ESP Native API
Extensions
EspAbbrev | Abbreviated ESP API. |
EspParse | ESP page parser structure. |
EspReq | ESP request structure. |
EspRoute | EspRoute extended route configuration. |
Functions
cchar* | absuri(cchar *target, ...) |
Create an absolute URI with a scheme and host. | |
void | addHeader(cchar *key, cchar *fmt, ...) |
Add a header to the transmission using a format string. | |
void | addParam(cchar *name, cchar *value) |
Add a request parameter value if not already defined. | |
bool | canUser(cchar *abilities, bool warn) |
Test if a user has the required abilities. | |
EdiRec* | createRec(cchar *tableName, MprJson *data) |
Create a record and initialize field values. | |
bool | createRecFromParams(cchar *table) |
Create a record from the request parameters. | |
cchar* | createSession() |
Create a session state object. | |
void | destroySession() |
Destroy a session state object. | |
void | dontAutoFinalize() |
Don't auto-finalize this request. | |
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 | espAddHomeRoute(HttpRoute *route) |
Add a route for the home page. | |
void | espAddPak(HttpRoute *route, cchar *name, cchar *version) |
Add the specified pak to the pak.json packs list. | |
void | espAddParam(HttpConn *conn, cchar *var, cchar *value) |
Add a request parameter value if it is not already defined. | |
void | espAddRouteSet(HttpRoute *route, cchar *set) |
Add a route set. | |
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. | |
int | espBindProc(HttpRoute *route, cchar *pattern, void *actionProc) |
Define an action for a URI pattern. | |
char* | espBuildScript(HttpRoute *route, cchar *page, cchar *path, cchar *cacheName, cchar *layout, EspState *state, char **err) |
Convert an ESP web page into C code. | |
int | espCache(HttpRoute *route, cchar *uri, int lifesecs, int flags) |
Add caching for response content. | |
void | espClearCurrentSession(HttpConn *conn) |
Clear the current authenticated session. | |
bool | espCompile(HttpRoute *route, MprDispatcher *dispatcher, cchar *source, cchar *module, cchar *cacheName, int isView, char **errMsg) |
Compile an ESP page, controller or view. | |
EspRoute* | espCreateRoute(HttpRoute *route) |
Create an EspRoute object. | |
cchar* | espCreateSession(HttpConn *conn) |
Create a session state 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(HttpConn *conn) |
Destroy a session state object. | |
int | espEmail(HttpConn *conn, cchar *to, cchar *from, cchar *subject, MprTime date, cchar *mime, cchar *message, MprList *files) |
Send mail using sendmail. | |
char* | espExpandCommand(HttpRoute *route, cchar *command, cchar *source, cchar *module) |
Expand a compile or link command template. | |
void | espFinalize(HttpConn *conn) |
Indicate the request is finalized. | |
void | espFlush(HttpConn *conn) |
Flush transmit data. | |
HttpAuth* | espGetAuth() |
Get the current route HttpAuth object. | |
cchar* | espGetConfig(HttpRoute *route, cchar *key, cchar *defaultValue) |
Get a configuration value from the ESP pak.json. | |
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* | espGetCookie(HttpConn *conn, cchar *name) |
Get a request cookie. | |
cchar* | espGetCookies(HttpConn *conn) |
Get the request cookies. | |
void* | espGetData(HttpConn *conn) |
Get the private data reference for the current request set via setData | |
Edi* | espGetDatabase(HttpConn *conn) |
Get the current database instance. | |
cchar* | espGetDocuments(HttpConn *conn) |
Get the default documents directory for the request route. | |
EspRoute* | espGetEspRoute(HttpConn *conn) |
Get the current extended route information. | |
cchar* | espGetFeedback(HttpConn *conn, cchar *type) |
Get a feedback message defined via feedback | |
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. | |
MprJson* | espGetParams(HttpConn *conn) |
Get the request parameter hash table. | |
cchar* | espGetPath(HttpConn *conn) |
Get the request URI path string. | |
cchar* | espGetQueryString(HttpConn *conn) |
Get the request query string. | |
char* | espGetReferrer(HttpConn *conn) |
Get the referring URI. | |
HttpRoute* | espGetRoute() |
Get the current route HttpRoute object. | |
Edi* | espGetRouteDatabase(HttpRoute *route) |
Get the default database defined on a route. | |
cchar* | espGetRouteVar(HttpConn *conn, cchar *var) |
Get a route variable. | |
cchar* | espGetSessionID(HttpConn *conn, int create) |
Get the session state ID. | |
int | espGetStatus(HttpConn *conn) |
Get the response status. | |
char* | espGetStatusMessage(HttpConn *conn) |
Get the Http response status message. | |
MprList* | 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 | espHasPak(HttpRoute *route, cchar *name) |
Test if the ESP application includes the specified pak. | |
bool | espHasRec(HttpConn *conn) |
Test if a current record has been defined and save to the database. | |
int | espInit(HttpRoute *route, cchar *prefix, cchar *path) |
Initialize ESP. | |
void | espInitHtmlOptions(Esp *esp) |
Add HTLM internal options to the Esp.options hash. | |
int | espInitParser() |
Initialize the ESP configuration file parser. | |
bool | espIsCurrentSession(HttpConn *conn) |
Test if the connection is being made on behalf of the current, single authenticated user. | |
bool | espIsEof(HttpConn *conn) |
Test if the receive input stream is at end-of-file. | |
bool | espIsFinalized(HttpConn *conn) |
Test if the request has been finalized. | |
bool | espIsSecure(HttpConn *conn) |
Test if the connection is using SSL and is secure. | |
int | espLoadCompilerRules(HttpRoute *route) |
Load the compiler rules from esp-compile.json. | |
int | espLoadConfig(HttpRoute *route) |
Configure an ESP application. | |
bool | espMatchParam(HttpConn *conn, cchar *var, cchar *value) |
Match a request parameter with an expected value. | |
int | espOpen(MprModule *module) |
ESP initialization entry point. | |
EdiGrid* | espReadTable(HttpConn *conn, cchar *tableName) |
Read a table from the current database. | |
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 | espRemoveCookie(HttpConn *conn, cchar *name) |
Remove a cookie. | |
int | espRemoveHeader(HttpConn *conn, cchar *key) |
Remove a header from the transmission. | |
void | espRemoveSessionVar(HttpConn *conn, cchar *name) |
Remove a session state variable. | |
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 | espRenderConfig(HttpConn *conn) |
Render the client configuration string in JSON. | |
void | espRenderDocument(HttpConn *conn, cchar *path) |
Render an ESP document. | |
ssize | espRenderError(HttpConn *conn, int status, cchar *fmt, ...) |
Render an error message back to the client and finalize the request. | |
ssize | espRenderFeedback(HttpConn *conn, cchar *types) |
Render feedback messages. | |
ssize | espRenderFile(HttpConn *conn, cchar *path) |
Render the contents of a file back to the client. | |
ssize | espRenderSafe(HttpConn *conn, cchar *fmt, ...) |
Render a formatted string after HTML escaping. | |
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. | |
ssize | espRenderVar(HttpConn *conn, cchar *name) |
Render the value of a request variable to the client. | |
bool | espRenderView(HttpConn *conn, cchar *view, int flags) |
Render an ESP view page to the client. | |
EspRoute* | espRoute(HttpRoute *route, bool create) |
Return the corresponding EspRoute for the given Route. | |
int | espSaveConfig(HttpRoute *route) |
Save the in-memory ESP pak.json configuration to the default location for the ESP application defined by the specified route. | |
ssize | espSendGrid(HttpConn *conn, EdiGrid *grid, int flags) |
Send a database grid as a JSON string. | |
ssize | espSendRec(HttpConn *conn, EdiRec *rec, int flags) |
Send a database record as a JSON string. | |
ssize | espSendResult(HttpConn *conn, bool success) |
Send a JSON response result. | |
bool | espSetAutoFinalizing(HttpConn *conn, bool on) |
Enable auto-finalizing for this request. | |
int | espSetConfig(HttpRoute *route, cchar *key, cchar *value) |
Set a configuration value to the ESP pak.json. | |
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, MprTicks lifespan, bool isSecure) |
Set a cookie in the transmission. | |
void | espSetCurrentSession(HttpConn *conn) |
Set this authenticated session as the current session. | |
void | espSetData(HttpConn *conn, void *data) |
Set a private data reference for the current request. | |
void | espSetFeedback(HttpConn *conn, cchar *type, cchar *fmt, ...) |
Set a feedback message. | |
void | espSetFeedbackv(HttpConn *conn, cchar *type, cchar *fmt, va_list args) |
Send a feedback 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 | espSetNotifier(HttpConn *conn, HttpNotifier notifier) |
Define a notifier callback for this connection. | |
void | espSetParam(HttpConn *conn, cchar *var, cchar *value) |
Set a request parameter value. | |
EdiRec* | espSetRec(HttpConn *conn, EdiRec *rec) |
Set the current database record. | |
void | espSetStatus(HttpConn *conn, int status) |
Set a Http response status. | |
void | espShowRequest(HttpConn *conn) |
Show request details. | |
int | espStaticInitialize(EspModuleEntry entry, cchar *appName, cchar *routeName) |
Initialize a static library ESP module. | |
bool | espTestConfig(HttpRoute *route, cchar *key, cchar *desired) |
Test if a configuration property from the ESP pak.json has a desired value. | |
void | espUpdateCache(HttpConn *conn, cchar *uri, cchar *data, int lifesecs) |
Update the cached content for a request. | |
bool | espUpdateRec(HttpConn *conn, EdiRec *rec) |
Write a record to the database. | |
cchar* | espUri(HttpConn *conn, cchar *target) |
Create a URI. | |
bool | feedback(cchar *type, cchar *fmt, ...) |
Set a feedback message. | |
void | finalize() |
Finalize the response. | |
void | flush() |
Flush transmit data. | |
HttpAuth* | getAuth() |
Get the auth object for the current route. | |
MprList* | getColumns(EdiRec *rec) |
Get a list of column names. | |
cchar* | getConfig(cchar *field) |
Get a field from the application pak.json configuration. | |
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. | |
void* | getData() |
Get the private data reference for the current request set via setData | |
Edi* | getDatabase() |
Get the current database instance. | |
MprDispatcher* | getDispatcher() |
Get the connection dispatcher object. | |
cchar* | getDocuments() |
Get the default document root directory for the request route. | |
EspRoute* | getEspRoute() |
Get the extended route EspRoute structure. | |
cchar* | getFeedback(cchar *type) |
Get a feedback message defined via feedback | |
cchar* | getField(EdiRec *rec, cchar *field) |
Get a field from the current database record. | |
cchar* | getFieldError(cchar *field) |
Test if a field in the current record has input validation errors. | |
EdiGrid* | getGrid() |
Get the current database grid. | |
cchar* | getHeader(cchar *key) |
Get an rx http header. | |
cchar* | getMethod() |
Get the HTTP method. | |
cchar* | getPath() |
Get the request URI path string. | |
cchar* | getQuery() |
Get the HTTP URI query string. | |
EdiRec* | getRec() |
Get the current database record. | |
cchar* | getReferrer() |
Get the referring URI. | |
EspReq* | getReq() |
Get the ESP request object. | |
HttpRoute* | getRoute() |
Get the HttpRoute object for the current route. | |
cchar* | getSecurityToken() |
Get the security token. | |
cchar* | getSessionID() |
Get the session state ID. | |
cchar* | getSessionVar(cchar *name) |
Get a session state variable. | |
MprList* | 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 | input(cchar *field, cchar *options) |
Render an input field as part of a form. | |
void | inputSecurityToken() |
Render an input field with a hidden XSRF security token. | |
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. | |
MprHash* | makeHash(cchar *fmt, ...) |
Make a hash table container of property values. | |
MprJson* | makeJson(cchar *fmt, ...) |
Make a JSON object container of property values. | |
EdiRec* | makeRec(cchar *content) |
Make a record. | |
cchar* | makeUri(cchar *target) |
Create a URI. | |
cchar* | md5(cchar *str) |
Get an MD5 checksum. | |
bool | modeIs(cchar *check) |
Test the the application mode. | |
cchar* | nonce() |
Generate a onetime random string. | |
cchar* | param(cchar *name) |
Get a request parameter. | |
MprJson* | params() |
Get the request parameter hash table. | |
EdiRec* | readRec(cchar *tableName, cchar *key) |
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* | readTable(cchar *tableName) |
Read all the records in table from the database. | |
EdiGrid* | readWhere(cchar *tableName, cchar *fieldName, cchar *operation, cchar *value) |
Read matching records. | |
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 | removeCookie(cchar *name) |
Remove a cookie. | |
bool | removeRec(cchar *tableName, cchar *key) |
Remove a record from a database table. | |
void | removeSessionVar(cchar *name) |
Remove a session state variable. | |
ssize | render(cchar *fmt, ...) |
Render a formatted string. | |
ssize | renderCached() |
Render cached content. | |
ssize | renderConfig() |
Render the pak.json. | |
void | renderError(int status, cchar *fmt, ...) |
Render an error message back to the client and finalize the request. | |
void | renderFeedback(cchar *types) |
Render feedback messages. | |
ssize | renderFile(cchar *path) |
Render a file back to the client. | |
ssize | renderSafe(cchar *fmt, ...) |
Render a formatted string after HTML escaping. | |
ssize | renderString(cchar *s) |
Render a string of data to the client. | |
ssize | renderVar(cchar *name) |
Render the value of a request variable to the client. | |
void | renderView(cchar *view) |
Render an ESP page to the client. | |
int | runCmd(cchar *command, char *input, char **output, char **error, MprTicks timeout, int flags) |
Run a command. | |
void | scripts(cchar *patterns) |
Render scripts. | |
void | securityToken() |
Add the security token to the response. | |
ssize | sendGrid(EdiGrid *grid) |
Send a Edatabase grid as a JSON string. | |
ssize | sendRec(EdiRec *rec) |
Send a database record as a JSON string. | |
void | sendResult(bool status) |
Send a JSON response result. | |
cchar* | session(cchar *name) |
Get a session state variable. | |
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, MprTicks lifespan, bool isSecure) |
Define a cookie header to send with the response. | |
void | setData(void *data) |
Set a private data reference for the current request. | |
EdiRec* | setField(EdiRec *rec, cchar *fieldName, cchar *value) |
Update a record field without writing to the database. | |
EdiRec* | setFields(EdiRec *rec, MprJson *data) |
Update record fields without writing to the database. | |
EdiGrid* | setGrid(EdiGrid *grid) |
Set the current database grid. | |
void | setHeader(cchar *key, cchar *fmt, ...) |
Set a transmission header. | |
void | setIntParam(cchar *name, int value) |
Set an integer request parameter value. | |
void | setNotifier(HttpNotifier notifier) |
Set a notifier callback for the connection. | |
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, MprTicks timeout, void *data) |
Create a timeout event. | |
void | showRequest() |
Show request details. | |
void | stylesheets(cchar *patterns) |
Render stylesheets. | |
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, MprJson *data) |
Write field values to a database row. | |
bool | updateRec(EdiRec *rec) |
Write a record to the database. | |
bool | updateRecFromParams(cchar *table) |
Update a record from the request parameters. | |
cchar* | uri(cchar *target, ...) |
Create a URI link. |
Typedefs
Esp | Top level ESP structure. |
EspAction | ESP Action. |
EspModuleEntry | Entry point for a loadable ESP module. |
EspProc | Procedure callback. |
EspViewProc | View procedure callback. |
Defines
#define | ESP_COMPILE_JSON "esp-compile.json" |
Compile rules filename. | |
#define | ESP_COMPILE_OPTIMIZED 1 |
Override to compile in release mode. | |
#define | ESP_COMPILE_SYMBOLS 0 |
Override to compile in debug mode. | |
#define | ESP_LIFESPAN (3600 * TPS) |
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. | |
#define | ME_ESP_EMAIL_TIMEOUT (60 * 1000) |
Timeout for sending email. | |
#define | ME_ESP_RELOAD_TIMEOUT (5 * 1000) |
Timeout for reloading esp modules. |
EspAbbrev
Abbreviated ESP API.
- Description:
- This is a short-form API that uses the current HttpConn connection object. These APIs are designed to be terse and highly readable. Consequently, they are not prefixed with "esp".
- See Also:
- API Stability:
- Stable.
- Fields:
-
Create an absolute URI with a scheme and host.
- Parameters:
-
target The URI target. See httpLink for details. ... arguments to the formatted target string.
- Returns:
- A normalized, absolute Uri string containing scheme and host.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Add a request parameter value if not already defined.
- Parameters:
-
name Name of the request parameter to set. value Value to set.
- API Stability:
- Evolving.
- See Also:
Test if a user has the required abilities.
- Parameters:
-
abilities Comma separated list of abilities to test for. If null, then use the required abilities defined for the current request route. warn If true, warn the user via sendResult
- Returns:
- True if the user has all the required abilities.
- API Stability:
- Prototype.
- See Also:
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. The record is remembered for this request as the "current" record and can be retrieved via: getRec()
- Parameters:
-
tableName Database table name. data Json object with field values.
- Returns:
- EdRec instance.
- API Stability:
- Evolving.
- See Also:
Create a record from the request parameters.
- Description:
- A new record is created with the request parameters in the specified table. The record is remembered for this request as the "current" record and can be retrieved via: getRec()
- Parameters:
-
table Database table to update.
- Returns:
- True if the update is successful.
- API Stability:
- Prototype.
- See Also:
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.
- Returns:
- Session ID string.
- API Stability:
- Evolving.
- See Also:
Destroy a session state object.
- Description:
- This will emit an expired cookie to the client to force it to erase the session cookie.
- API Stability:
- Evolving.
- See Also:
Don't auto-finalize this request.
- API Stability:
- Evolving.
- See Also:
Set a feedback message.
- Description:
- Feedback messages are a convenient way to aggregate messages state information in the response. The getFeedback API can be used to retrieve feedback messages. Feedback messages are removed at the completion of the request.
- Parameters:
-
type type of feedback message. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical". fmt Printf style formatted string to use as the message.
- Returns:
- True if the request has been successful so far, i.e. there is not an error feedback message defined. Return false if there is an error feedback defined. This permits feedback to be chained as: sendResult(feedback("error", ...));.
- API Stability:
- Evolving.
- See Also:
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
- API Stability:
- Evolving.
- See Also:
Flush transmit data.
- Description:
- This writes any buffered data.
- API Stability:
- Evolving.
- See Also:
Get the auth object for the current route.
- API Stability:
- Prototype.
- See Also:
Get a list of column names.
- Parameters:
-
rec Database record.
- Returns:
- An MprList of column names in the given table. If there is no record defined, an empty list is returned.
- API Stability:
- Evolving.
- See Also:
Get a field from the application pak.json configuration.
- Parameters:
-
field Property field name in pak.json. May contain dots.
- Returns:
- The field value. Returns "" if the field is not found.
- API Stability:
- Deprecated.
- See Also:
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 EspAbbrev APIs take an HttpConn object as an argument.
- Returns:
- HttpConn connection instance object.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Get the private data reference for the current request set via setData
- Returns:
- Reference to private data.
- API Stability:
- Prototype.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Get the connection dispatcher object.
- Returns:
- MprDispatcher connection dispatcher instance object.
- API Stability:
- Evolving.
- See Also:
Get the default document root directory for the request route.
- Returns:
- A directory path name.
- API Stability:
- Evolving.
- See Also:
Get the extended route EspRoute structure.
- Returns:
- EspRoute instance.
- API Stability:
- Evolving.
- See Also:
Get a feedback message defined via feedback
- Parameters:
-
type type of feedback message to retrieve. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".
- Returns:
- Reference to private data.
- API Stability:
- Evolving.
- See Also:
Get a field from the current database record.
- Parameters:
-
rec Database record. field Field name to return.
- Returns:
- String value for "field" in the current record.
- API Stability:
- Evolving.
- See Also:
Test if a field in the current record has input validation errors.
- API Stability:
- Prototype.
- See Also:
Get the current database grid.
- Description:
- The current grid is defined via setGrid
- Returns:
- EdiGrid instance.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Get the request URI path string.
- Description:
- This is a convenience API to return the request URI path. This is the portion after the application/route prefix.
- Returns:
- The espGetConn()->rx->pathInfo.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Get the current database record.
- Returns:
- EdiRec instance.
- API Stability:
- Evolving.
- See Also:
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 uri("~").
- Returns:
- String URI back to the referring URI. If no referrer is defined, refers to the home URI.
- API Stability:
- Evolving.
- See Also:
Get the ESP request object.
- Returns:
- EspReq connection instance object.
- API Stability:
- Evolving.
- See Also:
Get the HttpRoute object for the current route.
- API Stability:
- Evolving.
- See Also:
Get the security token.
- Description:
- To minimize form replay attacks, a security token may be required for POST requests on a route. Client-side Javascript must then send this token as a request header in subsquent POST requests. To configure a route to require security tokens, call httpSetRouteXsrf
- Returns:
- The security token.
- API Stability:
- Evolving.
- See Also:
Get the session state ID.
- Description:
- This will get a session and return the session ID. This will create a new session state storage area if one does not already exist.
- Returns:
- The session state identifier string.
- API Stability:
- Evolving.
- See Also:
Get a session state variable.
- Description:
- The session API is an alias for this routine.
- Parameters:
-
name Variable name to get.
- Returns:
- The session variable value. Returns NULL if not set.
- API Stability:
- Evolving.
- See Also:
Get the uploaded files.
- Description:
- Get the list of uploaded files.
- Returns:
- A list of HttpUploadFile objects.
- API Stability:
- Evolving.
- See Also:
Get the request URI string.
- Description:
- This is a convenience API to return the request URI.
- Returns:
- The espGetConn()->rx->uri.
- API Stability:
- Evolving.
- See Also:
Test if a current grid has been defined.
- Returns:
- "true" if a current grid has been defined.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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. This control should not be used if using the esp-angular-mvc or other similar client-side Javascript framework- 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 These are in JSON string form and are converted to attributes to pass to the input element - noescape Boolean Do not HTML escape the text before rendering.
- ... Other options are converted and rendered as HTML attributes.
- API Stability:
- Evolving.
- See Also:
Render an input field with a hidden XSRF security token.
- Description:
- Security tokens are used to help guard against CSRF threats. This call will generate a hidden input field that includes the CSRF security token for the form. This call should not be included in Angular client applications as the Angular framework will automatically handle the security token.
- API Stability:
- Prototype.
- See Also:
Test if the receive input stream is at end-of-file.
- Returns:
- "true" if there is no more receive data to read.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Test if the connection is using SSL and is secure.
- Returns:
- "true" if the connection is using SSL.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Make a JSON object container of property values.
- Description:
- This routine formats the given arguments, parses the result into a JSON object.
- Parameters:
-
fmt Printf style format string. ... arguments.
- Returns:
- MprJson instance.
- API Stability:
- Evolving.
- See Also:
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' }");.
- API Stability:
- Evolving.
- See Also:
Get an MD5 checksum.
- Parameters:
-
str String to hash.
- Returns:
- An allocated MD5 checksum string.
- API Stability:
- Prototype.
- See Also:
Test the the application mode.
- Description:
- This is typically set to "debug" or "release". The mode is defined by the "profile" property in the pak.json.
- Parameters:
-
check Mode to compare with the current application mode.
- Returns:
- True if the current app mode matches the check mode.
- API Stability:
- Prototype.
- See Also:
Generate a onetime random string.
- Returns:
- An MD5 encoded random string.
- API Stability:
- Prototype.
- See Also:
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. Returns NULL if the parameter is not defined.
- API Stability:
- Evolving.
- See Also:
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:
- MprJson instance containing the request parameters.
- API Stability:
- Evolving.
- See Also:
Read the identified record.
- Description:
- Read the record identified by the request param("id") from the nominated table. The record is remembered for this request as the "current" record and can be retrieved via: getRec()
- Parameters:
-
tableName Database table name. key Key value of the record to read.
- Returns:
- The identified record. Returns NULL if the table or record cannot be found.
- API Stability:
- Evolving.
- See Also:
Read a record identified by key value.
- Description:
- Read a record from the given table as identified by the key value. The record is remembered for this request as the "current" record and can be retrieved via: getRec()
- Parameters:
-
tableName Database table name. key Key value of the record to read.
- Returns:
- Record instance of EdiRec.
- API Stability:
- Evolving.
- See Also:
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". The record is remembered for this request as the "current" record and can be retrieved via: getRec()
- 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.
- API Stability:
- Evolving.
- See Also:
Read all the records in table from the database.
- Description:
- This reads a table and returns a grid containing the table data. The grid of records is remembered for this request as the "current" grid and can be retrieved via: getGrid()
- Parameters:
-
tableName Database table name.
- Returns:
- A grid containing all table rows. Returns NULL if the table cannot be found.
- API Stability:
- Evolving.
- See Also:
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". The grid of records is remembered for this request as the "current" grid and can be retrieved via: getGrid()
- 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.
- API Stability:
- Evolving.
- See Also:
Read receive body content.
- Description:
- Read body content from the client. This will not block by default. Use httpReadBlock for more options to read data.
- Parameters:
-
buf Buffer to accept content data. size Size of the buffer.
- Returns:
- A count of bytes read into the buffer.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Redirect the client back to the referrer.
- Description:
- Redirect the client to the referring URI.
- API Stability:
- Evolving.
- See Also:
Remove a cookie.
- Parameters:
-
name Cookie name.
- API Stability:
- Evolving.
- See Also:
Remove a record from a database table.
- Description:
- Remove the record identified by the key value from the given table. If the removal succeeds, the feedback message {inform: "Deleted Record"} will be created. If the removal fails, a feedback message {error: "Cannot delete Record"} will be created.
- Parameters:
-
tableName Database table name. key Key value of the record to remove.
- Returns:
- Record instance of EdiRec.
- API Stability:
- Evolving.
- See Also:
Remove a session state variable.
- Parameters:
-
name Variable name to set.
- API Stability:
- Prototype.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Render the pak.json.
- Returns:
- A count of the bytes actually written.
- API Stability:
- Prototype.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Render feedback messages.
- Description:
- Feedback notices are one-time messages that are passed to the next request (only). See espSetFeedback and feedback for how to define feedback messages. This API will render feedback messages as HTML in place of the renderFeedback call in ESP page.
- Parameters:
-
types Types of feedback message to retrieve. Set to "*" to retrieve all types of feedback. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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:
-
s String containing the data to write.
- Returns:
- A count of the bytes actually written.
- API Stability:
- Evolving.
- See Also:
Render the value of a request variable to the client.
If a request parameter is not found by the given name, consult the session store for a variable the same name- Description:
- This writes the value of a request variable after HTML escaping its value.
- Parameters:
-
name Form variable name.
- Returns:
- A count of the bytes actually written.
- API Stability:
- Evolving.
- See Also:
Render an ESP page to the client.
- Parameters:
-
view View name. The view name is interpreted relative to the matching route documents directory and may omit an ESP extension.
- API Stability:
- Evolving.
- See Also:
Run a command.
- Description:
- Run a command and return output.
- Parameters:
-
command Command line and arguments to run. input Input data to pass to the command. Set to null if not required. output Pointer to accept command standard output response. Set to null if not required. error Pointer to accept command standard error response. Set to null if not required. flags MprCmd flags. Use MPR_CMD_DETACH to run in the background. timeout Time in milliseconds to wait for the command to complete and exit.
- API Stability:
- Prototype.
- See Also:
Render scripts.
- Description:
- This renders script elements for all matching filenames on the server.
- Parameters:
-
patterns An enhanced glob-style expression pattern. The format is is a comma separated string of filename expressions. Each expression may contain the wildcard tokens: "*" which matches any filename portion, "**" which matches any filename portion in any subdirectory. An expression may be prefixed with "!" to exclude files of that expression.
- API Stability:
- Deprecated.
- See Also:
Add the security token to the response.
- Description:
- To minimize form replay attacks, a security token may be required for POST requests on a route. This call will set a security token in the response as a response header and as a response cookie. Client-side Javascript must then send this token as a request header in subsquent POST requests. To configure a route to require security tokens, call httpSetRouteXsrf
- API Stability:
- Evolving.
- See Also:
Get a session state variable.
- Description:
- This is a convenient alias for getSessionVar
- Parameters:
-
name Variable name to get.
- Returns:
- The session variable value. Returns NULL if not set.
- API Stability:
- Evolving.
- See Also:
Set the current request connection.
- Parameters:
-
conn The HttpConn connection object to define.
- API Stability:
- Evolving.
- See Also:
Set the transmission (response) content mime type.
- Description:
- Set the mime type Http header in the transmission.
- Parameters:
-
mimeType Mime type string.
- API Stability:
- Evolving.
- See Also:
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 in seconds. isSecure Boolean Set to "true" if the cookie only applies for SSL based connections.
- API Stability:
- Evolving.
- See Also:
Set a private data reference for the current request.
- Returns:
- Reference to private data.
- API Stability:
- Prototype.
- See Also:
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 updateRec
- Parameters:
-
rec Record to update. fieldName Record field name to update. value Value to update.
- Returns:
- The record instance if successful, otherwise NULL.
- API Stability:
- Evolving.
- See Also:
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 ediUpdateRec
- Parameters:
-
rec Record to update. data Json object of field data.
- Returns:
- The record instance if successful, otherwise NULL.
- API Stability:
- Evolving.
- See Also:
Set the current database grid.
- Returns:
- The grid instance. This permits chaining.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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:
-
name Name of the request parameter to set. value Integer value to set.
- API Stability:
- Evolving.
- See Also:
Set a notifier callback for the connection.
This wraps httpSetConnNotifier and calls espSetConn before invoking the notifier for connection events- Parameters:
-
notifier Callback function.
- API Stability:
- Evolving.
- See Also:
Set a request parameter value.
- Description:
- Set the value of a named request parameter to a string value. Parameters are defined via requeset POST data or request URI queries. This API permits these initial request parameters to be set or modified.
- Parameters:
-
name Name of the request parameter to set. value Value to set.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Set a session state variable.
- Parameters:
-
name Variable name to set. value Value to set.
- API Stability:
- Evolving.
- See Also:
Set a Http response status.
- Description:
- Set the Http response status for the request. This defaults to 200 (OK).
- Parameters:
-
status Http status code.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
Show request details.
- Description:
- This echoes request details back to the client. This is useful as a debugging tool.
- API Stability:
- Evolving.
- See Also:
Render stylesheets.
- Description:
- This renders stylesheet elements for all matching filenames on the server.
- Parameters:
-
patterns An enhanced glob-style expression pattern. The format is is a comma separated string of filename expressions. Each expression may contain the wildcard tokens: "*" which matches any filename portion, "**" which matches any filename portion in any subdirectory. An expression may be prefixed with "!" to exclude files of that expression.
- API Stability:
- Deprecated.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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.
- API Stability:
- Evolving.
- See Also:
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 Json object of fields to update.
- Returns:
- "true" if the field can be successfully written. Returns false if field validations fail.
- API Stability:
- Evolving.
- See Also:
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. If the update succeeds, the feedback message {inform: "Saved Record"} will be created. If the update fails, a feedback message {error: "Cannot save Record"} will be created.
- Parameters:
-
rec Record to write to the database.
- Returns:
- "true" if the record can be successfully written.
- API Stability:
- Evolving.
- See Also:
Update a record from the request parameters.
- Description:
- The record identified by the params(id) is read and updated with the request parameters.
- Parameters:
-
table Database table to update.
- Returns:
- True if the update is successful.
- API Stability:
- Prototype.
- See Also:
Create a URI link.
\par \b Description: Create a URI link based on a given target an expanding embedded tokens based on the current request and route state. The target URI parameter may contain partial or complete URI information. The missing parts are supplied using the current request and route tables- 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 service/action pair of the form "{AT}Service/action". If the "service/" portion is absent, the current service is used. If the action component is missing, the "list" action is used. A bare "{AT}" refers to the "list" action of the current service.
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 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 service/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 "?"
- service String Service name if using a Service-based route. This can also be specified via the action option.
- action String Action to invoke. This can be a URI string or a Service action of the form {AT}Service/action.
- route String Route name to use for the URI template
... arguments to the formatted target string.
- Returns:
- A normalized Uri string.
- API Stability:
- Evolving.
- Remarks:
- Examples:
uri("http://example.com/index.html"); uri("/path/to/index.html"); uri("../images/splash.png"); uri("~/static/images/splash.png"); uri("${app}/static/images/splash.png"); uri("@service/checkout"); uri("@service/") // Service = Service, action = index uri("@init") // Current service, action = init uri("@") // Current service, action = index uri("{ action: '@post/create' }"); uri("{ action: 'checkout' }"); uri("{ action: 'logout', service: 'admin' }"); uri("{ action: 'admin/logout'"); uri("{ product: 'candy', quantity: '10', template: '/cart/${product}/${quantity}' }"); uri("{ route: '~/STAR/edit', action: 'checkout', id: '99' }"); uri("{ template: '~/static/images/${theme}/background.jpg', theme: 'blue' }");
- See Also:
EspParse
ESP page parser structure.
- See Also:
- Esp
EspReq
ESP request structure.
- API Stability:
- Internal.
- See Also:
- Esp
- Fields:
-
int autoFinalize Request is or will be auto-finalized. cchar * commandLine Command line for compile/link. void * data Custom data for request (managed). Edi * edi Database for this request. Esp * esp Convenient esp reference. MprHash * feedback Feedback messages. int lastDomID Last generated DOM ID. MprHash * lastFeedback Feedback messages from the last request. HttpNotifier notifier Connection Http state change notification callback. HttpRoute * route Route reference. int sessionProbed Already probed for session store. void * staticData Custom data for request (unmanaged).
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Add a request parameter value if it is not already defined.
- Parameters:
-
conn HttpConn connection object. var Name of the request parameter to set. value Value to set.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- Session ID string.
- API Stability:
- Stable.
- See Also:
- Esp
Destroy a session state object.
- Description:
- This will destroy the server-side session state and emit an expired cookie to the client to force it to erase the session cookie.
- Parameters:
-
conn HttpConn connection object.
- API Stability:
- Stable.
- See Also:
- Esp
Indicate the request is finalized.
- Description:
- Calling this routine indicates that the handler has fully finished processing the request including processing all input, generating a full response and any other required processing. This call will invoke httpFinalizeOutput and then set the request finalized flag. If the request is already finalized, this call does nothing. A handler MUST call httpFinalize when it has completed processing a request. As background: there are three finalize concepts: HttpTx.finalizedOutput means the handler has generated all the response output but it may not yet be fully transmited through the pipeline and to the network by the connector. HttpTx.finalizedConnector means the connector has sent all the output to the network. HttpTx.finalized means the application has fully processed the request including reading all the input data it wishes to read and has generated all the output that will be generated. A fully finalized request has both HttpTx.finalized and HttpTx.finalizedConnector true.
- Parameters:
-
conn HttpConn connection object.
- API Stability:
- Stable.
- See Also:
- Esp
Flush transmit data.
- Description:
- This writes any buffered data.
- Parameters:
-
conn HttpConn connection object.
- API Stability:
- Stable.
- See Also:
- Esp
Get the current route HttpAuth object.
- Returns:
- The HttpAuth object.
- API Stability:
- Stable.
- See Also:
- Esp
Get the current request connection.
- Returns:
- The HttpConn connection object.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Get a request cookie.
- Description:
- Get the cookie for the given name.
- Parameters:
-
conn HttpConn connection object. name Cookie name to retrieve.
- Returns:
- The cookie value Return null if the cookie is not defined.
- API Stability:
- Stable.
- See Also:
- Esp
Get the request cookies.
- Description:
- Get the cookies defined in the current request. This returns the HTTP cookies header with all cookies in one string.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- Return a string containing the cookies sent in the Http header of the last request.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Get the default documents directory for the request route.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- A directory path name.
- API Stability:
- Stable.
- See Also:
- Esp
Get the current extended route information.
- Returns:
- EspRoute instance.
- API Stability:
- Evolving.
- See Also:
- Esp
Get a feedback message defined via feedback
- Parameters:
-
conn HttpConn object. type type of feedback message to retrieve. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".
- Returns:
- Reference to the feedback message.
- API Stability:
- Evolving.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Evolving.
- See Also:
- Esp
Get the HTTP method.
- Description:
- This is a convenience API to return the Http method.
- Returns:
- The HttpConn.rx.method property.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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:
- MprJson instance containing the request parameters.
- API Stability:
- Stable.
- See Also:
- Esp
Get the request URI path string.
- Description:
- This is a convenience API to return the request URI path. This is the request URI path after removing query parameters. It does not include the application route prefix.
- Returns:
- The espGetConn()->rx->pathInfo.
- API Stability:
- Evolving.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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 uri("~").
- Parameters:
-
conn HttpConn connection object.
- Returns:
- String URI back to the referring URI. If no referrer is defined, refers to the home URI.
- API Stability:
- Stable.
- See Also:
- Esp
Get the current route HttpRoute object.
- Returns:
- The HttpRoute object.
- API Stability:
- Stable.
- See Also:
- Esp
Get the default database defined on a route.
- Parameters:
-
route HttpRoute object.
- Returns:
- Database instance object.
- API Stability:
- Stable.
- See Also:
- Esp
Get a route variable.
- Description:
- Get the value of a request route variable.
- Parameters:
-
conn HttpConn connection object. var Name of the request parameter to retrieve.
- Returns:
- String containing the route variable value. Caller should not free.
- API Stability:
- Evolving.
- See Also:
- Esp
Get the session state ID.
- Description:
- This will get the session and return the session ID. This will create a new session state storage area if create is true and one does not already exist. This can be used to test if the session state exists for this connection.
- Parameters:
-
conn HttpConn connection object. create Set to true to create a new session if one does not already exist.
- Returns:
- The session state identifier string.
- API Stability:
- Evolving.
- See Also:
- Esp
Get the response status.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- An integer Http response code. Typically 200 is success.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Get the uploaded files.
- Description:
- Get the list of uploaded files. This list entries are HttpUploadFile objects.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- A list of HttpUploadFile objects.
- API Stability:
- Stable.
- See Also:
- Esp
Get the request URI string.
- Description:
- This is a convenience API to return the request URI. This is the request URI after removing query parameters. It includes any application route prefix.
- Returns:
- The espGetConn()->rx->uri.
- API Stability:
- Stable.
- See Also:
- Esp
Test if a current grid has been defined.
- Returns:
- "True" if a current grid has been defined.
- API Stability:
- Deprecated.
- See Also:
- Esp
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.
- API Stability:
- Deprecated.
- See Also:
- Esp
Test if the connection is being made on behalf of the current, single authenticated user.
- Description:
- Set esp.login.single to true to enable current session tracking.
- Returns:
- True if the.
- API Stability:
- Evolving.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Test if the request has been 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.
- API Stability:
- Stable.
- See Also:
- Esp
Test if the connection is using SSL and is secure.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- "True" if the connection is using SSL.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Read a table from the current database.
- Parameters:
-
conn HttpConn connection object. tableName Database table name.
- Returns:
- An EDI grid containing data for the table.
- API Stability:
- Evolving.
- See Also:
- Esp
Read receive body content.
Use httpReadBlock for more options to read data- Description:
- Read body content from the client. This call does not block.
- 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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Redirect the client back to the referrer.
- Description:
- Redirect the client to the referring URI.
- Parameters:
-
conn HttpConn connection object.
- API Stability:
- Stable.
- See Also:
- Esp
Remove a cookie.
- Parameters:
-
conn HttpConn connection object. name Cookie name.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Remove a session state variable.
- Parameters:
-
conn HttpConn connection object. name Variable name to set.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Render the client configuration string in JSON.
- Parameters:
-
conn HttpConn connection object.
- Returns:
- A count of the bytes actually written.
- API Stability:
- PRototype.
- See Also:
- Esp
Render an ESP document.
- Description:
- If the document is an ESP page, it will be rendered as a view via espRenderDocument. Otherwise, it will be rendered using the fileHandler as a static document.
- Parameters:
-
conn Http connection object. path Relative pathname from route->documents to the document to render.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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:
-
conn HttpConn connection object. fmt Printf style formatted string. ... Arguments for fmt.
- Returns:
- A count of the bytes actually written.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Render the value of a request variable to the client.
If a request parameter is not found by the given name, consult the session store for a variable the same name- Description:
- This writes the value of a request variable after HTML escaping its value.
- Parameters:
-
conn HttpConn connection object. name Form variable name.
- Returns:
- A count of the bytes actually written.
- API Stability:
- Stable.
- See Also:
- Esp
Render an ESP view page to the client.
- Parameters:
-
conn Http connection object. view View name. The view name is interpreted relative to the matching route documents directory and may omit an ESP extension. flags Reserved. Set to zero.
- Returns:
- True if a vew can be rendered.
- API Stability:
- Evolving.
- See Also:
- Esp
Send a database grid as a JSON string.
- Description:
- The JSON string is rendered as part of an enclosing "{ data: JSON }" wrapper.
- Parameters:
-
conn HttpConn connection object. grid EDI grid. flags Reserved. Set to zero.
- Returns:
- Number of bytes rendered.
- API Stability:
- Evolving.
- See Also:
- Esp
Send a database record as a JSON string.
- Description:
- The JSON string is rendered as part of an enclosing "{ data: JSON }" wrapper.
- Parameters:
-
conn HttpConn connection object. rec EDI record. flags Reserved. Set to zero.
- Returns:
- Number of bytes rendered.
- API Stability:
- Evolving.
- See Also:
- Esp
Send a JSON response result.
- Description:
- This renders a JSON response including the request success status, feedback message and field errors. The field errors apply to the current EDI record. The format of the response is: "{ success: STATUS, feedback: {messages}, fieldErrors: {messages}}" wrapper. The feedback messages are created via the espSetFeedback API. Field errors are created by ESP validations.
- Parameters:
-
conn HttpConn connection object. success True if the operation was a success.
- Returns:
- Number of bytes sent.
- API Stability:
- Evolving.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Set the current request connection.
- Parameters:
-
conn The HttpConn connection object to define.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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. Set to NULL to use the current connection's client domain. Some browsers will accept cookies without the initial ".", but the spec: (RFC 2109) requires it. lifespan Duration for the cookie to persist in msec. Set to a negative number to delete a cookie. Set to zero for a "session" cookie that lives only for the user's session. isSecure Set to "true" if the cookie only applies for SSL based connections.
- API Stability:
- Stable.
- See Also:
- Esp
Set this authenticated session as the current session.
- Description:
- Set esp.login.single to true to enable current session tracking.
- Returns:
- True if the.
- API Stability:
- Evolving.
- See Also:
- Esp
Set a feedback message.
- Description:
- Feedback messages are a convenient way to aggregate messages state information in the response. Feedback messages are removed at the completion of the request.
- Parameters:
-
conn Http connection object. type type of feedback message. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical". fmt Printf style formatted string to use as the message.
- API Stability:
- Stable.
- See Also:
- Esp
Send a feedback message.
- Parameters:
-
conn Http connection object. type type of feedback message. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical". fmt Printf style formatted string to use as the message. args Varargs style list.
- API Stability:
- Internal.
- See Also:
- Esp
Set the current database grid.
- Returns:
- The grid instance. This permits chaining.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Define a notifier callback for this connection.
- Description:
- The notifier callback will be invoked for state changes and I/O events as requests are processed. The supported events are:
- HTTP_EVENT_STATE
The request is changing state. Valid states are: HTTP_STATE_BEGIN, HTTP_STATE_CONNECTED, HTTP_STATE_FIRST, HTTP_STATE_CONTENT, HTTP_STATE_READY, HTTP_STATE_RUNNING, HTTP_STATE_FINALIZED and HTTP_STATE_COMPLETE. A request will always visit all states and the notifier will be invoked for each and every state. This is true even if the request has no content, the HTTP_STATE_CONTENT will still be visited. - HTTP_EVENT_READABLE
There is data available to read - HTTP_EVENT_WRITABLE
The outgoing pipeline can absorb more data - HTTP_EVENT_ERROR
The request has encountered an error - HTTP_EVENT_DESTROY
The connection structure is about to be destoyed - HTTP_EVENT_OPEN
The application layer is now open - HTTP_EVENT_CLOSE
The application layer is now closed
- HTTP_EVENT_STATE
- Parameters:
-
conn HttpConn connection object created via httpCreateConn notifier Notifier function.
- API Stability:
- Stable.
- See Also:
- Esp
Set a request parameter value.
- Description:
- Set the value of a named request parameter to a string value. Parameters are defined via requeset POST data or request URI queries. This API permits these initial request parameters to be set or modified.
- Parameters:
-
conn HttpConn connection object. var Name of the request parameter to set. value Value to set.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
Show request details.
- Description:
- This e request details back to the client. This is useful as a debugging tool.
- Parameters:
-
conn HttpConn connection object.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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, "~/client/images/splash.png", 0);
espUri(conn, "${app}/client/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: '~/client/images/${theme}/background.jpg', theme: 'blue' }", 0);.
- API Stability:
- Evolving.
- See Also:
- Esp
Get the HTTP method.
- Description:
- This is a convenience API to return the Http method.
- Returns:
- The HttpConn.rx.method property.
- API Stability:
- Evolving.
- See Also:
- Esp
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:
- MakeUri("http://example.com/index.html", 0);
makeUri("/path/to/index.html", 0);
makeUri("../images/splash.png", 0);
makeUri("~/client/images/splash.png", 0);
makeUri("${app}/client/images/splash.png", 0);
makeUri("@controller/checkout", 0);
makeUri("@controller/")
makeUri("@init")
makeUri("@")
makeUri("{ action: '@post/create' }", 0);
makeUri("{ action: 'checkout' }", 0);
makeUri("{ action: 'logout', controller: 'admin' }", 0);
makeUri("{ action: 'admin/logout'", 0);
makeUri("{ product: 'candy', quantity: '10', template: '/cart/${product}/${quantity}' }", 0);
makeUri("{ route: '~/STAR/edit', action: 'checkout', id: '99' }", 0);
makeUri("{ template: '~/client/images/${theme}/background.jpg', theme: 'blue' }", 0);.
- API Stability:
- Evolving.
- See Also:
- Esp
Send a Edatabase grid as a JSON string.
- Description:
- The JSON string is rendered as part of an enclosing "{ data: JSON }" wrapper. This API is used to send database data to client user interfaces such as Angular or Aurelia clients.
- Parameters:
-
grid EDI grid.
- Returns:
- Number of bytes sent.
- API Stability:
- Evolving.
- See Also:
- Esp
Send a database record as a JSON string.
- Description:
- The JSON string is rendered as part of an enclosing "{ data: JSON }" wrapper. This API is used to send database data to client user interfaces such as Angular or Aurelia clients.
- Parameters:
-
rec EDI record.
- Returns:
- Number of bytes sent.
- API Stability:
- Evolving.
- See Also:
- Esp
Send a JSON response result.
- Description:
- This sends a JSON response including the request success status, feedback message and field errors. This API is used to send controller action responses to client user interfaces such as Angular or Aurelia clients. The field errors apply to the current EDI record. The format of the response is: "{ success: STATUS, feedback: {messages}, fieldErrors: {messages}}" wrapper. The feedback messages are created via the espSetFeedback API. Field errors are created by ESP validations.
- Parameters:
-
status Request success status. Note: this is not the HTTP response status code.
- API Stability:
- Evolving.
- See Also:
- Esp
EspRoute
EspRoute extended route configuration.
- See Also:
- Esp
- Fields:
-
MprHash * actions Table of actions. uint app Is an esp mvc application. cchar * appName App module name. uint combine Combine C source into a single file. cchar * combineScript Combine mode script filename. cchar * combineSheet Combine mode stylesheet filename. EspProc commonController Common code for all controllers. uint compile Enable recompiling the application or esp page. cchar * compileCmd Compile command template. uint compileMode Compile the application debug or release mode. cchar * configFile Path to config file. cchar * currentSession Current login session when enforcing a single login. Edi * edi Default database for this route. MprHash * env Environment variables for route. uint keep Keep intermediate source code after compiling. cchar * linkCmd Link command template. MprTime loaded When configuration was last loaded. HttpRoute * route Back link to route. cchar * searchPath Search path to use when locating compiler/linker. struct EspRoute * top Top-level route for this application. uint update Enable dynamically updating the application. MprHash * views Table of views. cchar * winsdk Windows SDK.
Add a route for the home page.
- Description:
- This will add a home page to route ESP applications. This will add the following route:
Name Method Pattern Target home GET,POST,PUT ^/$ index.esp
- Parameters:
-
route Parent route from which to inherit configuration.
- API Stability:
- Evolving.
- See Also:
- Esp
Add the specified pak to the pak.json packs list.
- Parameters:
-
route HttpRoute defining the ESP application. name Desired pak name. For example: "angular-mvc". version Pack version string.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Prototype.
- See Also:
- Esp
Add a route set.
- Description:
- This will add a set of routes. It will add a home route and optional routes depending on the route set.
Name Method Pattern Target home GET,POST,PUT ^/$ index.esp
- Parameters:
-
route Parent route from which to inherit configuration. set Route set to select. Use "angular-mvc", or "html-mvc".
- API Stability:
- Stable.
- See Also:
- Esp
Define an action for a URI pattern.
- Description:
- This creates a new route and binds the action function to a URI pattern.
- Parameters:
-
route Parent route object from which to inherit settings when creating the new route. pattern URI pattern to use to find the releavant route. actionProc EspProc callback procedure to invoke when the action is requested.
- API Stability:
- Stable.
- See Also:
- Esp
Convert an ESP web page into C code.
- Description:
- This parses an ESP web page into an equivalent C source view.
- Parameters:
-
route HttpRoute 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. Deprecated. state Reserved. Must set to NULL. err Output parameter to hold any relevant error message.
- Returns:
- Compiled script. Return NULL on errors.
- API Stability:
- Evolving.
- See Also:
- Esp
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.
- API Stability:
- Evolving.
- See Also:
- Esp
Compile an ESP page, controller or view.
- Description:
- This compiles ESP resources into loadable, cached modules.
- Parameters:
-
route HttpRoute object. dispatcher Optional dispatcher to use when waiting for the compilation command. 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. errMsg Reference to receive an error message if the routine fails.
- Returns:
- "True" if the compilation is successful. Errors are logged and sent back to the client if ShowErrors is true.
- API Stability:
- Evolving.
- See Also:
- Esp
Define an action.
- Description:
- Actions are C procedures that are invoked when specific URIs are routed to the controller/action pair.
- Parameters:
-
route HttpRoute 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.
- API Stability:
- Stable.
- See Also:
- Esp
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 HttpRoute object. baseProc Function to call just prior to invoking a controller action.
- API Stability:
- Stable.
- See Also:
- Esp
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.
- API Stability:
- Stable.
- See Also:
- Esp
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 (esp, mpr)
- 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:
-
route HttpRoute object. command Http connection object. source ESP web page source pathname. module Output module pathname.
- Returns:
- An expanded command line.
- API Stability:
- Evolving.
- See Also:
- Esp
Get a configuration value from the ESP pak.json.
- Parameters:
-
route HttpRoute defining the ESP application. key Configuration property path. May contain dots. defaultValue Default value to use if the configuration is not defined. May be null.
- Returns:
- The Configuration string value.
- API Stability:
- Stable.
- See Also:
- Esp
Test if the ESP application includes the specified pak.
- Description:
- This tests the dependencies property specified pak.
- Parameters:
-
route HttpRoute defining the ESP application. name Desired pak name. For example: "angular-mvc".
- Returns:
- True if the specified pak is supported.
- API Stability:
- Prototype.
- See Also:
- Esp
Initialize ESP.
- Description:
- This initializes a route for ESP. This may be called multiple times for different routes.
- Parameters:
-
route Parent route from which to inherit configuration. prefix Optional URI prefix for all application URIs. path Pathname to the esp.json file.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Prototype.
- See Also:
- Esp
Load the compiler rules from esp-compile.json.
- Parameters:
-
route HttpRoute object.
- API Stability:
- Prototype.
- See Also:
- Esp
Configure an ESP application.
- Description:
- Load the esp.json and pak.json configuration files.
- Parameters:
-
route Parent route from which to inherit configuration.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Prototype.
- See Also:
- Esp
Return the corresponding EspRoute for the given Route.
- Description:
- Returns the defined EspRoute for the given Route. Creates a new EspRoute if required.
- Parameters:
-
route Parent route from which to inherit configuration. create Set to true to create an EspRoute if a suitable one cannot be found.
- Returns:
- The EspRoute object.
- API Stability:
- Prototype.
- Parameters:
-
route
- See Also:
- Esp
Save the in-memory ESP pak.json configuration to the default location for the ESP application defined by the specified route.
- Parameters:
-
route HttpRoute defining the ESP application.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Evolving.
- See Also:
- Esp
Set a configuration value to the ESP pak.json.
- Description:
- This updates the in-memory copy of the pak.json only.
- Parameters:
-
route HttpRoute defining the ESP application. key Configuration property path. May contain dots. value Value to set the property to.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Evolving.
- See Also:
- Esp
Test if a configuration property from the ESP pak.json has a desired value.
- Parameters:
-
route HttpRoute defining the ESP application. key Configuration property path. May contain dots. desired Desired value to compare with.
- Returns:
- True if the configuration property has the desired value.
- API Stability:
- Evolving.
- See Also:
- Esp
Functions
Create an EspRoute object.
- Parameters:
-
route HttpRoute to associate with.
- Returns:
- EspRoute object.
Send mail using sendmail.
- Parameters:
-
conn HttpConn connection object. to Message recipient. from Message sender. subject Message subject. date Message creation date. Set to null to use the current date/time. mime Message mime type. Set to null for text/plain. message Message body. files MprList of files to send with the message.
- Returns:
- Zero if the email is successfully sent.
- API Stability:
- Evolving.
Add HTLM internal options to the Esp.options hash.
Initialize the ESP configuration file parser.
ESP initialization entry point.
- Parameters:
-
module Module object if loaded as an MPR module.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Evolving.
Render feedback messages.
- Description:
- Feedback messages for one-time messages that are sent to the client. For HTML clients, feedback messages use the session state store and persist for only one request. For smart/thick clients, feedback messages are sent as JSON responses via the espSendFeedback API. See espSetFeedback for how to define feedback messages.
- Parameters:
-
conn Http connection object. types Types of feedback message to retrieve. Set to "*" to retrieve all types of feedback. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".
- Returns:
- Number of bytes written.
- API Stability:
- Deprecated.
Set a private data reference for the current request.
- Parameters:
-
conn HttpConn object. data Data object to associate with the current request. This must be a managed reference.
- Returns:
- Reference to private data.
- API Stability:
- Prototype.
Initialize a static library ESP module.
- Description:
- This invokes the ESP initializers for the required pre-compiled ESP shared library.
- Parameters:
-
entry ESP initialization function. appName Name of the ESP application. routeName Name of the route in the appweb.conf file for this ESP application or page.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Evolving.
Typedefs
Procedure callback.
- API Stability:
- Stable.
ESP Action.
- Description:
- Actions are run after a request URI is routed to a controller.
- API Stability:
- Stable.
- See Also:
- Esp
View procedure callback.
- Parameters:
-
conn Http connection object.
- API Stability:
- Stable.
- See Also:
- Esp
Entry point for a loadable ESP module.
- Parameters:
-
route HttpRoute object. module Mpr module object.
- Returns:
- Zero if successful, otherwise a negative MPR error code.
- API Stability:
- Stable.
- See Also:
- Esp
Top level ESP structure.
- Fields:
-
int compileMode Force a debug compile. MprHash * databases Cloned databases. MprEvent * databasesTimer Database prune timer. EdiService * ediService Database service. cchar * hostedDocuments Documents directory if hosted. MprHash * internalOptions Table of internal HTML control options. int inUse Active ESP request counter. MprThreadLocal * local Thread local data. MprMutex * mutex Multithread lock. int reloading Reloading ESP and modules. MprHash * vstudioEnv Visual Studio environment.