# APPWEB - ESP API Native API

# Components

Edi | Database structure.
EdiField | EDI Record field structure.
EdiGrid | Grid structure.
EdiRec | Database record structure.
EdiService | Edi service control structure.
EspAbbrev | Abbreviated ESP Controls.
EspControl | There are two groups of ESP Control APIs.
EspParse | ESP page parser structure.
EspReq | ESP request.
EspRoute | EspRoute extended route configuration.
EspSession | ESP session state object.

# Functions

void | addHeader(cchar *key, cchar *fmt, ...)
| Add a header to the transmission using a format string.
void | alert(cchar *text, cchar *options)
| Display a popup alert message in the client's browser when the web page is displayed.
void | anchor(cchar *text, cchar *uri, cchar *options)
| Render an HTML anchor link.
void | button(cchar *text, cchar *value, cchar *options)
| Render an HTML button to use inside a form.
void | buttonLink(cchar *text, cchar *uri, cchar *options)
| Render an HTML button to use outside a form.
void | chart(EdiGrid *grid, cchar *options)
| Render a graphic chart.
void | checkbox(cchar *field, cchar *checkedValue, cchar *options)
| Render an input checkbox.
EdiRec* | createRec(cchar *tableName, MprHash *data)
| Create a record and initialize field values.
void | createSession()
| Create a session state object.
void | destroySession()
| Destroy a session state object.
void | division(cchar *body, cchar *options)
| Render an HTML division.
void | dontAutoFinalize()
| Don't auto-finalize this request.
void | dropdown(cchar *field, cchar *choices, cchar *options)
| Render a dropdown selection list.
EdiRec* | eReadRecByKey(cchar *tableName, cchar *key)
| Read a record identified by the key value.
int | edRemoveColumn(Edi *edi, cchar *tableName, cchar *columnName)
| Remove a column from a table.
int | ediAddColumn(Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)
| Add a column to a table.
int | ediAddIndex(Edi *edi, cchar *tableName, cchar *columnName, cchar *indexName)
| Add an index to a table.
void | ediAddProvider(struct EdiProvider *provider)
| Add a database provider.
int | ediAddTable(Edi *edi, cchar *tableName)
| Add a table to a database.
int | ediAddValidation(Edi *edi, cchar *name, cchar *tableName, cchar *columnName, cvoid *data)
| Add a validation.
int | ediChangeColumn(Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)
| Change a column schema definition.
void | ediClose(Edi *edi)
| Close a database.
EdiGrid* | ediCreateBareGrid(Edi *edi, cchar *tableName, int nrows)
| Create a bare grid.
EdiRec* | ediCreateBareRec(Edi *edi, cchar *tableName, int nfields)
| Create a bare record.
EdiRec* | ediCreateRec(Edi *edi, cchar *tableName)
| Create a record.
EdiService* | ediCreateService()
| Create the EDI service.
void | ediDefineValidation(cchar *name, EdiValidationProc vfn)
| Define a field validation procedure.
int | ediDelete(Edi *edi, cchar *path)
| Delete the database at the given path.
int | ediDeleteRow(Edi *edi, cchar *tableName, cchar *key)
| Delete a row in a database table.
cchar* | ediFormatField(cchar *fmt, EdiField value)
| Format a field value.
int | ediGetColumnSchema(Edi *edi, cchar *tableName, cchar *columnName, int *type, int *flags, int *cid)
| Get the column schema.
MprList* | ediGetColumns(Edi *edi, cchar *tableName)
| Get a list of column names.
cchar* | ediGetField(EdiRec *rec, cchar *fieldName)
| Get a record field.
cchar* | ediGetFieldFmt(cchar *fmt, EdiRec *rec, cchar *fieldName)
| Get and format a record field value.
EdiField | ediGetFieldSchema(EdiRec *rec, cchar *fieldName)
| Get the record field schema.
int | ediGetFieldType(EdiRec *rec, cchar *fieldName)
| Get the data type of a record field.
MprList* | ediGetGridColumns(EdiGrid *grid)
| Get a list of grid column names.
MprList* | ediGetRecErrors(EdiRec *rec)
| Get record validation errors.
int | ediGetTableSchema(Edi *edi, cchar *tableName, int *numRows, int *numCols)
| Get table schema information.
MprList* | ediGetTables(Edi *edi)
| Get a list of database tables.
char* | ediGetTypeString(int type)
| Convert an EDI type to a string.
int | ediLoad(Edi *edi, cchar *path)
| MOB - remove this API Load the database file.
int | ediLookupField(Edi *edi, cchar *tableName, cchar *fieldName)
| Lookup a field by name.
EdiGrid* | ediMakeGrid(cchar *content)
| Make a grid.
MprHash* | ediMakeHash(cchar *fmt, ...)
| Make a hash container of property values.
EdiRec* | ediMakeRec(cchar *content)
| Make a record.
void | ediManageEdiRec(EdiRec *rec, int flags)
| Manage an EdiRec instance for garbage collection.
Edi* | ediOpen(cchar *source, cchar *provider, int flags)
| Open a database.
int | ediParseTypeString(cchar *type)
| Parse an EDI type string.
EdiGrid* | ediQuery(Edi *edi, cchar *cmd)
| Run a query.
cchar* | ediReadField(Edi *edi, cchar *fmt, cchar *tableName, cchar *key, cchar *fieldName, cchar *defaultValue)
| Read a field from the database and format the result.
EdiRec* | ediReadOneWhere(Edi *edi, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)
| Read one record.
EdiField | ediReadRawField(Edi *edi, cchar *tableName, cchar *key, cchar *fieldName)
| Read a field from the database.
EdiRec* | ediReadRec(Edi *edi, cchar *tableName, cchar *key)
| Read a record.
EdiGrid* | ediReadTable(Edi *edi, cchar *tableName)
| Read a table.
EdiGrid* | ediReadWhere(Edi *edi, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)
| Read matching records.
int | ediRemoveIndex(Edi *edi, cchar *tableName, cchar *indexName)
| Remove a table index.
int | ediRemoveTable(Edi *edi, cchar *tableName)
| Remove a table from the database.
int | ediRenameColumn(Edi *edi, cchar *tableName, cchar *columnName, cchar *newColumnName)
| Rename a column.
int | ediRenameTable(Edi *edi, cchar *tableName, cchar *newTableName)
| Rename a table.
int | ediSave(Edi *edi)
| Save in-memory database contents to disk.
EdiRec* | ediSetField(EdiRec *rec, cchar *fieldName, cchar *value)
| Set a record field without writing to the database.
EdiRec* | ediSetFields(EdiRec *rec, MprHash *data)
| Set record fields without writing to the database.
int | ediUpdateField(Edi *edi, cchar *tableName, cchar *key, cchar *fieldName, cchar *value)
| Write a value to a database table field.
int | ediUpdateRec(Edi *edi, EdiRec *rec)
| Write a record to the database.
bool | ediValidateRec(EdiRec *rec)
| Validate a record.
void | endform()
| Signify the end of an HTML form.
void | espAddHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
| Add a header to the transmission using a format string.
void | espAddHeaderString(HttpConn *conn, cchar *key, cchar *value)
| Add a header to the transmission.
void | espAlert(HttpConn *conn, cchar *text, cchar *options)
| Display a popup alert message in the client's browser when the web page is displayed.
EspSession* | espAllocSession(HttpConn *conn, cchar *id, MprTime lifespan)
| Allocate a new session state object.
void | espAnchor(HttpConn *conn, cchar *text, cchar *uri, cchar *options)
| Render an HTML anchor link.
void | espAppendHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
| Append a transmission header.
void | espAppendHeaderString(HttpConn *conn, cchar *key, cchar *value)
| Append a transmission header string.
void | espAutoFinalize(HttpConn *conn)
| Auto-finalize transmission of the http request.
char* | espBuildScript(HttpRoute *route, cchar *page, cchar *path, cchar *cacheName, cchar *layout, char **err)
| Convert an ESP web page into compilable C code.
void | espButton(HttpConn *conn, cchar *text, cchar *value, cchar *options)
| Render an HTML button to use inside a form.
void | espButtonLink(HttpConn *conn, cchar *text, cchar *uri, cchar *options)
| Render an HTML button to use outside a form.
int | espCache(HttpRoute *route, cchar *uri, int lifesecs, int flags)
| Add caching for response content.
void | espChart(HttpConn *conn, EdiGrid *grid, cchar *options)
| Render a graphic chart.
bool | espCheckSecurityToken(HttpConn *conn)
| Check a security token.
void | espCheckbox(HttpConn *conn, cchar *name, cchar *checkedValue, cchar *options)
| Render an input checkbox.
bool | espCompile(HttpConn *conn, cchar *source, cchar *module, cchar *cacheName, int isView)
| Compile a view or controller.
EdiRec* | espCreateRec(HttpConn *conn, cchar *tableName, MprHash *data)
| Create a record and initialize field values.
EspSession* | espCreateSession(HttpConn *conn)
| Create a session object.
void | espDefineAction(HttpRoute *route, cchar *targetKey, void *actionProc)
| Define an action.
void | espDefineBase(HttpRoute *route, EspProc baseProc)
| Define a base function to invoke for all controller actions.
void | espDefineView(HttpRoute *route, cchar *path, void *viewProc)
| Define a view.
void | espDestroySession(EspSession *sp)
| Destroy a session state object.
void | espDivision(HttpConn *conn, cchar *body, cchar *options)
| Render an HTML division.
void | espDropdown(HttpConn *conn, cchar *field, cchar *choices, cchar *options)
| Render a dropdown selection list.
void | espEndform(HttpConn *conn)
| Signify the end of an HTML form.
char* | espExpandCommand(cchar *command, cchar *source, cchar *module)
| Expand a compile or link command template.
void | espFinalize(HttpConn *conn)
| Finalize transmission of the http request.
void | espFlash(HttpConn *conn, cchar *kinds, cchar *options)
| Render flash messages.
void | espFlush(HttpConn *conn)
| Flush transmit data.
void | espForm(HttpConn *conn, EdiRec *record, cchar *options)
| Render an HTML form.
MprList* | espGetColumns(HttpConn *conn, EdiRec *rec)
| Get a list of column names.
HttpConn* | espGetConn()
| Get the current request connection.
MprOff | espGetContentLength(HttpConn *conn)
| Get the receive body content length.
cchar* | espGetContentType(HttpConn *conn)
| Get the receive body content type.
cchar* | espGetCookies(HttpConn *conn)
| Get the request cookies.
Edi* | espGetDatabase(HttpConn *conn)
| Get the current database instance.
cchar* | espGetDir(HttpConn *conn)
| Get the default document root directory for the request route.
EspRoute* | espGetEspRoute(HttpConn *conn)
| Get the current extended route information.
cchar* | espGetFlashMessage(HttpConn *conn, cchar *type)
| Get a flash message.
EdiGrid* | espGetGrid(HttpConn *conn)
| Get the current database grid.
cchar* | espGetHeader(HttpConn *conn, cchar *key)
| Get an rx http header.
MprHash* | espGetHeaderHash(HttpConn *conn)
| Get the hash table of rx Http headers.
char* | espGetHeaders(HttpConn *conn)
| Get all the request http headers.
int | espGetIntParam(HttpConn *conn, cchar *var, int defaultValue)
| Get a request pararmeter as an integer.
cchar* | espGetMethod(HttpConn *conn)
| Get the HTTP method.
cchar* | espGetParam(HttpConn *conn, cchar *var, cchar *defaultValue)
| Get a request parameter.
MprHash* | espGetParams(HttpConn *conn)
| Get the request parameter hash table.
cchar* | espGetQueryString(HttpConn *conn)
| Get the request query string.
char* | espGetReferrer(HttpConn *conn)
| Get the referring URI.
Edi* | espGetRouteDatabase(HttpRoute *route)
| Get the default database defined on a route.
cchar* | espGetSecurityToken(HttpConn *conn)
| Get a unique security token.
EspSession* | espGetSession(HttpConn *conn, int create)
| Get a session state object.
char* | espGetSessionID(HttpConn *conn)
| Get the session ID.
MprHash* | espGetSessionObj(HttpConn *conn, cchar *key)
| Get an object from the session state store.
cchar* | espGetSessionVar(HttpConn *conn, cchar *name, cchar *defaultValue)
| Get a session state variable.
int | espGetStatus(HttpConn *conn)
| Get the response status.
char* | espGetStatusMessage(HttpConn *conn)
| Get the Http response status message.
char* | espGetTop(HttpConn *conn)
| Get a relative URI to the top of the application.
MprHash* | espGetUploads(HttpConn *conn)
| Get the uploaded files.
cchar* | espGetUri(HttpConn *conn)
| Get the request URI string.
bool | espHasGrid(HttpConn *conn)
| Test if a current grid has been defined.
bool | espHasRec(HttpConn *conn)
| Test if a current record has been defined and save to the database.
void | espIcon(HttpConn *conn, cchar *uri, cchar *options)
| Render an HTML icon.
void | espImage(HttpConn *conn, cchar *uri, cchar *options)
| Render an HTML image.
void | espInput(HttpConn *conn, cchar *field, cchar *options)
| Render an input field as part of a form.
bool | espIsEof(HttpConn *conn)
| Test if the receive input stream is at end-of-file.
bool | espIsFinalized(HttpConn *conn)
| Test if a http request is finalized.
bool | espIsSecure(HttpConn *conn)
| Test if the connection is using SSL and is secure.
void | espLabel(HttpConn *conn, cchar *text, cchar *options)
| Render a text label field.
void | espMail(HttpConn *conn, cchar *name, cchar *address, cchar *options)
| Render a mail link.
EdiGrid* | espMakeGrid(cchar *content)
| Make a grid.
MprHash* | espMakeHash(cchar *fmt, ...)
| Make a hash table container of property values.
EdiRec* | espMakeRec(cchar *content)
| Make a record.
bool | espMatchParam(HttpConn *conn, cchar *var, cchar *value)
| Match a request parameter with an expected value.
void | espProgress(HttpConn *conn, cchar *progress, cchar *options)
| Emit a progress bar.
void | espRadio(HttpConn *conn, cchar *field, void *choices, cchar *options)
| Render a radio button.
EdiGrid* | espReadAllRecs(HttpConn *conn, cchar *tableName)
| Read all the records in table from the database.
EdiRec* | espReadRec(HttpConn *conn, cchar *tableName)
| Read the identified record.
EdiRec* | espReadRecWhere(HttpConn *conn, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)
| Read one record.
EdiGrid* | espReadRecsWhere(HttpConn *conn, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)
| Read matching records.
ssize | espReceive(HttpConn *conn, char *buf, ssize size)
| Read receive body content.
void | espRedirect(HttpConn *conn, int status, cchar *target)
| Redirect the client.
void | espRedirectBack(HttpConn *conn)
| Redirect the client back to the referrer.
void | espRefresh(HttpConn *conn, cchar *on, cchar *off, cchar *options)
| Control the refresh of web page dynamic elements.
int | espRemoveHeader(HttpConn *conn, cchar *key)
| Remove a header from the transmission.
bool | espRemoveRec(HttpConn *conn, cchar *tableName, cchar *key)
| Remove a record from a database table.
ssize | espRender(HttpConn *conn, cchar *fmt, ...)
| Render a formatted string.
ssize | espRenderBlock(HttpConn *conn, cchar *buf, ssize size)
| Render a block of data to the client.
ssize | espRenderCached(HttpConn *conn)
| Render cached content.
ssize | espRenderError(HttpConn *conn, int status, cchar *fmt, ...)
| Render an error message back to the client and finalize the request.
ssize | espRenderFile(HttpConn *conn, cchar *path)
| Render the contents of a file back to the client.
ssize | espRenderParam(HttpConn *conn, cchar *name)
| Render the value of a request parameter to the client.
ssize | espRenderSafeString(HttpConn *conn, cchar *s)
| Render a safe string of data to the client.
ssize | espRenderString(HttpConn *conn, cchar *s)
| Render a string of data to the client.
void | espRenderView(HttpConn *conn, cchar *name)
| Render a view template to the client.
void | espScript(HttpConn *conn, cchar *uri, cchar *options)
| Render a script link.
void | espSecurityToken(HttpConn *conn)
| Generate a security token.
bool | espSetAutoFinalizing(HttpConn *conn, bool on)
| Enable auto-finalizing for this request.
void | espSetConn(HttpConn *conn)
| Set the current request connection.
void | espSetContentLength(HttpConn *conn, MprOff length)
| Define a content length header in the transmission.
void | espSetContentType(HttpConn *conn, cchar *mimeType)
| Set the transmission (response) content mime type.
void | espSetCookie(HttpConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, MprTime lifespan, bool isSecure)
| Set a cookie in the transmission.
EdiRec* | espSetField(EdiRec *rec, cchar *fieldName, cchar *value)
| Update a record field without writing to the database.
EdiRec* | espSetFields(EdiRec *rec, MprHash *data)
| Update record fields without writing to the database.
void | espSetFlash(HttpConn *conn, cchar *kind, cchar *fmt, ...)
| Send a flash message.
void | espSetFlashv(HttpConn *conn, cchar *kind, cchar *fmt, va_list args)
| Send a flash message.
EdiGrid* | espSetGrid(HttpConn *conn, EdiGrid *grid)
| Set the current database grid.
void | espSetHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
| Set a transmission header.
void | espSetHeaderString(HttpConn *conn, cchar *key, cchar *value)
| Set a simple key/value transmission header.
void | espSetIntParam(HttpConn *conn, cchar *var, int value)
| Set an integer request parameter value.
void | espSetParam(HttpConn *conn, cchar *var, cchar *value)
| Set a request parameter value.
EdiRec* | espSetRec(HttpConn *conn, EdiRec *rec)
| Set the current database record.
int | espSetSessionObj(HttpConn *conn, cchar *key, MprHash *value)
| Set an object into the session state store.
int | espSetSessionVar(HttpConn *conn, cchar *name, cchar *value)
| Set a session variable.
void | espSetStatus(HttpConn *conn, int status)
| Set a Http response status.
void | espShowRequest(HttpConn *conn)
| Show request details.
void | espStylesheet(HttpConn *conn, cchar *uri, cchar *options)
| Render a stylesheet link.
void | espTable(HttpConn *conn, EdiGrid *grid, cchar *options)
| Render a table.
void | espTabs(HttpConn *conn, EdiRec *rec, cchar *options)
| Render a tab control.
void | espText(HttpConn *conn, cchar *field, cchar *options)
| Render a text input field as part of a form.
void | espTree(HttpConn *conn, EdiGrid *grid, cchar *options)
| Render a tree control.
void | espUpdateCache(HttpConn *conn, cchar *uri, cchar *data, int lifesecs)
| Update the cached content for a request.
bool | espUpdateField(HttpConn *conn, cchar *tableName, cchar *key, cchar *fieldName, cchar *value)
| Write a value to a database table field.
bool | espUpdateFields(HttpConn *conn, cchar *tableName, MprHash *data)
| Write field values to a database row.
bool | espUpdateRec(HttpConn *conn, EdiRec *rec)
| Write a record to the database.
cchar* | espUri(HttpConn *conn, cchar *target)
| Create a URI.
void | finalize()
| Finalize the response.
void | flash(cchar *kinds, cchar *options)
| Render flash notices.
void | flush()
| Flush transmit data.
void | form(void *record, cchar *options)
| Render an HTML form.
MprList* | getColumns(EdiRec *rec)
| Get a list of column names.
HttpConn* | getConn()
| Get the connection object.
MprOff | getContentLength()
| Get the receive body content length.
cchar* | getContentType()
| Get the receive body content type.
cchar* | getCookies()
| Get the request cookies.
Edi* | getDatabase()
| Get the current database instance.
cchar* | getDir()
| Get the default document root directory for the request route.
EspRoute* | getEspRoute()
| Get the extended route EspRoute structure.
cchar* | getField(cchar *field)
| Get a field from the current database record.
EdiGrid* | getGrid()
| Get the current database grid.
cchar* | getHeader(cchar *key)
| Get an rx http header.
cchar* | getMethod()
| Get the HTTP method.
cchar* | getQuery()
| Get the HTTP URI query string.
EdiRec* | getRec()
| Get the current database record.
cchar* | getReferrer()
| Get the referring URI.
cchar* | getSessionVar(cchar *name)
| Get a session state variable.
cchar* | getTop()
| Get a relative URI to the top of the application.
MprHash* | getUploads()
| Get the uploaded files.
cchar* | getUri()
| Get the request URI string.
bool | hasGrid()
| Test if a current grid has been defined.
bool | hasRec()
| Test if a current record has been defined and save to the database.
void | icon(cchar *uri, cchar *options)
| Render an HTML icon.
void | image(cchar *uri, cchar *options)
| Render an HTML image.
void | inform(cchar *fmt, ...)
| Set an informational flash notification message.
void | input(cchar *field, cchar *options)
| Render an input field as part of a form.
bool | isEof()
| Test if the receive input stream is at end-of-file.
bool | isFinalized()
| Test if a http request is finalized.
bool | isSecure()
| Test if the connection is using SSL and is secure.
void | label(cchar *text, cchar *options)
| Render a text label field.
void | mail(cchar *name, cchar *address, cchar *options)
| Render a mail link.
EdiGrid* | makeGrid(cchar *content)
| Make a grid.
MprHash* | makeHash(cchar *fmt, ...)
| Make a hash table container of property values.
EdiRec* | makeRec(cchar *content)
| Make a record.
void | notice(cchar *fmt, ...)
| Set an error flash notification message.
cchar* | param(cchar *name)
| Get a request parameter.
MprHash* | params()
| Get the request parameter hash table.
void | progress(cchar *progress, cchar *options)
| Emit a progress bar.
void | radio(cchar *field, void *choices, cchar *options)
| Render a radio button.
EdiRec* | readRec(cchar *tableName)
| Read the identified record.
EdiRec* | readRecByKey(cchar *tableName, cchar *key)
| Read a record identified by key value.
EdiRec* | readRecWhere(cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)
| Read one record.
EdiGrid* | readRecsWhere(cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)
| Read matching records.
EdiGrid* | readTable(cchar *tableName)
| Read all the records in table from the database.
ssize | receive(char *buf, ssize size)
| Read receive body content.
void | redirect(cchar *target)
| Redirect the client.
void | redirectBack()
| Redirect the client back to the referrer.
void | refresh(cchar *on, cchar *off, cchar *options)
| Control the refresh of web page dynamic elements.
bool | removeRec(cchar *tableName, cchar *key)
| Remove a record from a database table.
ssize | render(cchar *fmt, ...)
| Render a formatted string.
ssize | renderCached()
| Render cached content.
void | renderError(int status, cchar *fmt, ...)
| Render an error message back to the client and finalize the request.
ssize | renderFile(cchar *path)
| Render a file back to the client.
ssize | renderSafe(cchar *fmt, ...)
| Render a formatted string after HTML escaping.
void | renderView(cchar *view)
| Render a view template to the client.
void | script(cchar *uri, cchar *options)
| Render a script link.
void | securityToken()
| Generate a security token.
void | setConn(HttpConn *conn)
| Set the current request connection.
void | setContentType(cchar *mimeType)
| Set the transmission (response) content mime type.
void | setCookie(cchar *name, cchar *value, cchar *path, cchar *domain, MprTime lifespan, bool isSecure)
| Define a cookie header to send with the response.
EdiRec* | setField(EdiRec *rec, cchar *fieldName, cchar *value)
| Update a record field without writing to the database.
EdiRec* | setFields(EdiRec *rec, MprHash *data)
| Update record fields without writing to the database.
void | setFlash(cchar *kind, cchar *fmt, ...)
| Set a flash notification message.
EdiGrid* | setGrid(EdiGrid *grid)
| Set the current database grid.
void | setHeader(cchar *key, cchar *fmt, ...)
| Set a transmission header.
void | setParam(cchar *name, cchar *value)
| Set a request parameter value.
EdiRec* | setRec(EdiRec *rec)
| Set the current database record.
void | setSessionVar(cchar *name, cchar *value)
| Set a session state variable.
void | setStatus(int status)
| Set a Http response status.
void | setTimeout(void *proc, MprTime timeout, void *data)
| Create a timeout event.
void | showRequest()
| Show request details.
void | stylesheet(cchar *uri, cchar *options)
| Render a stylesheet link.
void | table(EdiGrid *grid, cchar *options)
| Render a table.
void | tabs(EdiRec *rec, cchar *options)
| Render a tab control.
void | text(cchar *field, cchar *options)
| Render a text input field as part of a form.
void | tree(EdiGrid *grid, cchar *options)
| Render a tree control.
void | updateCache(cchar *uri, cchar *data, int lifesecs)
| Update the cached content for a request.
bool | updateField(cchar *tableName, cchar *key, cchar *fieldName, cchar *value)
| Write a value to a database table field.
bool | updateFields(cchar *tableName, MprHash *data)
| Write field values to a database row.
bool | updateRec(EdiRec *rec)
| Write a record to the database.
cchar* | uri(cchar *target)
| Create a URI.

# Typedefs

EdiProvider | Database provider interface.
EdiValidation | Validation structure.
EdiValidationProc | Field validation callback procedure.
Esp | Top level ESP structure.
EspAction | ESP Action.
EspProc | Procedure callback.
EspViewProc | View procedure callback.

# Defines

#define | EDI_AUTO_INC 0x1
| Field flag — Automatic increments on new row.
#define | EDI_AUTO_SAVE 0x2
| Auto-save database if modified in memory.
#define | EDI_CREATE 0x1
| Create database if not present.
#define | EDI_INDEX 0x4
| Field flag — Column is indexed.
#define | EDI_KEY 0x2
| Field flag — Column is the key.
#define | EDI_LITERAL 0x8
| Literal schema in ediOpen source parameter.
#define | EDI_NO_SAVE 0x4
| Prevent saving to disk.
#define | EDI_SUPPRESS_SAVE 0x10
| Temporarily suppress auto-save.
#define | EDI_TYPE_BINARY 1
| Arbitrary binary data.
#define | EDI_TYPE_BOOL 2
| Boolean true|false value.
#define | EDI_TYPE_DATE 3
| Date type.
#define | EDI_TYPE_FLOAT 4
| Floating point number.
#define | EDI_TYPE_INT 5
| Integer number.
#define | EDI_TYPE_STRING 6
| String.
#define | EDI_TYPE_TEXT 7
| Multi-line text.
#define | ESP_LIFESPAN (3600 * MPR_TICKS_PER_SEC)
| Default generated content cache lifespan.
#define | ESP_LISTEN "4000"
| Default listening endpoint for the esp program.
#define | ESP_TOK_INCR 1024
| Growth increment for ESP tokens.
#define | ESP_UNLOAD_TIMEOUT (10)
| Very short timeout for reloading.

# Edi

Edi

Database structure.

Description:
  The Embedded Database Interface (EDI) defines an abstract interface atop various relational database providers. Providers are supplied for SQLite and for the ESP Memory Database (MDB).

Fields:

  int |  | flags | Database flags.
  struct EdiProvider * |  | provider | Database provider.

int ediAddColumn (Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)

Add a column to a table.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  columnName | Database column name.
  type | Column data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.
  flags | Control column attributes. Set to a set of: EDI_AUTO_INC for auto incrementing columns, EDI_KEY if the column is the key column and/or EDI_INDEX to create an index on the column.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediAddIndex (Edi *edi, cchar *tableName, cchar *columnName, cchar *indexName)

Add an index to a table.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  columnName | Database column name.
  indexName | Ignored. Set to null.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediAddTable (Edi *edi, cchar *tableName)

Add a table to a database.

Parameters:

  edi | Database handle.
  tableName | Database table name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediAddValidation (Edi *edi, cchar *name, cchar *tableName, cchar *columnName, cvoid *data)

Add a validation.

Description:
  Validations are run when calling ediUpdateRec. A validation is used to validate field data using builtin validators.

Parameters:

  edi | Database handle.

  name

  Validation name. Select from:
  - boolean — to validate field data as "true" or "false"
  - date — to validate field data as a date or time.
  - format — to validate field data against a regular expression supplied in the "data" argument
  - integer — to validate field data as an integral value
  - number — to validate field data as a number. It may be an integer or floating point number.
  - present — to validate field data as not null.
  - unique — to validate field data as being unique in the database table.

  tableName | Database table name.
  columnName | Database column name.
  data | Argument data for the validator. For example: the "format" validator requires a regular expression.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediChangeColumn (Edi *edi, cchar *tableName, cchar *columnName, int type, int flags)

Change a column schema definition.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  columnName | Database column name.
  type | Column data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.
  flags | Control column attributes. Set to a set of: EDI_AUTO_INC for auto incrementing columns, EDI_KEY if the column is the key column and/or EDI_INDEX to create an index on the column.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

void ediClose (Edi *edi)

Close a database.

Parameters:

  edi | Database handle.

See Also:

EdiGrid * ediCreateBareGrid (Edi *edi, cchar *tableName, int nrows)

Create a bare grid.

Description:
  This creates an empty grid based on the given table's schema.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  nrows | Number of rows to reserve in the grid.

Returns:
  EdiGrid instance.

See Also:

EdiRec * ediCreateBareRec (Edi *edi, cchar *tableName, int nfields)

Create a bare record.

Description:
  This creates an empty record based on the given table's schema.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  nfields | Number of fields to reserve in the record.

Returns:
  EdiGrid instance.

See Also:

EdiRec * ediCreateRec (Edi *edi, cchar *tableName)

Create a record.

Description:
  This will create a record using the given database tableName to supply the record schema. Use $ediCreateBareRec to create a free-standing record without requiring a database. The record is allocated and room is reserved to store record values. No record field values are stored.

Parameters:

  edi | Database handle.
  tableName | Database table name.

Returns:
  Record instance.

See Also:

int ediDelete (Edi *edi, cchar *path)

Delete the database at the given path.

Parameters:

  edi | Database handle. This is required to identify the database provider. The database should be closed before deleting.
  path | Database path name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediDeleteRow (Edi *edi, cchar *tableName, cchar *key)

Delete a row in a database table.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  key | Row key column value to delete.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

cchar * ediFormatField (cchar *fmt, EdiField value)

Format a field value.

Parameters:

  fmt | Printf style format string.
  value | Field value.

Returns:
  Formatted value string.

See Also:

MprList * ediGetColumns (Edi *edi, cchar *tableName)

Get a list of column names.

Parameters:

  edi | Database handle.
  tableName | Database table name.

Returns:
  An MprList of column names in the given table.

See Also:

int ediGetColumnSchema (Edi *edi, cchar *tableName, cchar *columnName, int *type, int *flags, int *cid)

Get the column schema.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  columnName | Database column name.
  type | Output parameter to receive the column data type. Will be set to one of: EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE, EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT. Set to null if this data is not required.
  flags | Output parameter to receive the column control flags. Will be set to one or more of: EDI_AUTO_INC, EDI_KEY and/or EDI_INDEX Set to null if this data is not required.
  cid | Output parameter to receive the ordinal column index in the database table. Set to null if this data is not required.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

cchar * ediGetField (EdiRec *rec, cchar *fieldName)

Get a record field.

Parameters:

  rec | Database record.
  fieldName | Field in the record to extract.

Returns:
  An EdiField structure containing the record field value and details.

See Also:

cchar * ediGetFieldFmt (cchar *fmt, EdiRec *rec, cchar *fieldName)

Get and format a record field value.

Parameters:

  fmt | Record field value.
  rec | Record to examine.
  fieldName | Record field to examine.

Returns:
  String value of the field.

See Also:

EdiField ediGetFieldSchema (EdiRec *rec, cchar *fieldName)

Get the record field schema.

Description:
  This returns the actual EdiField which contains the field name, type, value and flags.

Parameters:

  rec | Database record.
  fieldName | Field in the record to extract.

Returns:
  An EdiField structure containing the record field value and details.

See Also:

int ediGetFieldType (EdiRec *rec, cchar *fieldName)

Get the data type of a record field.

Parameters:

  rec | Record to examine.
  fieldName | Field to examine.

Returns:
  The field type. Returns one of: EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE, EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.

See Also:

MprList * ediGetGridColumns (EdiGrid *grid)

Get a list of grid column names.

Parameters:

  grid | Database grid.

Returns:
  An MprList of column names in the given grid.

See Also:

MprList * ediGetRecErrors (EdiRec *rec)

Get record validation errors.

Parameters:

  rec | Database record.

Returns:
  A list of validation errors. If validation passed, then this call returns NULL.

See Also:

MprList * ediGetTables (Edi *edi)

Get a list of database tables.

Parameters:

  edi | Database handle.

Returns:
  An MprList of table names in the database.

See Also:

int ediGetTableSchema (Edi *edi, cchar *tableName, int *numRows, int *numCols)

Get table schema information.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  numRows | Output parameter to receive the number of rows in the table Set to null if this data is not required.
  numCols | Output parameter to receive the number of columns in the table Set to null if this data is not required.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

char * ediGetTypeString (int type)

Convert an EDI type to a string.

Parameters:

  type | Column data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.

Returns:
  Type string. This will be set to one of: "binary", "bool", "date", "float", "int", "string" or "text".

See Also:

int ediLoad (Edi *edi, cchar *path)

MOB - remove this API Load the database file.

Parameters:

  edi | Database handle.
  path | Database path name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediLookupField (Edi *edi, cchar *tableName, cchar *fieldName)

Lookup a field by name.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  fieldName | Database column name.

Returns:
  The ordinal field (column) index in the table.

See Also:

EdiGrid * ediMakeGrid (cchar *content)

Make a grid.

Description:
  This call makes a free-standing data grid based on the JSON format content string.

Parameters:

  content | JSON format content string. The content should be an array of objects where each object is a set of property names and values.

Returns:
  An EdiGrid instance.

Example:
  : grid = ediMakeGrid("[ \
  { id: '1', country: 'Australia' }, \
  { id: '2', country: 'China' }, \
  ]");.

See Also:

MprHash * ediMakeHash (cchar *fmt, ...)

Make a hash container of property values.

Description:
  This routine formats the given arguments, parses the result as a JSON string and returns an equivalent hash of property values. The result after formatting should be of the form: ediMakeHash("{ key: 'value', key2: 'value', key3: 'value' }");.

Parameters:

  fmt | Printf style format string.
  ... | arguments.

Returns:
  MprHash instance.

See Also:

EdiRec * ediMakeRec (cchar *content)

Make a record.

Description:
  This call makes a free-standing data record based on the JSON format content string.

Parameters:

  content | JSON format content string. The content should be a set of property names and values.

Returns:
  An EdiRec instance.

Example:
  : rec = ediMakeRec("{ id: 1, title: 'Message One', body: 'Line one' }");.

See Also:

void ediManageEdiRec (EdiRec *rec, int flags)

Manage an EdiRec instance for garbage collection.

Parameters:

  rec | Record instance.
  flags | GC management flag.

See Also:

Edi * ediOpen (cchar *source, cchar *provider, int flags)

Open a database.

Description:
  This opens a database using the specified database provider.

Parameters:

  source | Database path name. If using the "mdb" provider with the EDI_LITERAL flag, then the source argument can be set to a literal JSON database content string.
  provider | Database provider. Set to "mdb" for the Memory Database or "sqlite" for the SQLite provider.

  flags

  Set to:
  - EDI_CREATE — Create database if not present.
  - EDI_AUTO_SAVE — Auto-save database if modified in memory. This option is only supported by the "mdb" provider.
  - EDI_NO_SAVE — Prevent saving to disk. This option is only supported by the "mdb" provider.
  - EDI_LITERAL — Literal schema in ediOpen source parameter. This option is only supported by the "mdb" provider.

Returns:
  If successful, returns an EDI database instance object. Otherwise returns zero.

See Also:

int ediParseTypeString (cchar *type)

Parse an EDI type string.

Parameters:

  type | Type string set to one of: "binary", "bool", "date", "float", "int", "string" or "text".

Returns:
  Type code. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE, EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.

See Also:

EdiGrid * ediQuery (Edi *edi, cchar *cmd)

Run a query.

Description:
  This runs a provider dependant query. For the SQLite provider, this runs an SQL statement. The "mdb" provider does not implement this API. To do queries using the "mdb" provider, use: $ediReadRec, $ediReadOneWhere, $ediReadWhere, $ediReadField and $ediReadTable.

Parameters:

  edi | Database handle.
  cmd | Query command to execute.

Returns:
  If succesful, returns tabular data in the form of an EgiGrid structure. Returns NULL on errors.

See Also:

cchar * ediReadField (Edi *edi, cchar *fmt, cchar *tableName, cchar *key, cchar *fieldName, cchar *defaultValue)

Read a field from the database and format the result.

Description:
  This reads a field from the database and formats the result using an optional format string. If the field has a null or empty value, the supplied defaultValue will be returned.

Parameters:

  edi | Database handle.
  fmt | Printf style format string to use in formatting the result.
  tableName | Database table name.
  key | Row key column value to read.
  fieldName | Column name to read.
  defaultValue | Default value to return if the field is null or empty.

Returns:
  Field value or default value if field is null or empty. Returns null if no matching record is found.

See Also:

EdiRec * ediReadOneWhere (Edi *edi, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read one record.

Description:
  This runs a simple query on the database and selects the first matching record. The query selects a row that has a "field" that matches the given "value".

Parameters:

  edi | Database handle.
  tableName | Database table name.
  fieldName | Database field name to evaluate.
  operation | Comparision operation. Set to "==", "!=", "<", ">", "<=" or ">=".
  value | Data value to compare with the field values.

Returns:
  First matching record. Returns NULL if no matching records.

See Also:

EdiField ediReadRawField (Edi *edi, cchar *tableName, cchar *key, cchar *fieldName)

Read a field from the database.

Description:
  This reads a field from the database.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  key | Row key column value to read.
  fieldName | Column name to read.

Returns:
  Field value or null if the no record is found. May return null or empty if the field is null or empty.

See Also:

EdiRec * ediReadRec (Edi *edi, cchar *tableName, cchar *key)

Read a record.

Description:
  Read a record from the given table as identified by the key value.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  key | Key value of the record to read.

Returns:
  Record instance of EdiRec.

See Also:

EdiGrid * ediReadTable (Edi *edi, cchar *tableName)

Read a table.

Description:
  This reads all the records in a table and returns a grid containing the results.

Parameters:

  edi | Database handle.
  tableName | Database table name.

Returns:
  A grid containing all records. Returns NULL if no matching records.

See Also:

EdiGrid * ediReadWhere (Edi *edi, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read matching records.

Description:
  This runs a simple query on the database and returns matching records in a grid. The query selects all rows that have a "field" that matches the given "value".

Parameters:

  edi | Database handle.
  tableName | Database table name.
  fieldName | Database field name to evaluate.
  operation | Comparision operation. Set to "==", "!=", "<", ">", "<=" or ">=".
  value | Data value to compare with the field values.

Returns:
  A grid containing all matching records. Returns NULL if no matching records.

See Also:

int ediRemoveIndex (Edi *edi, cchar *tableName, cchar *indexName)

Remove a table index.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  indexName | Ignored. Set to null. This call will remove the table index.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediRemoveTable (Edi *edi, cchar *tableName)

Remove a table from the database.

Parameters:

  edi | Database handle.
  tableName | Database table name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediRenameColumn (Edi *edi, cchar *tableName, cchar *columnName, cchar *newColumnName)

Rename a column.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  columnName | Database column name.
  newColumnName | New column name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediRenameTable (Edi *edi, cchar *tableName, cchar *newTableName)

Rename a table.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  newTableName | New database table name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediSave (Edi *edi)

Save in-memory database contents to disk.

Description:
  How this call behaves is provider dependant. If the provider is "mdb" and the database is not opened with AutoSave, then this call will save the in-memory contents. If the "mdb" database is opened with AutoSave, then this call will do nothing. For the "sdb" SQLite provider, this call does nothing.

Parameters:

  edi | Database handle.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

EdiRec * ediSetField (EdiRec *rec, cchar *fieldName, cchar *value)

Set a record field without writing to the database.

Description:
  This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use $ediUpdateRec.

Parameters:

  rec | Record to update.
  fieldName | Record field name to update.
  value | Value to update.

Returns:
  The record instance if successful, otherwise NULL.

See Also:

EdiRec * ediSetFields (EdiRec *rec, MprHash *data)

Set record fields without writing to the database.

Description:
  This routine updates the record object with the given values. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request $params() or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: ediSetFields(rec, ediMakeHash("{ name: '%s', address: '%s' }", name, address)) The record will not be written to the database. To write to the database, use $ediUpdateRec.

Parameters:

  rec | Record to update.
  data | Hash of field names and values to use for the update.

Returns:
  The record instance if successful, otherwise NULL.

See Also:

int ediUpdateField (Edi *edi, cchar *tableName, cchar *key, cchar *fieldName, cchar *value)

Write a value to a database table field.

Description:
  Update the value of a table field in the selected table row. Note: field validations are not run.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  key | Key value for the table row to update.
  fieldName | Column name to update.
  value | Value to write to the database field.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

int ediUpdateRec (Edi *edi, EdiRec *rec)

Write a record to the database.

Description:
  If the record is a new record and the "id" column is EDI_AUTO_INC, then the "id" will be assigned prior to saving the record.

Parameters:

  edi | Database handle.
  rec | Record to write to the database.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

bool ediValidateRec (EdiRec *rec)

Validate a record.

Description:
  Run defined field validations and return true if the record validates. Field validations are defined via $ediAddValidation calls. If any validations fail, error messages will be added to the record and can be retrieved via $ediGetRecErrors.

Parameters:

  rec | Record to validate.

Returns:
  True if all field valiations pass.

See Also:

int edRemoveColumn (Edi *edi, cchar *tableName, cchar *columnName)

Remove a column from a table.

Parameters:

  edi | Database handle.
  tableName | Database table name.
  columnName | Database column name.

Returns:
  Zero if successful. Otherwise a negative MPR error code.

See Also:

# EdiField

EdiField

EDI Record field structure.

Description:
  The EdiField stores record field data and minimal schema information such as the data type and source column name.

Fields:

  int |  | flags | Field flags. Flag mask set to EDI_AUTO_INC, EDI_KEY and/or EDI_INDEX.
  cchar * |  | name | Field name. Sourced from the database column name.
  int |  | type | Field data type. Set to one of EDI_TYPE_BINARY, EDI_TYPE_BOOL, EDI_TYPE_DATE EDI_TYPE_FLOAT, EDI_TYPE_INT, EDI_TYPE_STRING, EDI_TYPE_TEXT.
  int |  | valid | Field validity. Set to true if valid.
  cchar * |  | value | Field data value.

# EdiGrid

EdiGrid

Grid structure.

Description:
  A grid is a tabular (grid) of rows and records. Grids may capture database table data, or may be free-standing without a backing database.

Fields:

  struct Edi * |  | edi | Database handle.
  int |  | nrecords | Number of records in grid.
  EdiRec * |  | records[MPR_FLEX] | Grid records.
  cchar * |  | tableName | Base table name for grid.

# EdiRec

EdiRec

Database record structure.

Description:
  Records may capture database row data, or may be free-standing without a backing database.

Fields:

  struct Edi * |  | edi | Database handle.
  MprList * |  | errors | List of record errors.
  EdiField |  | fields[MPR_FLEX] | Field records.
  cchar * |  | id | Record key ID.
  int |  | nfields | Number of fields in record.
  cchar * |  | tableName | Base table name for record.

# EdiService

EdiService

Edi service control structure.

Fields:

void ediAddProvider (struct EdiProvider *provider)

Add a database provider.

Description:
  This should only be called by database providers.

See Also:

EdiService * ediCreateService ()

Create the EDI service.

Returns:
  EdiService object.

See Also:

void ediDefineValidation (cchar *name, EdiValidationProc vfn)

Define a field validation procedure.

Parameters:

  name | Validation name.
  vfn | Validation callback to invoke when validating field data.

See Also:

# EspAbbrev

EspAbbrev

Abbreviated ESP Controls.

Description:
  These controls do not take a HttpConn argument and determine the connection object from thread-local storage.

API Stability:
  Prototype.

See Also:
  espAlert

Fields:

void addHeader (cchar *key, cchar *fmt, ...)

Add a header to the transmission using a format string.

Description:
  Add a header if it does not already exist.

Parameters:

  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

Returns:
  Zero if successful, otherwise a negative MPR error code. Returns MPR_ERR_ALREADY_EXISTS if the header already exists.

See Also:
  espAlert

void alert (cchar *text, cchar *options)

Display a popup alert message in the client's browser when the web page is displayed.

Parameters:

  text | Alert text to display.

  options

  Extra options. See $EspControl for a list of the standard options.
  - Polling period in milliseconds for the client to check the server for status message updates. If this is not specifed, the connection to the server will be kept open. This permits the server to "push" alerts to the console, but will consume a connection at the server for each client.

See Also:
  espAlert

void anchor (cchar *text, cchar *uri, cchar *options)

Render an HTML anchor link.

Description:
  This is emits a label inside an anchor reference. i.e. a clickable link.

Parameters:

  text | Anchor text to display for the link.
  uri | URI link for the anchor.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void button (cchar *text, cchar *value, cchar *options)

Render an HTML button to use inside a form.

Description:
  This creates a button suitable for use inside an input form. When the button is clicked, the input form will be submitted.

Parameters:

  text | Button text to display. This text is also used as the name for the form input from this control.
  value | Form input value to submit when the button is clicked.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void buttonLink (cchar *text, cchar *uri, cchar *options)

Render an HTML button to use outside a form.

Parameters:

  text | Button text to display.
  uri | URI to invoke when the button is clicked.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void chart (EdiGrid *grid, cchar *options)

Render a graphic chart.

Description:
  The chart control can display static or dynamic tabular data. The client chart control manages sorting by column, dynamic data refreshes, pagination and clicking on rows. TODO. This is incomplete.

Parameters:

  grid | Data to display. The data is a grid of data. Use ediCreateGrid or ediReadGrid.

  options

  Extra options. See $EspControl for a list of the standard options.
  - columns Object hash of column entries. Each column entry is in-turn an object hash of options. If unset, all columns are displayed using defaults.
  - kind String Type of chart. Select from: piechart, table, linechart, annotatedtimeline, guage, map, motionchart, areachart, intensitymap, imageareachart, barchart, imagebarchart, bioheatmap, columnchart, linechart, imagelinechart, imagepiechart, scatterchart (and more)

See Also:
  espAlert

void checkbox (cchar *field, cchar *checkedValue, cchar *options)

Render an input checkbox.

Description:
  This creates a checkbox suitable for use within an input form.

Parameters:

  field | Name for the input checkbox. This defines the HTML element name and provides the source of the initial value for the checkbox. The field should be a property of the $espForm current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  checkedValue | Value for which the checkbox will be checked.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

EdiRec * createRec (cchar *tableName, MprHash *data)

Create a record and initialize field values.

Description:
  This will call $ediCreateRec to create a record based on the given table's schema. It will then call $ediSetFields to update the record with the given data.

Parameters:

  tableName | Database table name.
  data | Hash of field values.

Returns:
  EdRec instance.

See Also:
  espAlert

void createSession ()

Create a session state object.

Description:
  The session state object can be used to share state between requests. If a session has not already been created, this call will create a new session. It will create a response cookie containing a session ID that will be sent to the client with the response. Note: Objects are stored in the session state using JSON serialization. This routine calls $espCreateSession.

See Also:
  espAlert

void destroySession ()

Destroy a session state object.

Description:

See Also:
  espAlert

void division (cchar *body, cchar *options)

Render an HTML division.

Description:
  This creates an HTML element with the required options.It is useful to generate a dynamically refreshing division.

Parameters:

  body | HTML body to render.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void dontAutoFinalize ()

Don't auto-finalize this request.

See Also:
  espAlert

void dropdown (cchar *field, cchar *choices, cchar *options)

Render a dropdown selection list.

Parameters:

  field | Record field name to provide the default value for the list. The field should be a property of the form current record. The field name is used to create the HTML input control name. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  choices | Choices to select from. This is a JSON style set of properties. For example: espDropdown(conn, "priority", "{ low: 0, med: 1, high: 2 }", NULL).
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void finalize ()

Finalize the response.

Description:
  Signals the end of any and all response data and flushes any buffered write data to the client. If the request has already been finalized, this call has no additional effect. This routine calls $espFinalize.

See Also:
  espAlert

void flash (cchar *kinds, cchar *options)

Render flash notices.

Description:
  Flash notices are one-time messages that are displayed to the client on the next request (only). See $espSetFlash for how to define flash messages.

Parameters:

  kinds | Space separated list of flash messages types. Typical types are: "error", "inform", "warning".

  options

  Extra options. See $EspControl for a list of the standard options.
  - retain — Number of seconds to retain the message. If <= 0, the message is retained until another message is displayed. Default is 0. MOB - this default implies it is displayed for zero seconds

See Also:
  espAlert

void flush ()

Flush transmit data.

Description:
  This writes any buffered data.

See Also:
  espAlert

void form (void *record, cchar *options)

Render an HTML form.

Description:
  This will render an HTML form tag and optionally associate the given record as the current record for the request. Abbreviated controls (see $EspAbbrev) use the current record to supply form data fields and values. The espForm control can be used without a record. In this case, nested ESP controls may have to provide values via an Options.value field.

Parameters:

  record | Record to use by default to supply form field names and values.

  options

  Extra options. See $EspControl for a list of the standard options.
  - hideErrors — Don't display database record errors. Records retain error diagnostics from the previous failed write. Setting this option will prevent the display of such errors.
  - modal — Make the form a modal dialog. This will block all other HTML controls except the form.
  - insecure — Don't generate a security token for the form.
  - securityToken — String Override CSRF security token to include when the form is submitted. A default security token will always be generated unless options.insecure is defined to be true. Security tokens are used by ESP to mitigate cross site scripting errors.

See Also:
  espAlert

HttpConn * getConn ()

Get the connection object.

Description:
  Before a view or controller is run, the current connection object for the request is saved in thread local data. Most EspControl APIs take an HttpConn object as an argument.

Returns:
  HttpConn connection instance object.

See Also:
  espAlert

MprOff getContentLength ()

Get the receive body content length.

Description:
  Get the length of the receive body content (if any). This is used in servers to get the length of posted data and in clients to get the response body length.

Returns:
  A count of the response content data in bytes.

See Also:
  espAlert

cchar * getContentType ()

Get the receive body content type.

Description:
  Get the content mime type of the receive body content (if any).

Returns:
  Mime type of any receive content. Set to NULL if not posted data.

See Also:
  espAlert

cchar * getCookies ()

Get the request cookies.

Description:
  Get the cookies defined in the current request.

Returns:
  Return a string containing the cookies sent in the Http header of the last request.

See Also:
  espAlert

Edi * getDatabase ()

Get the current database instance.

Description:
  A route may have a default database configured via the EspDb Appweb.conf configuration directive. The database will be opened when the web server initializes and will be shared between all requests using the route.

Returns:
  Edi EDI database handle.

See Also:
  espAlert

cchar * getDir ()

Get the default document root directory for the request route.

Returns:
  A directory path name.

See Also:
  espAlert

EspRoute * getEspRoute ()

Get the extended route EspRoute structure.

Returns:
  EspRoute instance.

See Also:
  espAlert

cchar * getHeader (cchar *key)

Get an rx http header.

Description:
  Get a http response header for a given header key.

Parameters:

  key | Name of the header to retrieve. This should be a lower case header name. For example: "Connection".

Returns:
  Value associated with the header key or null if the key did not exist in the response.

See Also:
  espAlert

cchar * getQuery ()

Get the HTTP URI query string.

Description:
  This is a convenience API to return the query string for the current request.

Returns:
  The espGetConn()->rx->parsedUri->query property.

See Also:
  espAlert

cchar * getReferrer ()

Get the referring URI.

Description:
  This returns the referring URI as described in the HTTP "referer" (yes the HTTP specification does spell it incorrectly) header. If this header is not defined, this routine will return the home URI as returned by $home.

Returns:
  String URI back to the referring URI. If no referrer is defined, refers to the home URI.

See Also:
  espAlert

cchar * getSessionVar (cchar *name)

Get a session state variable.

Description:
  See also $espGetSessionVar and $espGetSessionObj for alternate ways to retrieve session data.

Parameters:

  name | Variable name to get.

Returns:
  The session variable value. Returns NULL if not set.

See Also:
  espAlert

cchar * getTop ()

Get a relative URI to the top of the application.

Description:
  This will return an absolute URI for the top of the application. This will be "/" if there is no application script name. Otherwise, it will return a URI for the script name for the application. Alternatively, this can be constructed via uri("~").

Returns:
  String Absolute URI to the top of the application.

See Also:
  espAlert

MprHash * getUploads ()

Get the uploaded files.

Description:
  Get the hash table defining the uploaded files. This hash is indexed by the file identifier supplied in the upload form. The hash entries are HttpUploadFile objects.

Returns:
  A hash of HttpUploadFile objects.

See Also:
  espAlert

cchar * getUri ()

Get the request URI string.

Description:
  This is a convenience API to return the request URI.

Returns:
  The espGetConn()->rx->uri.

See Also:
  espAlert

void icon (cchar *uri, cchar *options)

Render an HTML icon.

Parameters:

  uri | URI reference for the icon resource.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void image (cchar *uri, cchar *options)

Render an HTML image.

Parameters:

  uri | URI reference for the image resource.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void inform (cchar *fmt, ...)

Set an informational flash notification message.

Description:
  Flash messages persist for only one request and are a convenient way to pass state information or feedback messages to the next request. This routine calls $espInform.

Parameters:

  fmt | Printf style message format.

See Also:
  espAlert

void input (cchar *field, cchar *options)

Render an input field as part of a form.

This is a smart input control that will call the appropriate input control based on the database record field data type

Parameters:

  field | Name for the input field. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

bool isEof ()

Test if the receive input stream is at end-of-file.

Returns:
  "true" if there is no more receive data to read.

See Also:
  espAlert

bool isFinalized ()

Test if a http request is finalized.

Description:
  This tests if espFinalize or httpFinalize has been called for a request.

Returns:
  "true" if the request has been finalized.

See Also:
  espAlert

bool isSecure ()

Test if the connection is using SSL and is secure.

Returns:
  "true" if the connection is using SSL.

See Also:
  espAlert

void label (cchar *text, cchar *options)

Render a text label field.

This renders an output-only text field. Use espText() for input fields

Parameters:

  text | Label text to display.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void mail (cchar *name, cchar *address, cchar *options)

Render a mail link.

Parameters:

  name | Recipient name to display.
  address | Mail recipient address link.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

EdiGrid * makeGrid (cchar *content)

Make a grid.

Description:
  This call makes a free-standing data grid based on the JSON format content string. The record is not saved to the database.

Parameters:

  content | JSON format content string. The content should be an array of objects where each object is a set of property names and values.

Returns:
  An EdiGrid instance.

Example:
  : grid = ediMakeGrid("[ \
  { id: '1', country: 'Australia' }, \
  { id: '2', country: 'China' }, \
  ]");.

See Also:
  espAlert

MprHash * makeHash (cchar *fmt, ...)

Make a hash table container of property values.

Description:
  This routine formats the given arguments, parses the result as a JSON string and returns an equivalent hash of property values. The result after formatting should be of the form: hash("{ key: 'value', key2: 'value', key3: 'value' }");.

Parameters:

  fmt | Printf style format string.
  ... | arguments.

Returns:
  MprHash instance.

See Also:
  espAlert

EdiRec * makeRec (cchar *content)

Make a record.

Description:
  This call makes a free-standing data record based on the JSON format content string. The record is not saved to the database.

Parameters:

  content | JSON format content string. The content should be a set of property names and values.

Returns:
  An EdiRec instance.

Example:
  : rec = ediMakeRec("{ id: 1, title: 'Message One', body: 'Line one' }");.

See Also:
  espAlert

void notice (cchar *fmt, ...)

Set an error flash notification message.

Description:
  Flash messages persist for only one request and are a convenient way to pass state information or feedback messages to the next request.

Parameters:

  fmt | Printf style message format.

See Also:
  espAlert

cchar * param (cchar *name)

Get a request parameter.

Description:
  Get the value of a named request parameter. Form variables are defined via www-urlencoded query or post data contained in the request. This routine calls $espGetParam.

Parameters:

  name | Name of the request parameter to retrieve.

Returns:
  String containing the request parameter's value. Caller should not free.

See Also:
  espAlert

MprHash * params ()

Get the request parameter hash table.

Description:
  This call gets the params hash table for the current request. Route tokens, request query data, and www-url encoded form data are all entered into the params table after decoding. Use mprLookupKey to retrieve data from the table. This routine calls $espGetParams.

Returns:
  MprHash instance containing the request parameters.

See Also:
  espAlert

void progress (cchar *progress, cchar *options)

Emit a progress bar.

Parameters:

  progress | Progress percentage (0-100).
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void radio (cchar *field, void *choices, cchar *options)

Render a radio button.

This creates a radio button suitable for use within an input form

Parameters:

  field | Name for the input radio button. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  choices | Choices to select from. This is a JSON style set of properties. For example: espRadio(conn, "priority", "{ low: 0, med: 1, high: 2, }", NULL).
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

EdiRec * readRecByKey (cchar *tableName, cchar *key)

Read a record identified by key value.

Description:
  Read a record from the given table as identified by the key value.

Parameters:

  tableName | Database table name.
  key | Key value of the record to read.

Returns:
  Record instance of EdiRec.

See Also:
  espAlert

EdiRec * readRecWhere (cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read one record.

Description:
  This runs a simple query on the database and selects the first matching record. The query selects a row that has a "field" that matches the given "value".

Parameters:

  tableName | Database table name.
  fieldName | Database field name to evaluate.
  operation | Comparison operation. Set to "==", "!=", "<", ">", "<=" or ">=".
  value | Data value to compare with the field values.

Returns:
  First matching record. Returns NULL if no matching records.

See Also:
  espAlert

ssize receive (char *buf, ssize size)

Read receive body content.

Description:
  Read body content from the client.

Parameters:

  buf | Buffer to accept content data.
  size | Size of the buffer.

Returns:
  A count of bytes read into the buffer.

See Also:
  espAlert

void redirect (cchar *target)

Redirect the client.

Description:
  Redirect the client to a new uri. This will redirect with an HTTP 302 status. If a different HTTP status code is required, use $espRedirect.

Parameters:

  target | New target uri for the client.

See Also:
  espAlert

void redirectBack ()

Redirect the client back to the referrer.

Description:
  Redirect the client to the referring URI.

See Also:
  espAlert

void refresh (cchar *on, cchar *off, cchar *options)

Control the refresh of web page dynamic elements.

Parameters:

  on | URI to invoke when turning "on" refresh.
  off | URI to invoke when turning "off" refresh.

  options

  Extra options. See $EspControl for a list of the standard options.
  - minified Set to "ture" to select a minified (compressed) version of the script.

See Also:
  espAlert

ssize render (cchar *fmt, ...)

Render a formatted string.

Description:
  Render a formatted string of data into packets to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.

Parameters:

  fmt | Printf style formatted string.
  ... | Arguments for fmt.

Returns:
  A count of the bytes actually written.

See Also:
  espAlert

ssize renderCached ()

Render cached content.

Description:
  Render the saved, cached response from a prior request to this URI. This is useful if the caching mode has been set to "manual".

Returns:
  A count of the bytes actually written.

See Also:
  espAlert

void renderError (int status, cchar *fmt, ...)

Render an error message back to the client and finalize the request.

The output is Html escaped for security

Parameters:

  status | Http status code.
  fmt | Printf style message format.

Returns:
  A count of the bytes actually written.

See Also:
  espAlert

ssize renderFile (cchar *path)

Render a file back to the client.

Description:
  Render a formatted string of data and then HTML escape. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.

Parameters:

  path | Filename of the file to send to the client.
  ... | Arguments for fmt.

Returns:
  A count of the bytes actually written.

See Also:
  espAlert

ssize renderSafe (cchar *fmt, ...)

Render a formatted string after HTML escaping.

Description:
  Render a formatted string of data and then HTML escape. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.

Parameters:

  fmt | Printf style formatted string.
  ... | Arguments for fmt.

Returns:
  A count of the bytes actually written.

See Also:
  espAlert

void renderView (cchar *view)

Render a view template to the client.

Description:
  Actions are C procedures that are invoked when specific URIs are routed to the controller/action pair.

Parameters:

  view | view name.

See Also:
  espAlert

void script (cchar *uri, cchar *options)

Render a script link.

Parameters:

  uri | Script URI to load. Set to null to get a default set of scripts. See $httpLink for a list of possible URI formats.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void securityToken ()

Generate a security token.

Description:
  Security tokens are used to help guard against CSRF threats. This call will generate a security token for the page and emit an HTML meta element for the security token. The token will automatically be included whenever forms are submitted and the token be validated by the receiving Controller. Forms will normally automatically generate the security token and that explicitly calling this routine is not required unless a security token is required for non-form requests such as AJAX requests. The $securityToken control should be called inside the <head section of the web page.

See Also:
  espAlert

void setConn (HttpConn *conn)

Set the current request connection.

Parameters:

  conn | The HttpConn connection object to define.

See Also:
  espAlert

void setContentType (cchar *mimeType)

Set the transmission (response) content mime type.

Description:
  Set the mime type Http header in the transmission.

Parameters:

  mimeType | Mime type string.

See Also:
  espAlert

void setCookie (cchar *name, cchar *value, cchar *path, cchar *domain, MprTime lifespan, bool isSecure)

Define a cookie header to send with the response.

The Path, Domain, and Expires properties can be set to null for default values

Parameters:

  name | Cookie name.
  value | Cookie value.
  path | Uri path to which the cookie applies.
  domain | String Domain in which the cookie applies. Must have 2-3 "." and begin with a leading ".". For example: domain: .example.com Some browsers will accept cookies without the initial ".", but the spec: (RFC 2109) requires it.
  lifespan | Lifespan of the cookie. (MOB units?).
  isSecure | Boolean Set to "true" if the cookie only applies for SSL based connections.

See Also:
  espAlert

EdiRec * setField (EdiRec *rec, cchar *fieldName, cchar *value)

Update a record field without writing to the database.

Description:
  This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use $writeRec.

Parameters:

  rec | Record to update.
  fieldName | Record field name to update.
  value | Value to update.

Returns:
  The record instance if successful, otherwise NULL.

See Also:
  espAlert

EdiRec * setFields (EdiRec *rec, MprHash *data)

Update record fields without writing to the database.

Description:
  This routine updates the record object with the given values. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request $params() or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: updateFields(rec, hash("{ name: '%s', address: '%s' }", name, address)) The record will not be written to the database. To write to the database, use $ediWriteRec.

Parameters:

  rec | Record to update.
  data | Hash of field names and values to use for the update.

Returns:
  The record instance if successful, otherwise NULL.

See Also:
  espAlert

void setFlash (cchar *kind, cchar *fmt, ...)

Set a flash notification message.

Description:
  Flash messages persist for only one request and are a convenient way to pass state information or feedback messages to the next request. Flash messages use the session state store, but persist only for one request. The $inform, $error and $warn convenience methods invoke $notice. This routine calls $espSetFlash.

Parameters:

  kind | Kind of flash message.
  fmt | Printf style message format.

See Also:
  espAlert

void setHeader (cchar *key, cchar *fmt, ...)

Set a transmission header.

Description:
  Set a Http header to send with the request. If the header already exists, its value is overwritten.

Parameters:

  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

See Also:
  espAlert

void setParam (cchar *name, cchar *value)

Set a request parameter value.

Description:
  Set the value of a named request parameter to a string value. Form variables are defined via www-urlencoded query or post data contained in the request.

Parameters:

  name | Name of the request parameter to set.
  value | Value to set.

See Also:
  espAlert

void setSessionVar (cchar *name, cchar *value)

Set a session state variable.

Description:
  See also $espSetSessionVar and $espSetSessionObj for alternate ways to set session data.

Parameters:

  name | Variable name to set.
  value | Value to set.

See Also:
  espAlert

void setStatus (int status)

Set a Http response status.

Description:
  Set the Http response status for the request. This defaults to 200 (OK).

Parameters:

  status | Http status code.

See Also:
  espAlert

void setTimeout (void *proc, MprTime timeout, void *data)

Create a timeout event.

Description:
  Invoke the given procedure after the timeout.

Parameters:

  proc | Function to invoke.
  timeout | Time in milliseconds to elapse before invoking the timeout.
  data | Argument to pass to proc.

See Also:
  espAlert

void showRequest ()

Show request details.

Description:
  This echoes request details back to the client. This is useful as a debugging tool.

See Also:
  espAlert

void stylesheet (cchar *uri, cchar *options)

Render a stylesheet link.

Parameters:

  uri | Stylesheet URI to load. Set to null to get a default set of stylesheets. See $httpLink for a list of possible URI formats.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void table (EdiGrid *grid, cchar *options)

Render a table.

Description:
  The table control can display static or dynamic tabular data. The client table control manages sorting by column, dynamic data refreshes and clicking on rows or cells.

Parameters:

  grid | Data to display. The data is a grid of data. Use ediCreateGrid or ediReadGrid.
  options | Extra options. See $EspControl for a list of the standard options.

  options

  Optional extra options. See $View for a list of the standard options.
  - cell Boolean Set to "true" to make click or edit links apply per cell instead of per row. The default is false.
  - columns (Array|Object) The columns list is anobject hash of column objects where each column entry is hash of column options. Column options:
    - align - Will right-align numbers by default
    - click - URI to invoke if the cell is clicked
    - edit - MOB
    - formatter - Function to invoke to format the value to display
    - header - Header text for the column
    - style - Cell styles
    - width - Column width. Can be a string percentage or numeric pixel width
  - params Object Hash of post parameters to include in the request. This is a hash of key/value items.
  - pivot Boolean Pivot the table by swaping rows for columns and vice-versa
  - showHeader Boolean Control if column headings are displayed.
  - showId Boolean If a columns option is not provided, the id column is normally hidden. To display, set showId to be "true".
  - sort String Enable row sorting and define the column to sort by. Defaults to the first column.
  - sortOrder String Default sort order. Set to "ascending" or "descending".Defaults to ascending.
  - style String CSS class to use for the table. The ultimate style to use for a table cell is the combination of style, styleCells, styleColumns and style Rows.
  - styleCells 2D Array of styles to use for the table body cells. Can also provide an array to the column.style property.
  - styleColumns Array of styles to use for the table body columns. Can also use the style option in the columns option.
  - styleRows Array of styles to use for the table body rows
  - title String Table title.

See Also:
  espAlert

void tabs (EdiRec *rec, cchar *options)

Render a tab control.

The tab control can manage a set of panes and will selectively show and hide or invoke the selected panes. If the "click" option is defined, the selected pane will be invoked via a foreground click. If the "remote" option is defined, the selected pane will be invoked via a background click. If the "toggle" option is defined the selected pane will be made visible and other panes will be hidden. If using show/hide tabs, define the initial visible pane to be of the class "-ejs-pane-visible" and define other panes to be "-ejs-pane-hidden". The control's client side code will toggle these classes to make panes visible or hidden

Parameters:

  rec | Tab data for the control. Tab data is a single object where the tab text is the property key and the target to invoke is the property value.

  options

  Optional extra options. See $View for a list of the standard options.
  - click Set to "true" to invoke the selected pane via a foreground click.
  - remote Set to "true" to invoke the selected pane via a background click.
  - toggle Set to "true" to show the selected pane and hide other panes.

See Also:
  espAlert

void text (cchar *field, cchar *options)

Render a text input field as part of a form.

Parameters:

  field

  Name for the input text field. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form control record. It can be a simple property of the record or it can have multiple parts, such as: field.field.field. If this call is used without a form control record, the actual data value should be supplied via the options.value property. If the cols or rows option is defined, then a textarea HTML element will be used for multiline input.

  options

  Optional extra options. See $View for a list of the standard options.
  - cols Number number of text columns
  - rows Number number of text rows
  - password Boolean The data to display is a password and should be obfuscated.

See Also:
  espAlert

void tree (EdiGrid *grid, cchar *options)

Render a tree control.

Description:
  The tree control can display static or dynamic tree data.

Parameters:

  grid | Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. The tree data is typically an XML document.
  options | Optional extra options. See $View for a list of the standard options.

See Also:
  espAlert

void updateCache (cchar *uri, cchar *data, int lifesecs)

Update the cached content for a request.

Description:
  Save the given content for future requests. This is useful if the caching mode has been set to "manual".

Parameters:

  uri | Request URI to cache for.
  data | Data to cache.
  lifesecs | Time in seconds to cache the data.

See Also:
  espAlert

bool updateField (cchar *tableName, cchar *key, cchar *fieldName, cchar *value)

Write a value to a database table field.

Description:
  Update the value of a table field in the selected table row. Note: validations are not run.

Parameters:

  tableName | Database table name.
  key | Key value for the table row to update.
  fieldName | Column name to update.
  value | Value to write to the database field.

Returns:
  "true" if the field can be successfully written.

See Also:
  espAlert

bool updateFields (cchar *tableName, MprHash *data)

Write field values to a database row.

Description:
  This routine updates the current record with the given data and then saves the record to the database. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request $params() or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: ediWriteFields(rec, params()); The record runs field validations before saving to the database.

Parameters:

  tableName | Database table name.
  data | Hash of field names and values to use for the update.

Returns:
  "true" if the field can be successfully written. Returns false if field validations fail.

See Also:
  espAlert

bool updateRec (EdiRec *rec)

Write a record to the database.

Description:
  The record will be saved to the database after running any field validations. If any field validations fail to pass, the record will not be written and error details can be retrieved via $ediGetRecErrors. If the record is a new record and the "id" column is EDI_AUTO_INC, then the "id" will be assigned prior to saving the record.

Parameters:

  rec | Record to write to the database.

Returns:
  "true" if the record can be successfully written.

See Also:
  espAlert

cchar * uri (cchar *target)

Create a URI.

Description:
  Create a URI link by expansions tokens based on the current request and route state. The target parameter may contain partial or complete URI information. The missing parts are supplied using the current request and route tables. The resulting URI is a normalized, server-local URI (that begins with "/"). The URI will include any defined route prefix, but will not include scheme, host or port components.

Parameters:

  target

  The URI target. The target parameter can be a URI string or JSON style set of options. The target will have any embedded "{tokens}" expanded by using token values from the request parameters. If the target has an absolute URI path, that path is used directly after tokenization. If the target begins with "~", that character will be replaced with the route prefix. This is a very convenient way to create application top-level relative links.
  If the target is a string that begins with "{AT}" it will be interpreted as a controller/action pair of the form "{AT}Controller/action". If the "controller/" portion is absent, the current controller is used. If the action component is missing, the "list" action is used. A bare "{AT}" refers to the "list" action of the current controller.
  If the target starts with "{" it is interpreted as being a JSON style set of options that describe the link. If the target is a relative URI path, it is appended to the current request URI path.
  If the target is a JSON style of options, it can specify the URI components: scheme, host, port, path, reference and query. If these component properties are supplied, these will be combined to create a URI.
  If the target specifies either a controller/action or a JSON set of options, The URI will be created according to the route URI template. The template may be explicitly specified via a "route" target property. Otherwise, if an "action" property is specified, the route of the same name will be used. If these don't result in a usable route, the "default" route will be used.
  These are the properties supported in a JSON style "{ ... }" target:
  - scheme String URI scheme portion
  - host String URI host portion
  - port Number URI port number
  - path String URI path portion
  - reference String URI path reference. Does not include "#"
  - query String URI query parameters. Does not include "?"
  - controller String Controller name if using a Controller-based route. This can also be specified via the action option.
  - action String Action to invoke. This can be a URI string or a Controller action of the form {AT}Controller/action.
  - route String Route name to use for the URI template

Returns:
  A normalized, server-local Uri string.

Example:
  Uri("http://example.com/index.html", 0);
  uri("/path/to/index.html", 0);
  uri("../images/splash.png", 0);
  uri("~/static/images/splash.png", 0);
  uri("${app}/static/images/splash.png", 0);
  uri("@controller/checkout", 0);
  uri("@controller/")
  uri("@init")
  uri("@")
  uri("{ action: '@post/create' }", 0);
  uri("{ action: 'checkout' }", 0);
  uri("{ action: 'logout', controller: 'admin' }", 0);
  uri("{ action: 'admin/logout'", 0);
  uri("{ product: 'candy', quantity: '10', template: '/cart/${product}/${quantity}' }", 0);
  uri("{ route: '~/STAR/edit', action: 'checkout', id: '99' }", 0);
  uri("{ template: '~/static/images/${theme}/background.jpg', theme: 'blue' }", 0);.

See Also:
  espAlert

# EspControl

EspControl

There are two groups of ESP Control APIs.

API Stability:
  Prototype.

See Also:
  espAlert

Fields:

void endform ()

Signify the end of an HTML form.

Description:
  This emits a HTML closing form tag.

See Also:
  espAlert

void espAlert (HttpConn *conn, cchar *text, cchar *options)

Display a popup alert message in the client's browser when the web page is displayed.

Parameters:

  conn | Http connection object.
  text | Alert text to display.

  options

  Extra options. See $EspControl for a list of the standard options.
  - period — Polling period in milliseconds for the client to check the server for status message updates. If this is not specifed, the connection to the server will be kept open. This permits the server to "push" alerts to the console, but will consume a connection at the server for each client.

See Also:

void espAnchor (HttpConn *conn, cchar *text, cchar *uri, cchar *options)

Render an HTML anchor link.

Description:
  This emits a label inside an anchor reference. i.e. a clickable link.

Parameters:

  conn | Http connection object.
  text | Anchor text to display for the link.
  uri | URI link for the anchor.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espButton (HttpConn *conn, cchar *text, cchar *value, cchar *options)

Render an HTML button to use inside a form.

Description:
  This creates a button suitable for use inside an input form. When the button is clicked, the input form will be submitted.

Parameters:

  conn | Http connection object.
  text | Button text to display. This text is also used as the name for the form input from this control.
  value | Form input value to submit when the button is clicked.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espButtonLink (HttpConn *conn, cchar *text, cchar *uri, cchar *options)

Render an HTML button to use outside a form.

Parameters:

  conn | Http connection object.
  text | Button text to display.
  uri | URI to invoke when the button is clicked.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espChart (HttpConn *conn, EdiGrid *grid, cchar *options)

Render a graphic chart.

Description:
  The chart control can display static or dynamic tabular data. The client chart control manages sorting by column, dynamic data refreshes, pagination, and clicking on rows. TODO. This is incomplete.

Parameters:

  conn | Http connection object.
  grid | Data to display. The data is a grid of data. Use ediCreateGrid or ediReadGrid.

  options

  Extra options. See $EspControl for a list of the standard options.
  - columns Object hash of column entries. Each column entry is (in turn) an object hash of options. If unset, all columns are displayed using defaults.
  - kind String Type of chart. Select from: piechart, table, linechart, annotatedtimeline, guage, map, motionchart, areachart, intensitymap, imageareachart, barchart, imagebarchart, bioheatmap, columnchart, linechart, imagelinechart, imagepiechart, scatterchart (and more).

See Also:
  espAlert

void espCheckbox (HttpConn *conn, cchar *name, cchar *checkedValue, cchar *options)

Render an input checkbox.

Description:
  This creates a checkbox suitable for use within an input form.

Parameters:

  conn | Http connection object.
  name | Name for the input checkbox. This defines the HTML element name, and provides the source of the initial value for the checkbox. The field should be a property of the $espForm current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  checkedValue | Value for which the checkbox will be checked.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espDivision (HttpConn *conn, cchar *body, cchar *options)

Render an HTML division.

Description:
  This creates an HTML element with the required options. It is useful to generate a dynamically refreshing division.

Parameters:

  conn | Http connection object.
  body | HTML body to render.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espDropdown (HttpConn *conn, cchar *field, cchar *choices, cchar *options)

Render a dropdown selection list.

Parameters:

  conn | Http connection object.
  field | Record field name to provide the default value for the list. The field should be a property of the form current record. The field name is used to create the HTML input control name. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  choices | Choices to select from. This is a JSON style set of properties. For example: espDropdown(conn, "priority", "{ low: 0, med: 1, high: 2 }", NULL).
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espEndform (HttpConn *conn)

Signify the end of an HTML form.

Description:
  This emits a HTML closing form tag.

Parameters:

  conn | Http connection object.

See Also:
  espAlert

void espFlash (HttpConn *conn, cchar *kinds, cchar *options)

Render flash messages.

Description:
  Flash messages are one-time messages that are displayed to the client on the next request (only). Flash messages use the session state store but persist for only one request. See $espSetFlash for how to define flash messages.

Parameters:

  conn | Http connection object.
  kinds | Space separated list of flash messages types. Typical types are: "error", "inform", "warning".

  options

  Extra options. See $EspControl for a list of the standard options.
  - retain — Number of seconds to retain the message. If <= 0, the message is retained until another message is displayed. Default is 0. MOB - this default implies it is displayed for zero seconds

See Also:
  espAlert

void espForm (HttpConn *conn, EdiRec *record, cchar *options)

Render an HTML form.

Description:
  This will render an HTML form tag and optionally associate the given record as the current record for the request. Abbreviated controls (see $EspAbbrev) use the current record to supply form data fields and values. The espForm control can be used without a record. In this case, nested ESP controls may have to provide values via an Options.value field.

Parameters:

  conn | Http connection object.
  record | Record to use by default to supply form field names and values.

  options

  Extra options. See $EspControl for a list of the standard options.
  - hideErrors — Don't display database record errors. Records retain error diagnostics from the previous failed write. Setting this option will prevent the display of such errors.
  - modal — Make the form a modal dialog. This will block all other HTML controls except the form.
  - nosecurity — Don't generate a security token for the form.
  - securityToken — String Override CSRF security token to include when the form is submitted. A default security token will always be generated unless options.nosecurity is defined to be true. Security tokens are used by ESP to mitigate cross-site scripting errors.

See Also:
  espAlert

void espIcon (HttpConn *conn, cchar *uri, cchar *options)

Render an HTML icon.

Parameters:

  conn | Http connection object.
  uri | URI reference for the icon resource.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espImage (HttpConn *conn, cchar *uri, cchar *options)

Render an HTML image.

Parameters:

  conn | Http connection object.
  uri | URI reference for the image resource.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espInput (HttpConn *conn, cchar *field, cchar *options)

Render an input field as part of a form.

This is a smart input control that will call the appropriate input control based on the database record field data type

Parameters:

  conn | Http connection object.
  field | Name for the input field. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espLabel (HttpConn *conn, cchar *text, cchar *options)

Render a text label field.

This renders an output-only text field. Use espText() for input fields

Parameters:

  conn | Http connection object.
  text | Label text to display.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espMail (HttpConn *conn, cchar *name, cchar *address, cchar *options)

Render a mail link.

Parameters:

  conn | Http connection object.
  name | Recipient name to display.
  address | Mail recipient address link.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espProgress (HttpConn *conn, cchar *progress, cchar *options)

Emit a progress bar.

Parameters:

  conn | Http connection object.
  progress | Progress percentage (0-100).
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espRadio (HttpConn *conn, cchar *field, void *choices, cchar *options)

Render a radio button.

This creates a radio button suitable for use within an input form

Parameters:

  conn | Http connection object.
  field | Name for the input radio button. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
  choices | Choices to select from. This is a JSON style set of properties. For example: espRadio(conn, "priority", "{ low: 0, med: 1, high: 2, }", NULL).
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espRefresh (HttpConn *conn, cchar *on, cchar *off, cchar *options)

Control the refresh of web page dynamic elements.

Parameters:

  conn | Http connection object.
  on | URI to invoke when turning "on" refresh.
  off | URI to invoke when turning "off" refresh.

  options

  Extra options. See $EspControl for a list of the standard options.
  - minified — Set to "true" to select a minified (compressed) version of the script.

See Also:
  espAlert

void espScript (HttpConn *conn, cchar *uri, cchar *options)

Render a script link.

Parameters:

  uri | Script URI to load. Set to null to get a default set of scripts. See $httpLink for a list of possible URI formats.
  conn | Http connection object.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espSecurityToken (HttpConn *conn)

Generate a security token.

Description:
  Security tokens are used to help guard against CSRF threats. This call will generate a security token for the page, and emit an HTML meta element for the security token. The token will automatically be included whenever forms are submitted and the token is validated by the receiving Controller. Typically, forms will automatically generate the security token. Note that explicitly calling this routine is not necessary unless a security token is required for non-form requests such as AJAX requests. The $securityToken control should be called inside the <head section of the web page.

Parameters:

  conn | Http connection object.

See Also:
  espAlert

void espStylesheet (HttpConn *conn, cchar *uri, cchar *options)

Render a stylesheet link.

Parameters:

  uri | Stylesheet URI to load. Set to null to get a default set of stylesheets. See $httpLink for a list of possible URI formats.
  conn | Http connection object.
  options | Extra options. See $EspControl for a list of the standard options.

See Also:
  espAlert

void espTable (HttpConn *conn, EdiGrid *grid, cchar *options)

Render a table.

Description:
  The table control can display static or dynamic tabular data. The client table control manages sorting by column, dynamic data refreshes, and clicking on rows or cells.

Parameters:

  conn | Http connection object.
  grid | Data to display. The data is a grid of data. Use ediCreateGrid or ediReadGrid.
  options | Extra options. See $EspControl for a list of the standard options.

  options

  Optional extra options. See $View for a list of the standard options.
  - cell Boolean Set to "true" to make click or edit links apply per cell instead of per row. The default is false.
  - columns (Array|Object) The columns list is an object hash of column objects where each column entry is a hash of column options. Column options:
    - align - Will right-align numbers by default
    - click - URI to invoke if the cell is clicked
    - edit - MOB
    - formatter - Function to invoke to format the value to display
    - header - Header text for the column
    - style - Cell styles
    - width - Column width. Can be a string percentage or numeric pixel width
  - params Object Hash of post parameters to include in the request. This is a hash of key/value items.
  - pivot Boolean Pivot the table by swapping rows for columns and vice-versa
  - showHeader Boolean Control if column headings are displayed.
  - showId Boolean If a column's option is not provided, the id column is normally hidden. To display, set showId to be 'true'.
  - sort String Enable row sorting and define the column to sort by. Defaults to the first column.
  - sortOrder String Default sort order. Set to "ascending" or "descending". Defaults to ascending.
  - style String CSS class to use for the table. The ultimate style to use for a table cell is the combination of style, styleCells, styleColumns, and style Rows.
  - styleCells 2D Array of styles to use for the table body cells. Can also provide an array to the column.style property.
  - styleColumns Array of styles to use for the table body columns. Can also use the style option in the columns option.
  - styleRows Array of styles to use for the table body rows
  - title String Table title.

See Also:
  espAlert

void espTabs (HttpConn *conn, EdiRec *rec, cchar *options)

Render a tab control.

The tab control can manage a set of panes and will selectively show and hide or invoke the selected panes. If the "click" option is defined, the selected pane will be invoked via a foreground click. If the "remote" option is defined, the selected pane will be invoked via a background click. If the "toggle" option is defined the selected pane will be made visible and other panes will be hidden. If using show/hide tabs, define the initial visible pane to be of the class "-ejs-pane-visible" and define other panes to be "-ejs-pane-hidden". The control's client side code will toggle these classes to make panes visible or hidden

Parameters:

  conn | Http connection object.
  rec | Tab data for the control. Tab data is be be a single object where the tab text is the property key and the target to invoke is the property value.

  options

  Optional extra options. See $View for a list of the standard options.
  - click Set to "true" to invoke the selected pane via a foreground click.
  - remote Set to "true" to invoke the selected pane via a background click.
  - toggle Set to "true" to show the selected pane and hide other panes.

See Also:
  espAlert

void espText (HttpConn *conn, cchar *field, cchar *options)

Render a text input field as part of a form.

Parameters:

  conn | Http connection object.

  field

  Name for the input text field. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form control record. It can be a simple property of the record or it can have multiple parts, such as: field.field.field. If this call is used without a form control record, the actual data value should be supplied via the options.value property. If the cols or rows option is defined, then a textarea HTML element will be used for multiline input.

  options

  Optional extra options. See $View for a list of the standard options.
  - cols Number number of text columns
  - rows Number number of text rows
  - password Boolean The data to display is a password and should be obfuscated.

See Also:
  espAlert

void espTree (HttpConn *conn, EdiGrid *grid, cchar *options)

Render a tree control.

Parameters:

  conn | Http connection object.

Description:
  The tree control can display static or dynamic tree data.

Parameters:

  grid | Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. The tree data is typically an XML document.
  options | Optional extra options. See $View for a list of the standard options.

See Also:
  espAlert

# EspParse

EspParse

ESP page parser structure.

See Also:

Fields:

  char * |  | data | Input data to parse.
  int |  | lineNumber | Line number for error reporting.
  char * |  | next | Next character in input.
  MprBuf * |  | token | Storage buffer for token.

# EspReq

EspReq

ESP request.

See Also:

Fields:

  EspAction * |  | action | Action to invoke.
  int |  | appLoaded | App module already probed.
  int |  | autoFinalize | Request is or will be auto-finalized.
  char * |  | cacheName | Base name of intermediate compiled file.
  char * |  | commandLine | Command line for compile/link.
  char * |  | controllerName | Controller name.
  char * |  | controllerPath | Path to controller source.
  char * |  | entry | Module entry point.
  EspRoute * |  | eroute | Extended route info.
  Esp * |  | esp | Convenient esp reference.
  MprHash * |  | flash | New flash messages.
  int |  | lastDomID | Last generated DOM ID.
  MprHash * |  | lastFlash | Flash messages from the last request.
  char * |  | module | Name of compiled module.
  EdiRec * |  | record | Current data record.
  HttpRoute * |  | route | Route reference.
  EspSession * |  | session | Session data object.
  int |  | sessionProbed | Already probed for session store.
  char * |  | source | Name of ESP source.
  char * |  | view | Path to view.

EdiRec * eReadRecByKey (cchar *tableName, cchar *key)

Read a record identified by the key value.

Description:
  Read a record from the given table as identified by the key value.

Parameters:

  tableName | Database table name.
  key | Key value of the record to read.

Returns:
  Record instance of EdiRec.

See Also:

void espAddHeader (HttpConn *conn, cchar *key, cchar *fmt, ...)

Add a header to the transmission using a format string.

Description:
  Add a header if it does not already exist.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

Returns:
  Zero if successful, otherwise a negative MPR error code. Returns MPR_ERR_ALREADY_EXISTS if the header already exists.

See Also:

void espAddHeaderString (HttpConn *conn, cchar *key, cchar *value)

Add a header to the transmission.

Description:
  Add a header if it does not already exist.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.
  value | Value to set for the header.

Returns:
  Zero if successful, otherwise a negative MPR error code. Returns MPR_ERR_ALREADY_EXISTS if the header already exists.

See Also:

void espAppendHeader (HttpConn *conn, cchar *key, cchar *fmt, ...)

Append a transmission header.

Description:
  Set the header if it does not already exist. Append with a ", " separator if the header already exists.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

See Also:

void espAppendHeaderString (HttpConn *conn, cchar *key, cchar *value)

Append a transmission header string.

Description:
  Set the header if it does not already exist. Append with a ", " separator if the header already exists.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.
  value | Value to set for the header.

See Also:

void espAutoFinalize (HttpConn *conn)

Auto-finalize transmission of the http request.

Description:
  If auto-finalization is enabled via espSetAutoFinalizing, this call will finalize writing Http response data by writing the final chunk trailer if required. If using chunked transfers, a null chunk trailer is required to signify the end of write data. If the request is already finalized, this call does nothing.

Parameters:

  conn | HttpConn connection object.

See Also:

bool espCheckSecurityToken (HttpConn *conn)

Check a security token.

Description:
  Check the request security token. If a required security token is defined in the session state, the request must supply the same token with all POST requests. This helps mitigate potential CSRF threats. Security tokens are used to help guard against CSRF threats. If a template web page includes the securityToken() control, a security token will be added to the meta section of the generated HTML. When a form is posted from this page, the ESP jQuery script will add the security token to the form parameters. This call validates the security token to ensure it matches the security token stored in session state.

Parameters:

  conn | Http connection object.

Returns:
  False if the request is a POST request and the security token does not match the session held token. Otherwise return "true".

See Also:

EdiRec * espCreateRec (HttpConn *conn, cchar *tableName, MprHash *data)

Create a record and initialize field values.

Description:
  This will call $ediCreateRec to create a record based on the given table's schema. It will then call $ediSetFields to update the record with the given data.

Parameters:

  conn | Http connection object.
  tableName | Database table name.
  data | Hash of field values.

Returns:
  EdRec instance.

See Also:

void espFinalize (HttpConn *conn)

Finalize transmission of the http request.

Description:
  Finalize writing HTTP data by writing the final chunk trailer if required. If using chunked transfers, a null chunk trailer is required to signify the end of write data. If the request is already finalized, this call does nothing.

Parameters:

  conn | HttpConn connection object.

See Also:

void espFlush (HttpConn *conn)

Flush transmit data.

Description:
  This writes any buffered data.

Parameters:

  conn | HttpConn connection object.

See Also:

MprList * espGetColumns (HttpConn *conn, EdiRec *rec)

Get a list of column names.

Parameters:

  conn | HttpConn connection object.
  rec | Database record. If set to NULL, the current database record defined via $form() is used.

Returns:
  An MprList of column names in the given table. If there is no record defined, an empty list is returned.

See Also:

HttpConn * espGetConn ()

Get the current request connection.

Returns:
  The HttpConn connection object.

See Also:

MprOff espGetContentLength (HttpConn *conn)

Get the receive body content length.

Description:
  Get the length of the receive body content (if any). This is used in servers to get the length of posted data and, in clients, to get the response body length.

Parameters:

  conn | HttpConn connection object.

Returns:
  A count of the response content data in bytes.

See Also:

cchar * espGetContentType (HttpConn *conn)

Get the receive body content type.

Description:
  Get the content mime type of the receive body content (if any).

Parameters:

  conn | HttpConn connection object.

Returns:
  Mime type of any receive content. Set to NULL if not posted data.

See Also:

cchar * espGetCookies (HttpConn *conn)

Get the request cookies.

Description:
  Get the cookies defined in the current request.

Parameters:

  conn | HttpConn connection object.

Returns:
  Return a string containing the cookies sent in the Http header of the last request.

See Also:

Edi * espGetDatabase (HttpConn *conn)

Get the current database instance.

Description:
  A route may have a default database configured via the EspDb Appweb.conf configuration directive. The database will be opened when the web server initializes and will be shared between all requests using the route.

Returns:
  Edi EDI database handle.

See Also:

cchar * espGetDir (HttpConn *conn)

Get the default document root directory for the request route.

Parameters:

  conn | HttpConn connection object.

Returns:
  A directory path name.

See Also:

EspRoute * espGetEspRoute (HttpConn *conn)

Get the current extended route information.

Returns:
  EspRoute instance.

See Also:

cchar * espGetFlashMessage (HttpConn *conn, cchar *type)

Get a flash message.

Description:
  This retrieves a flash message of a specified type. Flash messages are special session state messages that are passed to the next request (only).

Parameters:

  conn | HttpConn connection object.
  type | Type of flash message to retrieve. Possible types include: "error", "inform", "warning", "all".

See Also:

cchar * espGetHeader (HttpConn *conn, cchar *key)

Get an rx http header.

Description:
  Get a http response header for a given header key.

Parameters:

  conn | HttpConn connection object.
  key | Name of the header to retrieve. This should be a lower case header name. For example: "Connection".

Returns:
  Value associated with the header key or null if the key did not exist in the response.

See Also:

MprHash * espGetHeaderHash (HttpConn *conn)

Get the hash table of rx Http headers.

Description:
  Get the internal hash table of rx headers.

Parameters:

  conn | HttpConn connection object.

Returns:
  Hash table. See MprHash for how to access the hash table.

See Also:

char * espGetHeaders (HttpConn *conn)

Get all the request http headers.

Description:
  Get all the rx headers. The returned string formats all the headers in the form: key: value\nkey2: value2\n.

Parameters:

  conn | HttpConn connection object.

Returns:
  String containing all the headers. The caller must free this returned string.

See Also:

int espGetIntParam (HttpConn *conn, cchar *var, int defaultValue)

Get a request pararmeter as an integer.

Description:
  Get the value of a named request parameter as an integer. Form variables are defined via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request parameter to retrieve.
  defaultValue | Default value to return if the variable is not defined. Can be null.

Returns:
  Integer containing the request parameter's value.

See Also:

cchar * espGetMethod (HttpConn *conn)

Get the HTTP method.

Description:
  This is a convenience API to return the Http method.

Returns:
  The HttpConn.rx.method property.

See Also:

cchar * espGetParam (HttpConn *conn, cchar *var, cchar *defaultValue)

Get a request parameter.

Description:
  Get the value of a named request parameter. Form variables are defined via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request parameter to retrieve.
  defaultValue | Default value to return if the variable is not defined. Can be null.

Returns:
  String containing the request parameter's value. Caller should not free.

See Also:

MprHash * espGetParams (HttpConn *conn)

Get the request parameter hash table.

Description:
  This call gets the params hash table for the current request. Route tokens, request query data, and www-url encoded form data are all entered into the params table after decoding. Use mprLookupKey to retrieve data from the table.

Parameters:

  conn | HttpConn connection object.

Returns:
  MprHash instance containing the request parameters.

See Also:

cchar * espGetQueryString (HttpConn *conn)

Get the request query string.

Description:
  Get query string sent with the current request.

Parameters:

  conn | HttpConn connection object.

Returns:
  String containing the request query string. Caller should not free.

See Also:

char * espGetReferrer (HttpConn *conn)

Get the referring URI.

Description:
  This returns the referring URI as described in the HTTP "referer" (yes the HTTP specification does spell it incorrectly) header. If this header is not defined, this routine will return the home URI as returned by $espGetHome.

Parameters:

  conn | HttpConn connection object.

Returns:
  String URI back to the referring URI. If no referrer is defined, refers to the home URI.

See Also:

Edi * espGetRouteDatabase (HttpRoute *route)

Get the default database defined on a route.

Parameters:

  route | HttpRoute object.

Returns:
  Database instance object.

See Also:

int espGetStatus (HttpConn *conn)

Get the response status.

Parameters:

  conn | HttpConn connection object.

Returns:
  An integer Http response code. Typically 200 is success.

See Also:

char * espGetStatusMessage (HttpConn *conn)

Get the Http response status message.

Description:
  The HTTP status message is supplied on the first line of the HTTP response.

Parameters:

  conn | HttpConn connection object.

Returns:
  A Http status message.

See Also:

char * espGetTop (HttpConn *conn)

Get a relative URI to the top of the application.

Description:
  This will return an absolute URI for the top of the application. This will be "/" if there is no application script name. Otherwise, it will return a URI for the script name for the application.

Parameters:

  conn | HttpConn connection object.

Returns:
  String Absolute URI to the top of the application.

See Also:

MprHash * espGetUploads (HttpConn *conn)

Get the uploaded files.

Description:
  Get the hash table defining the uploaded files. This hash is indexed by the file identifier supplied in the upload form. The hash entries are HttpUploadFile objects.

Parameters:

  conn | HttpConn connection object.

Returns:
  A hash of HttpUploadFile objects.

See Also:

cchar * espGetUri (HttpConn *conn)

Get the request URI string.

Description:
  This is a convenience API to return the request URI.

Returns:
  The espGetConn()->rx->uri.

See Also:

bool espHasGrid (HttpConn *conn)

Test if a current grid has been defined.

Description:
  The current grid is defined via $setRec.

Returns:
  "True" if a current grid has been defined.

See Also:

bool espHasRec (HttpConn *conn)

Test if a current record has been defined and save to the database.

Description:
  This call returns "true" if a current record is defined and has been saved to the database with a valid "id" field.

Returns:
  "True" if a current record with a valid "id" is defined.

See Also:

bool espIsEof (HttpConn *conn)

Test if the receive input stream is at end-of-file.

Parameters:

  conn | HttpConn connection object.

Returns:
  "True" if there is no more receive data to read.

See Also:

bool espIsFinalized (HttpConn *conn)

Test if a http request is finalized.

Description:
  This tests if espFinalize or httpFinalize has been called for a request.

Parameters:

  conn | HttpConn connection object.

Returns:
  "True" if the request has been finalized.

See Also:

bool espIsSecure (HttpConn *conn)

Test if the connection is using SSL and is secure.

Parameters:

  conn | HttpConn connection object.

Returns:
  "True" if the connection is using SSL.

See Also:

EdiGrid * espMakeGrid (cchar *content)

Make a grid.

Description:
  This call makes a free-standing data grid based on the JSON format content string. The record is not saved to the database.

Parameters:

  content | JSON format content string. The content should be an array of objects where each object is a set of property names and values.

Returns:
  An EdiGrid instance.

Example:
  : grid = ediMakeGrid("[ \
  { id: '1', country: 'Australia' }, \
  { id: '2', country: 'China' }, \
  ]");.

See Also:

MprHash * espMakeHash (cchar *fmt, ...)

Make a hash table container of property values.

Description:
  This routine formats the given arguments, parses the result as a JSON string and returns an equivalent hash of property values. The result after formatting should be of the form: hash("{ key: 'value', key2: 'value', key3: 'value' }");.

Parameters:

  fmt | Printf style format string.
  ... | arguments.

Returns:
  MprHash instance.

See Also:

EdiRec * espMakeRec (cchar *content)

Make a record.

Description:
  This call makes a free-standing data record based on the JSON format content string. The record is not saved to the database.

Parameters:

  content | JSON format content string. The content should be a set of property names and values.

Returns:
  An EdiRec instance.

Example:
  : rec = ediMakeRec("{ id: 1, title: 'Message One', body: 'Line one' }");.

See Also:

bool espMatchParam (HttpConn *conn, cchar *var, cchar *value)

Match a request parameter with an expected value.

Description:
  Compare a request parameter and return "true" if it exists and its value matches.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request parameter.
  value | Expected value to match.

Returns:
  "True" if the value matches.

See Also:

EdiGrid * espReadAllRecs (HttpConn *conn, cchar *tableName)

Read all the records in table from the database.

Description:
  This reads a table and returns a grid containing the table data.

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.

Returns:
  A grid containing all table rows. Returns NULL if the table cannot be found.

See Also:

EdiRec * espReadRec (HttpConn *conn, cchar *tableName)

Read the identified record.

Description:
  Read the record identified by the request params("id") from the nominated table.

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.

Returns:
  The identified record. Returns NULL if the table or record cannot be found.

See Also:

EdiGrid * espReadRecsWhere (HttpConn *conn, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read matching records.

Description:
  This runs a simple query on the database and returns matching records in a grid. The query selects all rows that have a "field" that matches the given "value".

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.
  fieldName | Database field name to evaluate.
  operation | Comparison operation. Set to "==", "!=", "<", ">", "<=" or ">=".
  value | Data value to compare with the field values.

Returns:
  A grid containing all matching records. Returns NULL if no matching records.

See Also:

EdiRec * espReadRecWhere (HttpConn *conn, cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read one record.

Description:
  This runs a simple query on the database and selects the first matching record. The query selects a row that has a "field" that matches the given "value".

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.
  fieldName | Database field name to evaluate.
  operation | Comparison operation. Set to "==", "!=", "<", ">", "<=" or ">=".
  value | Data value to compare with the field values.

Returns:
  First matching record. Returns NULL if no matching records.

See Also:

ssize espReceive (HttpConn *conn, char *buf, ssize size)

Read receive body content.

Description:
  Read body content from the client.

Parameters:

  conn | HttpConn connection object.
  buf | Buffer to accept content data.
  size | Size of the buffer.

Returns:
  A count of bytes read into the buffer.

See Also:

void espRedirect (HttpConn *conn, int status, cchar *target)

Redirect the client.

Description:
  Redirect the client to a new uri.

Parameters:

  conn | HttpConn connection object.
  status | Http status code to send with the response.
  target | New target uri for the client.

See Also:

void espRedirectBack (HttpConn *conn)

Redirect the client back to the referrer.

Description:
  Redirect the client to the referring URI.

Parameters:

  conn | HttpConn connection object.

See Also:

int espRemoveHeader (HttpConn *conn, cchar *key)

Remove a header from the transmission.

Description:
  Remove a header if present.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.

Returns:
  Zero if successful, otherwise a negative MPR error code.

See Also:

ssize espRender (HttpConn *conn, cchar *fmt, ...)

Render a formatted string.

Description:
  Render a formatted string of data into packets to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.

Parameters:

  conn | HttpConn connection object.
  fmt | Printf style formatted string.
  ... | Arguments for fmt.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderBlock (HttpConn *conn, cchar *buf, ssize size)

Render a block of data to the client.

Description:
  Render a block of data to the client. Data packets will be created as required to store the write data.

Parameters:

  conn | HttpConn connection object.
  buf | Buffer containing the write data.
  size | Size of the data in buf.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderCached (HttpConn *conn)

Render cached content.

Description:
  Render the saved, cached response from a prior request to this URI. This is useful if the caching mode has been set to "manual".

Parameters:

  conn | HttpConn connection object.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderError (HttpConn *conn, int status, cchar *fmt, ...)

Render an error message back to the client and finalize the request.

The output is Html escaped for security

Parameters:

  conn | HttpConn connection object.
  status | Http status code.
  fmt | Printf style message format.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderFile (HttpConn *conn, cchar *path)

Render the contents of a file back to the client.

Parameters:

  conn | HttpConn connection object.
  path | File path name.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderParam (HttpConn *conn, cchar *name)

Render the value of a request parameter to the client.

Description:
  This writes the value of a request parameter after HTML escaping its value.

Parameters:

  conn | HttpConn connection object.
  name | Form variable name.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderSafeString (HttpConn *conn, cchar *s)

Render a safe string of data to the client.

Description:
  HTML escape a string and then write the string of data to the client. Data packets will be created as required to store the write data. This call may block waiting for the data to the client to drain.

Parameters:

  conn | HttpConn connection object.
  s | String containing the data to write.

Returns:
  A count of the bytes actually written.

See Also:

ssize espRenderString (HttpConn *conn, cchar *s)

Render a string of data to the client.

Description:
  Render a string of data to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.

Parameters:

  conn | HttpConn connection object.
  s | String containing the data to write.

Returns:
  A count of the bytes actually written.

See Also:

void espRenderView (HttpConn *conn, cchar *name)

Render a view template to the client.

Description:
  Actions are C procedures that are invoked when specific URIs are routed to the controller/action pair.

Parameters:

  conn | Http connection object.
  name | view name.

See Also:

bool espSetAutoFinalizing (HttpConn *conn, bool on)

Enable auto-finalizing for this request.

Parameters:

  conn | HttpConn connection object.
  on | Set to "true" to enable auto-finalizing.

Returns:
  "True" if auto-finalizing was enabled prior to this call.

See Also:

void espSetConn (HttpConn *conn)

Set the current request connection.

Parameters:

  conn | The HttpConn connection object to define.

See Also:

void espSetContentLength (HttpConn *conn, MprOff length)

Define a content length header in the transmission.

Description:
  This will define a "Content-Length: NNN" request header.

Parameters:

  conn | HttpConn connection object.
  length | Numeric value for the content length header.

See Also:

void espSetContentType (HttpConn *conn, cchar *mimeType)

Set the transmission (response) content mime type.

Description:
  Set the mime type Http header in the transmission.

Parameters:

  conn | HttpConn connection object.
  mimeType | Mime type string.

See Also:

void espSetCookie (HttpConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, MprTime lifespan, bool isSecure)

Set a cookie in the transmission.

Description:
  Define a cookie to send in the transmission Http header.

Parameters:

  conn | HttpConn connection object.
  name | Cookie name.
  value | Cookie value.
  path | URI path to which the cookie applies.
  domain | String Domain in which the cookie applies. Must have 2-3 "." and begin with a leading ".". For example: domain: .example.com. Some browsers will accept cookies without the initial ".", but the spec: (RFC 2109) requires it.
  lifespan | Duration for the cookie to persist in msec.
  isSecure | Set to "true" if the cookie only applies for SSL based connections.

See Also:

EdiRec * espSetField (EdiRec *rec, cchar *fieldName, cchar *value)

Update a record field without writing to the database.

Description:
  This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use $writeRec.

Parameters:

  rec | Record to update.
  fieldName | Record field name to update.
  value | Value to update.

Returns:
  The record instance if successful, otherwise NULL.

See Also:

EdiRec * espSetFields (EdiRec *rec, MprHash *data)

Update record fields without writing to the database.

Description:
  This routine updates the record object with the given values. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request $params() or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: updateFields(rec, hash("{ name: '%s', address: '%s' }", name, address)) The record will not be written to the database. To write to the database, use $ediWriteRec.

Parameters:

  rec | Record to update.
  data | Hash of field names and values to use for the update.

Returns:
  The record instance if successful, otherwise NULL.

See Also:

void espSetFlash (HttpConn *conn, cchar *kind, cchar *fmt, ...)

Send a flash message.

Parameters:

  conn | Http connection object.
  kind | Kind of flash message.
  fmt | Printf style formatted string to use as the message.

See Also:

void espSetFlashv (HttpConn *conn, cchar *kind, cchar *fmt, va_list args)

Send a flash message.

Parameters:

  conn | Http connection object.
  kind | Kind of flash message.
  fmt | Printf style formatted string to use as the message.
  args | Varargs style list.

See Also:

EdiGrid * espSetGrid (HttpConn *conn, EdiGrid *grid)

Set the current database grid.

Returns:
  The grid instance. This permits chaining.

See Also:

void espSetHeader (HttpConn *conn, cchar *key, cchar *fmt, ...)

Set a transmission header.

Description:
  Set a Http header to send with the request. If the header already exists, its value is overwritten.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.
  fmt | Printf style formatted string to use as the header key value.
  ... | Arguments for fmt.

See Also:

void espSetHeaderString (HttpConn *conn, cchar *key, cchar *value)

Set a simple key/value transmission header.

Description:
  Set a Http header to send with the request. If the header already exists, its value is overwritten.

Parameters:

  conn | HttpConn connection object.
  key | Http response header key.
  value | String value for the key.

See Also:

void espSetIntParam (HttpConn *conn, cchar *var, int value)

Set an integer request parameter value.

Description:
  Set the value of a named request parameter to an integer value. Form variables are defined via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request parameter to set.
  value | Value to set.

See Also:

void espSetParam (HttpConn *conn, cchar *var, cchar *value)

Set a request parameter value.

Description:
  Set the value of a named request parameter to a string value. Form variables are defined via www-urlencoded query or post data contained in the request.

Parameters:

  conn | HttpConn connection object.
  var | Name of the request parameter to set.
  value | Value to set.

See Also:

EdiRec * espSetRec (HttpConn *conn, EdiRec *rec)

Set the current database record.

Description:
  The current record is used to supply data to various abbreviated controls, such as: text(), input(), checkbox and dropdown()

Parameters:

  conn | HttpConn connection object.
  rec | Record object to define as the current record.

Returns:
  The grid instance. This permits chaining.

See Also:

void espSetStatus (HttpConn *conn, int status)

Set a Http response status.

Description:
  Set the Http response status for the request. This defaults to 200 (OK).

Parameters:

  conn | HttpConn connection object.
  status | Http status code.

See Also:

void espShowRequest (HttpConn *conn)

Show request details.

Description:
  This e request details back to the client. This is useful as a debugging tool.

Parameters:

  conn | HttpConn connection object.

See Also:

void espUpdateCache (HttpConn *conn, cchar *uri, cchar *data, int lifesecs)

Update the cached content for a request.

Description:
  Save the given content for future requests. This is useful if the caching mode has been set to "manual".

Parameters:

  conn | HttpConn connection object.
  uri | Request URI to cache for.
  data | Data to cache.
  lifesecs | Time in seconds to cache the data.

See Also:

bool espUpdateField (HttpConn *conn, cchar *tableName, cchar *key, cchar *fieldName, cchar *value)

Write a value to a database table field.

Description:
  Update the value of a table field in the selected table row. Note: validations are not run.

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.
  key | Key value for the table row to update.
  fieldName | Column name to update.
  value | Value to write to the database field.

Returns:
  "true" if the field can be successfully written.

See Also:

bool espUpdateFields (HttpConn *conn, cchar *tableName, MprHash *data)

Write field values to a database row.

Description:
  This routine updates the current record with the given data and then saves the record to the database. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request $params() or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: ediWriteFields(rec, params()); The record runs field validations before saving to the database.

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.
  data | Hash of field names and values to use for the update.

Returns:
  "true" if the field can be successfully written. Returns false if field validations fail.

See Also:

bool espUpdateRec (HttpConn *conn, EdiRec *rec)

Write a record to the database.

Description:
  The record will be saved to the database after running any field validations. If any field validations fail to pass, the record will not be written and error details can be retrieved via $ediGetRecErrors. If the record is a new record and the "id" column is EDI_AUTO_INC, then the "id" will be assigned prior to saving the record.

Parameters:

  conn | HttpConn connection object.
  rec | Record to write to the database.

Returns:
  "true" if the record can be successfully written.

See Also:

cchar * espUri (HttpConn *conn, cchar *target)

Create a URI.

Description:
  Create a URI link by expansions tokens based on the current request and route state. The target parameter may contain partial or complete URI information. The missing parts are supplied using the current request and route tables. The resulting URI is a normalized, server-local URI (that begins with "/"). The URI will include any defined route prefix, but will not include scheme, host or port components.

Parameters:

  conn | HttpConn connection object.

  target

  The URI target. The target parameter can be a URI string or JSON style set of options. The target will have any embedded "{tokens}" expanded by using token values from the request parameters. If the target has an absolute URI path, that path is used directly after tokenization. If the target begins with "~", that character will be replaced with the route prefix. This is a very convenient way to create application top-level relative links.
  If the target is a string that begins with "{AT}" it will be interpreted as a controller/action pair of the form "{AT}Controller/action". If the "controller/" portion is absent, the current controller is used. If the action component is missing, the "list" action is used. A bare "{AT}" refers to the "list" action of the current controller.
  If the target starts with "{" it is interpreted as being a JSON style set of options that describe the link. If the target is a relative URI path, it is appended to the current request URI path.
  If the target is a JSON style of options, it can specify the URI components: scheme, host, port, path, reference and query. If these component properties are supplied, these will be combined to create a URI.
  If the target specifies either a controller/action or a JSON set of options, The URI will be created according to the route URI template. The template may be explicitly specified via a "route" target property. Otherwise, if an "action" property is specified, the route of the same name will be used. If these don't result in a usable route, the "default" route will be used.
  These are the properties supported in a JSON style "{ ... }" target:
  - scheme String URI scheme portion
  - host String URI host portion
  - port Number URI port number
  - path String URI path portion
  - reference String URI path reference. Does not include "#"
  - query String URI query parameters. Does not include "?"
  - controller String Controller name if using a Controller-based route. This can also be specified via the action option.
  - action String Action to invoke. This can be a URI string or a Controller action of the form {AT}Controller/action.
  - route String Route name to use for the URI template

Returns:
  A normalized, server-local Uri string.

Example:
  EspUri(conn, "http://example.com/index.html", 0);
  espUri(conn, "/path/to/index.html", 0);
  espUri(conn, "../images/splash.png", 0);
  espUri(conn, "~/static/images/splash.png", 0);
  espUri(conn, "${app}/static/images/splash.png", 0);
  espUri(conn, "@controller/checkout", 0);
  espUri(conn, "@controller/")
  espUri(conn, "@init")
  espUri(conn, "@")
  espUri(conn, "{ action: '@post/create' }", 0);
  espUri(conn, "{ action: 'checkout' }", 0);
  espUri(conn, "{ action: 'logout', controller: 'admin' }", 0);
  espUri(conn, "{ action: 'admin/logout'", 0);
  espUri(conn, "{ product: 'candy', quantity: '10', template: '/cart/${product}/${quantity}' }", 0);
  espUri(conn, "{ route: '~/STAR/edit', action: 'checkout', id: '99' }", 0);
  espUri(conn, "{ template: '~/static/images/${theme}/background.jpg', theme: 'blue' }", 0);.

See Also:

cchar * getMethod ()

Get the HTTP method.

Description:
  This is a convenience API to return the Http method.

Returns:
  The HttpConn.rx.method property.

See Also:

# EspRoute

EspRoute

EspRoute extended route configuration.

See Also:

Fields:

  char * |  | appModuleName | App module name when compiled flat.
  char * |  | appModulePath | App module path when compiled flat.
  char * |  | cacheDir | Directory for cached compiled controllers and views.
  char * |  | compile | Compile template.
  EspProc |  | controllerBase | Initialize base for a controller.
  char * |  | controllersDir | Directory for controllers.
  char * |  | dbDir | Directory for databases.
  Edi * |  | edi | Default database for this route.
  MprList * |  | env | Environment for compiler.
  int |  | keepSource | Preserve generated source.
  char * |  | layoutsDir | Directory for layouts.
  MprTime |  | lifespan | Default cache lifespan.
  char * |  | link | Link template.
  HttpRoute * |  | route | Back link to the owning route.
  char * |  | searchPath | Search path to use when locating compiler/linker.
  int |  | showErrors | Send server errors back to client.
  char * |  | staticDir | Directory for static web content.
  int |  | update | Auto-update modified ESP source.
  char * |  | viewsDir | Directory for views.

char * espBuildScript (HttpRoute *route, cchar *page, cchar *path, cchar *cacheName, cchar *layout, char **err)

Convert an ESP web page into compilable C code.

Description:
  This parses an ESP web page into an equivalent C source view.

Parameters:

  route | EspRoute object.
  page | ESP web page script.
  path | Pathname for the ESP web page. This is used to process include directives which are resolved relative to this path.
  cacheName | MD5 cache name. Not a full path.
  layout | Default layout page.
  err | Output parameter to hold any relevant error message.

Returns:
  C language code string for the web page.

See Also:

int espCache (HttpRoute *route, cchar *uri, int lifesecs, int flags)

Add caching for response content.

Description:
  This call configures caching for request responses. Caching may be used for any HTTP method, though typically it is most useful for state-less GET requests. Output data may be uniquely cached for requests with different request parameters (query, post and route parameters).
  When server-side caching is requested and manual-mode is not enabled, the request response will be automatically cached. Subsequent client requests will revalidate the cached content with the server. If the server-side cached content has not expired, a HTTP Not-Modified (304) response will be sent and the client will use its client-side cached content. This results in a very fast transaction with the client as no response data is sent. Server-side caching will cache both the response headers and content.
  If manual server-side caching is requested, the response will be automatically cached, but subsequent requests will require the handler to explicitly send cached content by calling $httpWriteCached.
  If client-side caching is requested, a "Cache-Control" Http header will be sent to the client with the caching "max-age" set to the lifesecs argument value. This causes the client to serve client-cached content and to not contact the server at all until the max-age expires. Alternatively, you can use $httpSetHeader to explicitly set a "Cache-Control header. For your reference, here are some keywords that can be used in the Cache-Control Http header.
  "max-age" Max time in seconds the resource is considered fresh. "s-maxage" Max time in seconds the resource is considered fresh from a shared cache. "public" marks authenticated responses as cacheable. "private" shared caches may not store the response. "no-cache" cache must re-submit request for validation before using cached copy. "no-store" response may not be stored in a cache. "must-revalidate" forces clients to revalidate the request with the server. "proxy-revalidate" similar to must-revalidate except only for proxy caches.
  Use client-side caching for static content that will rarely change or for content for which using "reload" in the browser is an adequate solution to force a refresh. Use manual server-side caching for situations where you need to explicitly control when and how cached data is returned to the client. For most other situations, use server-side caching.

Parameters:

  route | HttpRoute object.
  uri | URI to cache. If the URI is set to "*" all URIs for that action are uniquely cached. If the request has POST data, the URI may include such post data in a sorted query format. E.g. {uri: /buy?item=scarf&quantity=1}.
  lifesecs | Lifespan of cache items in seconds. If not set to positive integer, the lifesecs will default to the route lifespan.

  flags

  Cache control flags. Select ESP_CACHE_MANUAL to enable manual mode. In manual mode, cached content will not be automatically sent. Use $httpWriteCached in the request handler to write previously cached content.
  Select ESP_CACHE_CLIENT to enable client-side caching. In this mode a "Cache-Control" Http header will be sent to the client with the caching "max-age". WARNING: the client will not send any request for this URI until the max-age timeout has expired.
  Select HTTP_CACHE_RESET to first reset existing caching configuration for this route.
  Select HTTP_CACHE_COMBINED, HTTP_CACHE_ONLY or HTTP_CACHE_UNIQUE to define the server-side caching mode. Only one of these three mode flags should be specified.
  If the HTTP_CACHE_COMBINED flag is set, the request params (query, post data and route parameters) will be ignored and all request for a given URI path will cache to the same cache record.
  Select HTTP_CACHE_UNIQUE to uniquely cache requests with different request parameters. The URIs specified in $uris should not contain any request parameters.
  Select HTTP_CACHE_ONLY to cache only the exact URI with parameters specified in $uris. The parameters must be in sorted www-urlencoded format. For example: /example.esp?hobby=sailing&name=john.

Returns:
  A count of the bytes actually written.

See Also:

bool espCompile (HttpConn *conn, cchar *source, cchar *module, cchar *cacheName, int isView)

Compile a view or controller.

Description:
  This compiles ESP controllers and views into loadable, cached modules.

Parameters:

  conn | Http connection object.
  source | ESP source file name.
  module | Output module file name.
  cacheName | MD5 cache name. Not a full path.
  isView | Set to "true" if the source is a view.

Returns:
  "True" if the compilation is successful. Errors are logged and sent back to the client if EspRoute.showErrors is true.

See Also:

void espDefineAction (HttpRoute *route, cchar *targetKey, void *actionProc)

Define an action.

Description:
  Actions are C procedures that are invoked when specific URIs are routed to the controller/action pair.

Parameters:

  route | Route object.
  targetKey | Target key used to select the action in a HttpRoute target. This is typically a URI prefix.
  actionProc | EspProc callback procedure to invoke when the action is requested.

See Also:

void espDefineBase (HttpRoute *route, EspProc baseProc)

Define a base function to invoke for all controller actions.

Description:
  A base function can be defined that will be called before calling any controller action. This emulates a super class constructor.

Parameters:

  route | Route object.
  baseProc | Function to call just prior to invoking a controller action.

See Also:

void espDefineView (HttpRoute *route, cchar *path, void *viewProc)

Define a view.

Description:
  Views are ESP web pages that are executed to return presentation data back to the client.

Parameters:

  route | Http route object.
  path | Path to the ESP view source code.
  viewProc | EspViewPrococ callback procedure to invoke when the view is requested.

See Also:

char * espExpandCommand (cchar *command, cchar *source, cchar *module)

Expand a compile or link command template.

Description:
  This expands a command template and replaces "${tokens}" with their equivalent value. The supported tokens are:
  - ARCH - Build architecture (i386, x86_64)
  - CC - Compiler pathname
  - DEBUG - Compiler debug options (-g, -Zi, -Od)
  - INC - Include directory (out/inc)
  - LIB - Library directory (out/lib, out/bin)
  - LIBS - Required libraries directory (mod_esp, libappweb)
  - OBJ - Name of compiled source (out/lib/view-MD5.o)
  - OUT - Output module (view_MD5.dylib)
  - SHLIB - Shared library extension (.lib, .so)
  - SHOBJ - Shared object extension (.dll, .so)
  - SRC - Path to source code for view or controller (already templated)
  - TMP - System temporary directory
  - WINSDK - Path to the Windows SDK
  - VS - Path to Visual Studio

Parameters:

  command | Http connection object.
  source | ESP web page source pathname.
  module | Output module pathname.

Returns:
  An expanded command line.

See Also:

# EspSession

EspSession

ESP session state object.

See Also:

Fields:

  MprCache * |  | cache | Cache store reference.
  char * |  | id | Session ID key.
  MprTime |  | lifespan | Session inactivity timeout (msecs).

EspSession * espAllocSession (HttpConn *conn, cchar *id, MprTime lifespan)

Allocate a new session state object.

Description:

Parameters:

  conn | Http connection object.
  id | Unique session state ID.
  lifespan | Session lifespan in ticks.

Returns:
  A session state object.

See Also:

EspSession * espCreateSession (HttpConn *conn)

Create a session object.

Description:
  This call creates a session object if one does not already exist. Session state stores persist across individual HTTP requests.

Parameters:

  conn | Http connection object.

Returns:
  A session state object.

See Also:

void espDestroySession (EspSession *sp)

Destroy a session state object.

Description:

Parameters:

  sp | Session state object allocated with espAllocSession

See Also:

EspSession * espGetSession (HttpConn *conn, int create)

Get a session state object.

Description:

Parameters:

  conn | Http connection object.
  create | Set to "true" to create a session state object if one does not already exist for this client.

Returns:
  A session state object.

See Also:

char * espGetSessionID (HttpConn *conn)

Get the session ID.

Description:

Parameters:

  conn | Http connection object.

Returns:
  The session ID string.

See Also:

MprHash * espGetSessionObj (HttpConn *conn, cchar *key)

Get an object from the session state store.

Description:
  Retrieve an object from the session state store by deserializing all properties.

Parameters:

  conn | Http connection object.
  key | Session state key.

See Also:

cchar * espGetSessionVar (HttpConn *conn, cchar *name, cchar *defaultValue)

Get a session state variable.

Description:

Parameters:

  conn | Http connection object.
  name | Variable name to get.
  defaultValue | If the variable does not exist, return the defaultValue.

Returns:
  The variable value or defaultValue if it does not exist.

See Also:

int espSetSessionObj (HttpConn *conn, cchar *key, MprHash *value)

Set an object into the session state store.

Description:
  Store an object in the session state store by serializing all properties.

Parameters:

  conn | Http connection object.
  key | Session state key.
  value | Object to serialize.

See Also:

int espSetSessionVar (HttpConn *conn, cchar *name, cchar *value)

Set a session variable.

Description:

Parameters:

  conn | Http connection object.
  name | Variable name to set.
  value | Variable value to use.

Returns:
  A session state object.

See Also:

## Functions

EdiGrid * espGetGrid (HttpConn *conn)

Get the current database grid.

Description:
  The current grid is defined via $setGrid.

Returns:
  EdiGrid instance.

cchar * espGetSecurityToken (HttpConn *conn)

Get a unique security token.

Description:
  Security tokens help mitigate against replay attacks. The security token is stored in HttpRx.securityToken and in the session store.

Parameters:

  conn | HttpConn connection object.

Returns:
  The security token string.

bool espRemoveRec (HttpConn *conn, cchar *tableName, cchar *key)

Remove a record from a database table.

Description:
  Remove the record identified by the key value from the given table.

Parameters:

  conn | HttpConn connection object.
  tableName | Database table name.
  key | Key value of the record to remove.

Returns:
  Record instance of EdiRec.

MprList * getColumns (EdiRec *rec)

Get a list of column names.

Parameters:

  rec | Database record. If set to NULL, the current database record defined via $form() is used.

Returns:
  An MprList of column names in the given table. If there is no record defined, an empty list is returned.

cchar * getField (cchar *field)

Get a field from the current database record.

Description:
  The current grid is defined via $setRec.

Parameters:

  field | Field name to return.

Returns:
  String value for "field" in the current record.

EdiGrid * getGrid ()

Get the current database grid.

Description:
  The current grid is defined via $setGrid.

Returns:
  EdiGrid instance.

EdiRec * getRec ()

Get the current database record.

Description:
  The current record is defined via $setRec.

Returns:
  EdiRec instance.

bool hasGrid ()

Test if a current grid has been defined.

Description:
  The current grid is defined via $setRec.

Returns:
  "true" if a current grid has been defined.

bool hasRec ()

Test if a current record has been defined and save to the database.

Description:
  This call returns "true" if a current record is defined and has been saved to the database with a valid "id" field.

Returns:
  "true" if a current record with a valid "id" is defined.

EdiRec * readRec (cchar *tableName)

Read the identified record.

Description:
  Read the record identified by the request params("id") from the nominated table.

Parameters:

  tableName | Database table name.

Returns:
  The identified record. Returns NULL if the table or record cannot be found.

EdiGrid * readRecsWhere (cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read matching records.

Description:
  This runs a simple query on the database and returns matching records in a grid. The query selects all rows that have a "field" that matches the given "value".

Parameters:

  tableName | Database table name.
  fieldName | Database field name to evaluate.
  operation | Comparison operation. Set to "==", "!=", "<", ">", "<=" or ">=".
  value | Data value to compare with the field values.

Returns:
  A grid containing all matching records. Returns NULL if no matching records.

EdiGrid * readTable (cchar *tableName)

Read all the records in table from the database.

Description:
  This reads a table and returns a grid containing the table data.

Parameters:

  tableName | Database table name.

Returns:
  A grid containing all table rows. Returns NULL if the table cannot be found.

bool removeRec (cchar *tableName, cchar *key)

Remove a record from a database table.

Description:
  Remove the record identified by the key value from the given table.

Parameters:

  tableName | Database table name.
  key | Key value of the record to remove.

Returns:
  Record instance of EdiRec.

EdiGrid * setGrid (EdiGrid *grid)

Set the current database grid.

Returns:
  The grid instance. This permits chaining.

EdiRec * setRec (EdiRec *rec)

Set the current database record.

Description:
  The current record is used to supply data to various abbreviated controls, such as: text(), input(), checkbox and dropdown()

Returns:
  The grid instance. This permits chaining.

## Typedefs

typedef void(* EspProc)(HttpConn *conn).

Procedure callback.

typedef cchar*(* EdiValidationProc)(struct EdiValidation *vp, struct EdiRec *rec, cchar *fieldName, cchar *value).

Field validation callback procedure.

Parameters:

  vp | Validation structure reference.
  rec | Record to validate.
  fieldName | Field name to validate.
  value | Field value to validate.

See Also:

typedef void(* EspViewProc)(HttpConn *conn).

View procedure callback.

Parameters:

  conn | Http connection object.

See Also:

EdiProvider

Database provider interface.

Fields:

EdiValidation

Validation structure.

Fields:

  cvoid * |  | data | Allocated data that must be marked for GC.
  cvoid * |  | mdata | Non-GC (malloc) data.
  cchar * |  | name | Validation name.
  EdiValidationProc |  | vfn | Validation callback procedure.

Esp

Top level ESP structure.

Fields:

  MprHash * |  | actions | Table of actions.
  EdiService * |  | ediService | Database service.
  MprHash * |  | internalOptions | Table of internal HTML control options.
  int |  | inUse | Active ESP request counter.
  MprThreadLocal * |  | local | Thread local data.
  MprMutex * |  | mutex | Multithread lock.
  MprCache * |  | sessionCache | Session state cache.
  MprHash * |  | views | Table of views.

EspAction

ESP Action.

Description:
  Actions are run after a request URI is routed to a controller.

Fields:

  EspProc |  | actionProc | Action procedure to run to respond to the request.

See Also: