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.
voidaddHeader(cchar *key, cchar *fmt, ...)
 Add a header to the transmission using a format string.
voidaddParam(cchar *name, cchar *value)
 Add a request parameter value if not already defined.
boolcanUser(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.
boolcreateRecFromParams(cchar *table)
 Create a record from the request parameters.
cchar*createSession()
 Create a session state object.
voiddestroySession()
 Destroy a session state object.
voiddontAutoFinalize()
 Don't auto-finalize this request.
voidespAddHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
 Add a header to the transmission using a format string.
voidespAddHeaderString(HttpConn *conn, cchar *key, cchar *value)
 Add a header to the transmission.
voidespAddHomeRoute(HttpRoute *route)
 Add a route for the home page.
voidespAddPak(HttpRoute *route, cchar *name, cchar *version)
 Add the specified pak to the package.json packs list.
voidespAddParam(HttpConn *conn, cchar *var, cchar *value)
 Add a request parameter value if it is not already defined.
voidespAddRouteSet(HttpRoute *route, cchar *set)
 Add a route set.
voidespAppendHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
 Append a transmission header.
voidespAppendHeaderString(HttpConn *conn, cchar *key, cchar *value)
 Append a transmission header string.
voidespAutoFinalize(HttpConn *conn)
 Auto-finalize transmission of the http request.
intespBindProc(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.
intespCache(HttpRoute *route, cchar *uri, int lifesecs, int flags)
 Add caching for response content.
voidespClearCurrentSession(HttpConn *conn)
 Clear the current authenticated session.
boolespCompile(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.
voidespDefineAction(HttpRoute *route, cchar *targetKey, void *actionProc)
 Define an action.
voidespDefineBase(HttpRoute *route, EspProc baseProc)
 Define a base function to invoke for all controller actions.
voidespDefineView(HttpRoute *route, cchar *path, void *viewProc)
 Define a view.
voidespDestroySession(HttpConn *conn)
 Destroy a session state object.
intespEmail(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.
voidespFinalize(HttpConn *conn)
 Indicate the request is finalized.
voidespFlush(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 package.json.
HttpConn*espGetConn()
 Get the current request connection.
MprOffespGetContentLength(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.
intespGetIntParam(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.
intespGetStatus(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.
boolespHasGrid(HttpConn *conn)
 Test if a current grid has been defined.
boolespHasPak(HttpRoute *route, cchar *name)
 Test if the ESP application includes the specified pak.
boolespHasRec(HttpConn *conn)
 Test if a current record has been defined and save to the database.
intespInit(HttpRoute *route, cchar *prefix, cchar *path)
 Initialize ESP.
voidespInitHtmlOptions(Esp *esp)
 Add HTLM internal options to the Esp.options hash.
intespInitParser()
 Initialize the ESP configuration file parser.
boolespIsCurrentSession(HttpConn *conn)
 Test if the connection is being made on behalf of the current, single authenticated user.
boolespIsEof(HttpConn *conn)
 Test if the receive input stream is at end-of-file.
boolespIsFinalized(HttpConn *conn)
 Test if the request has been finalized.
boolespIsSecure(HttpConn *conn)
 Test if the connection is using SSL and is secure.
intespLoadCompilerRules(HttpRoute *route)
 Load the compiler rules from esp-compile.json.
intespLoadConfig(HttpRoute *route)
 Configure an ESP application.
boolespMatchParam(HttpConn *conn, cchar *var, cchar *value)
 Match a request parameter with an expected value.
intespOpen(MprModule *module)
 ESP initialization entry point.
EdiGrid*espReadTable(HttpConn *conn, cchar *tableName)
 Read a table from the current database.
ssizeespReceive(HttpConn *conn, char *buf, ssize size)
 Read receive body content.
voidespRedirect(HttpConn *conn, int status, cchar *target)
 Redirect the client.
voidespRedirectBack(HttpConn *conn)
 Redirect the client back to the referrer.
voidespRemoveCookie(HttpConn *conn, cchar *name)
 Remove a cookie.
intespRemoveHeader(HttpConn *conn, cchar *key)
 Remove a header from the transmission.
voidespRemoveSessionVar(HttpConn *conn, cchar *name)
 Remove a session state variable.
ssizeespRender(HttpConn *conn, cchar *fmt, ...)
 Render a formatted string.
ssizeespRenderBlock(HttpConn *conn, cchar *buf, ssize size)
 Render a block of data to the client.
ssizeespRenderCached(HttpConn *conn)
 Render cached content.
ssizeespRenderConfig(HttpConn *conn)
 Render the client configuration string in JSON.
voidespRenderDocument(HttpConn *conn, cchar *path)
 Render an ESP document.
ssizeespRenderError(HttpConn *conn, int status, cchar *fmt, ...)
 Render an error message back to the client and finalize the request.
ssizeespRenderFeedback(HttpConn *conn, cchar *types)
 Render feedback messages.
ssizeespRenderFile(HttpConn *conn, cchar *path)
 Render the contents of a file back to the client.
ssizeespRenderSafe(HttpConn *conn, cchar *fmt, ...)
 Render a formatted string after HTML escaping.
ssizeespRenderSafeString(HttpConn *conn, cchar *s)
 Render a safe string of data to the client.
ssizeespRenderString(HttpConn *conn, cchar *s)
 Render a string of data to the client.
ssizeespRenderVar(HttpConn *conn, cchar *name)
 Render the value of a request variable to the client.
boolespRenderView(HttpConn *conn, cchar *view, int flags)
 Render an ESP view page to the client.
EspRoute*espRoute(HttpRoute *route)
 Return the corresponding EspRoute for the given Route.
intespSaveConfig(HttpRoute *route)
 Save the in-memory ESP package.json configuration to the default location for the ESP application defined by the specified route.
ssizeespSendGrid(HttpConn *conn, EdiGrid *grid, int flags)
 Send a database grid as a JSON string.
ssizeespSendRec(HttpConn *conn, EdiRec *rec, int flags)
 Send a database record as a JSON string.
ssizeespSendResult(HttpConn *conn, bool success)
 Send a JSON response result.
boolespSetAutoFinalizing(HttpConn *conn, bool on)
 Enable auto-finalizing for this request.
intespSetConfig(HttpRoute *route, cchar *key, cchar *value)
 Set a configuration value to the ESP package.json.
voidespSetConn(HttpConn *conn)
 Set the current request connection.
voidespSetContentLength(HttpConn *conn, MprOff length)
 Define a content length header in the transmission.
voidespSetContentType(HttpConn *conn, cchar *mimeType)
 Set the transmission (response) content mime type.
voidespSetCookie(HttpConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, bool isSecure)
 Set a cookie in the transmission.
voidespSetCurrentSession(HttpConn *conn)
 Set this authenticated session as the current session.
voidespSetData(HttpConn *conn, void *data)
 Set a private data reference for the current request.
voidespSetFeedback(HttpConn *conn, cchar *type, cchar *fmt, ...)
 Set a feedback message.
voidespSetFeedbackv(HttpConn *conn, cchar *type, cchar *fmt, va_list args)
 Send a feedback message.
EdiGrid*espSetGrid(HttpConn *conn, EdiGrid *grid)
 Set the current database grid.
voidespSetHeader(HttpConn *conn, cchar *key, cchar *fmt, ...)
 Set a transmission header.
voidespSetHeaderString(HttpConn *conn, cchar *key, cchar *value)
 Set a simple key/value transmission header.
voidespSetIntParam(HttpConn *conn, cchar *var, int value)
 Set an integer request parameter value.
voidespSetNotifier(HttpConn *conn, HttpNotifier notifier)
 Define a notifier callback for this connection.
voidespSetParam(HttpConn *conn, cchar *var, cchar *value)
 Set a request parameter value.
EdiRec*espSetRec(HttpConn *conn, EdiRec *rec)
 Set the current database record.
voidespSetStatus(HttpConn *conn, int status)
 Set a Http response status.
voidespShowRequest(HttpConn *conn)
 Show request details.
intespStaticInitialize(EspModuleEntry entry, cchar *appName, cchar *routeName)
 Initialize a static library ESP module.
boolespTestConfig(HttpRoute *route, cchar *key, cchar *desired)
 Test if a configuration property from the ESP package.json has a desired value.
voidespUpdateCache(HttpConn *conn, cchar *uri, cchar *data, int lifesecs)
 Update the cached content for a request.
boolespUpdateRec(HttpConn *conn, EdiRec *rec)
 Write a record to the database.
cchar*espUri(HttpConn *conn, cchar *target)
 Create a URI.
boolfeedback(cchar *type, cchar *fmt, ...)
 Set a feedback message.
voidfinalize()
 Finalize the response.
voidflush()
 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 package.json configuration.
HttpConn*getConn()
 Get the connection object.
MprOffgetContentLength()
 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.
boolhasGrid()
 Test if a current grid has been defined.
boolhasRec()
 Test if a current record has been defined and save to the database.
voidinput(cchar *field, cchar *options)
 Render an input field as part of a form.
voidinputSecurityToken()
 Render an input field with a hidden XSRF security token.
boolisEof()
 Test if the receive input stream is at end-of-file.
boolisFinalized()
 Test if a http request is finalized.
boolisSecure()
 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.
boolmodeIs(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.
ssizereceive(char *buf, ssize size)
 Read receive body content.
voidredirect(cchar *target)
 Redirect the client.
voidredirectBack()
 Redirect the client back to the referrer.
voidremoveCookie(cchar *name)
 Remove a cookie.
boolremoveRec(cchar *tableName, cchar *key)
 Remove a record from a database table.
voidremoveSessionVar(cchar *name)
 Remove a session state variable.
ssizerender(cchar *fmt, ...)
 Render a formatted string.
ssizerenderCached()
 Render cached content.
ssizerenderConfig()
 Render the package.json.
voidrenderError(int status, cchar *fmt, ...)
 Render an error message back to the client and finalize the request.
voidrenderFeedback(cchar *types)
 Render feedback messages.
ssizerenderFile(cchar *path)
 Render a file back to the client.
ssizerenderSafe(cchar *fmt, ...)
 Render a formatted string after HTML escaping.
ssizerenderString(cchar *s)
 Render a string of data to the client.
ssizerenderVar(cchar *name)
 Render the value of a request variable to the client.
voidrenderView(cchar *view)
 Render an ESP page to the client.
intrunCmd(cchar *command, char *input, char **output, char **error, MprTicks timeout, int flags)
 Run a command.
voidscripts(cchar *patterns)
 Render scripts.
voidsecurityToken()
 Add the security token to the response.
ssizesendGrid(EdiGrid *grid)
 Send a Edatabase grid as a JSON string.
ssizesendRec(EdiRec *rec)
 Send a database record as a JSON string.
voidsendResult(bool status)
 Send a JSON response result.
cchar*session(cchar *name)
 Get a session state variable.
voidsetConn(HttpConn *conn)
 Set the current request connection.
voidsetContentType(cchar *mimeType)
 Set the transmission (response) content mime type.
voidsetCookie(cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, bool isSecure)
 Define a cookie header to send with the response.
voidsetData(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.
voidsetHeader(cchar *key, cchar *fmt, ...)
 Set a transmission header.
voidsetIntParam(cchar *name, int value)
 Set an integer request parameter value.
voidsetNotifier(HttpNotifier notifier)
 Set a notifier callback for the connection.
voidsetParam(cchar *name, cchar *value)
 Set a request parameter value.
EdiRec*setRec(EdiRec *rec)
 Set the current database record.
voidsetSessionVar(cchar *name, cchar *value)
 Set a session state variable.
voidsetStatus(int status)
 Set a Http response status.
voidsetTimeout(void *proc, MprTicks timeout, void *data)
 Create a timeout event.
voidshowRequest()
 Show request details.
voidstylesheets(cchar *patterns)
 Render stylesheets.
voidupdateCache(cchar *uri, cchar *data, int lifesecs)
 Update the cached content for a request.
boolupdateField(cchar *tableName, cchar *key, cchar *fieldName, cchar *value)
 Write a value to a database table field.
boolupdateFields(cchar *tableName, MprJson *data)
 Write field values to a database row.
boolupdateRec(EdiRec *rec)
 Write a record to the database.
boolupdateRecFromParams(cchar *table)
 Update a record from the request parameters.
cchar*uri(cchar *target, ...)
 Create a URI link.

Typedefs

EspTop level ESP structure.
EspActionESP Action.
EspModuleEntryEntry point for a loadable ESP module.
EspProcProcedure callback.
EspViewProcView procedure callback.

Defines

#defineESP_COMPILE_JSON   "esp-compile.json"
 Compile rules filename.
#defineESP_COMPILE_OPTIMIZED   1
 Override to compile in release mode.
#defineESP_COMPILE_SYMBOLS   0
 Override to compile in debug mode.
#defineESP_LIFESPAN   (3600 * TPS)
 Default generated content cache lifespan.
#defineESP_LISTEN   "4000"
 Default listening endpoint for the esp program.
#defineESP_TOK_INCR   1024
 Growth increment for ESP tokens.
#defineESP_UNLOAD_TIMEOUT   (10)
 Very short timeout for reloading.
#defineME_ESP_EMAIL_TIMEOUT   (60 * 1000)
 Timeout for sending email.
#defineME_ESP_RELOAD_TIMEOUT   (5 * 1000)
 Timeout for reloading esp modules.

EspAbbrev

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:
cchar * absuri (cchar *target, ...)

Create an absolute URI with a scheme and host.

Parameters:
targetThe 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:
void addHeader (cchar *key, cchar *fmt, ...)

Add a header to the transmission using a format string.

Description:
Add a header if it does not already exist.
Parameters:
keyHttp response header key.
fmtPrintf 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:
void addParam (cchar *name, cchar *value)

Add a request parameter value if not already defined.

Parameters:
nameName of the request parameter to set.
valueValue to set.
API Stability:
Evolving.
See Also:
bool canUser (cchar *abilities, bool warn)

Test if a user has the required abilities.

Parameters:
abilitiesComma separated list of abilities to test for. If null, then use the required abilities defined for the current request route.
warnIf true, warn the user via sendResult
Returns:
True if the user has all the required abilities.
API Stability:
Prototype.
See Also:
EdiRec * createRec (cchar *tableName, MprJson *data)

Create a record and initialize field values.

Description:
This will call ediCreateRec to create a record based on the given table's schema. It will then call ediSetFields to update the record with the given data. The record is remembered for this request as the "current" record and can be retrieved via: getRec()
Parameters:
tableNameDatabase table name.
dataJson object with field values.
Returns:
EdRec instance.
API Stability:
Evolving.
See Also:
bool createRecFromParams (cchar *table)

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:
tableDatabase table to update.
Returns:
True if the update is successful.
API Stability:
Prototype.
See Also:
cchar * createSession ()

Create a session state object.

Description:
The session state object can be used to share state between requests. If a session has not already been created, this call will create a new session. It will create a response cookie containing a session ID that will be sent to the client with the response. Note: Objects are stored in the session state using JSON serialization.
Returns:
Session ID string.
API Stability:
Evolving.
See Also:
void destroySession ()

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:
void dontAutoFinalize ()

Don't auto-finalize this request.

API Stability:
Evolving.
See Also:
bool feedback (cchar *type, cchar *fmt, ...)

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:
typetype 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".
fmtPrintf 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:
void finalize ()

Finalize the response.

Description:
Signals the end of any and all response data and flushes any buffered write data to the client. If the request has already been finalized, this call has no additional effect. This routine calls espFinalize
API Stability:
Evolving.
See Also:
void flush ()

Flush transmit data.

Description:
This writes any buffered data.
API Stability:
Evolving.
See Also:
HttpAuth * getAuth ()

Get the auth object for the current route.

API Stability:
Prototype.
See Also:
MprList * getColumns (EdiRec *rec)

Get a list of column names.

Parameters:
recDatabase 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:
cchar * getConfig (cchar *field)

Get a field from the application package.json configuration.

Parameters:
fieldProperty field name in package.json. May contain dots.
Returns:
The field value. Returns "" if the field is not found.
API Stability:
Deprecated.
See Also:
HttpConn * getConn ()

Get the connection object.

Description:
Before a view or controller is run, the current connection object for the request is saved in thread local data. Most EspAbbrev APIs take an HttpConn object as an argument.
Returns:
HttpConn connection instance object.
API Stability:
Evolving.
See Also:
MprOff getContentLength ()

Get the receive body content length.

Description:
Get the length of the receive body content (if any). This is used in servers to get the length of posted data and in clients to get the response body length.
Returns:
A count of the response content data in bytes.
API Stability:
Evolving.
See Also:
cchar * getContentType ()

Get the receive body content type.

Description:
Get the content mime type of the receive body content (if any).
Returns:
Mime type of any receive content. Set to NULL if not posted data.
API Stability:
Evolving.
See Also:
cchar * getCookies ()

Get the request cookies.

Description:
Get the cookies defined in the current request.
Returns:
Return a string containing the cookies sent in the Http header of the last request.
API Stability:
Evolving.
See Also:
void * getData ()

Get the private data reference for the current request set via setData

Returns:
Reference to private data.
API Stability:
Prototype.
See Also:
Edi * getDatabase ()

Get the current database instance.

Description:
A route may have a default database configured via the EspDb Appweb.conf configuration directive. The database will be opened when the web server initializes and will be shared between all requests using the route.
Returns:
Edi EDI database handle.
API Stability:
Evolving.
See Also:
MprDispatcher * getDispatcher ()

Get the connection dispatcher object.

Returns:
MprDispatcher connection dispatcher instance object.
API Stability:
Evolving.
See Also:
cchar * getDocuments ()

Get the default document root directory for the request route.

Returns:
A directory path name.
API Stability:
Evolving.
See Also:
EspRoute * getEspRoute ()

Get the extended route EspRoute structure.

Returns:
EspRoute instance.
API Stability:
Evolving.
See Also:
cchar * getFeedback (cchar *type)

Get a feedback message defined via feedback

Parameters:
typetype 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:
cchar * getField (EdiRec *rec, cchar *field)

Get a field from the current database record.

Parameters:
recDatabase record.
fieldField name to return.
Returns:
String value for "field" in the current record.
API Stability:
Evolving.
See Also:
cchar * getFieldError (cchar *field)

Test if a field in the current record has input validation errors.

API Stability:
Prototype.
See Also:
EdiGrid * getGrid ()

Get the current database grid.

Description:
The current grid is defined via setGrid
Returns:
EdiGrid instance.
API Stability:
Evolving.
See Also:
cchar * getHeader (cchar *key)

Get an rx http header.

Description:
Get a http response header for a given header key.
Parameters:
keyName 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:
cchar * getPath ()

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:
cchar * getQuery ()

Get the HTTP URI query string.

Description:
This is a convenience API to return the query string for the current request.
Returns:
The espGetConn()->rx->parsedUri->query property.
API Stability:
Evolving.
See Also:
EdiRec * getRec ()

Get the current database record.

Returns:
EdiRec instance.
API Stability:
Evolving.
See Also:
cchar * getReferrer ()

Get the referring URI.

Description:
This returns the referring URI as described in the HTTP "referer" (yes the HTTP specification does spell it incorrectly) header. If this header is not defined, this routine will return the home URI as returned by uri("~").
Returns:
String URI back to the referring URI. If no referrer is defined, refers to the home URI.
API Stability:
Evolving.
See Also:
EspReq * getReq ()

Get the ESP request object.

Returns:
EspReq connection instance object.
API Stability:
Evolving.
See Also:
HttpRoute * getRoute ()

Get the HttpRoute object for the current route.

API Stability:
Evolving.
See Also:
cchar * getSecurityToken ()

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:
cchar * getSessionID ()

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:
cchar * getSessionVar (cchar *name)

Get a session state variable.

Description:
The session API is an alias for this routine.
Parameters:
nameVariable name to get.
Returns:
The session variable value. Returns NULL if not set.
API Stability:
Evolving.
See Also:
MprList * getUploads ()

Get the uploaded files.

Description:
Get the list of uploaded files.
Returns:
A list of HttpUploadFile objects.
API Stability:
Evolving.
See Also:
cchar * getUri ()

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:
bool hasGrid ()

Test if a current grid has been defined.

Returns:
"true" if a current grid has been defined.
API Stability:
Evolving.
See Also:
bool hasRec ()

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

Description:
This call returns "true" if a current record is defined and has been saved to the database with a valid "id" field.
Returns:
"true" if a current record with a valid "id" is defined.
API Stability:
Evolving.
See Also:
void input (cchar *field, cchar *options)

Render an input field as part of a form.

This is a smart input control that will call the appropriate input control based on the database record field data type. This control should not be used if using the esp-angular-mvc or other similar client-side Javascript framework
Parameters:
fieldName 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.
optionsThese 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:
void inputSecurityToken ()

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:
bool isEof ()

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:
bool isFinalized ()

Test if a http request is finalized.

Description:
This tests if espFinalize or httpFinalize has been called for a request.
Returns:
"true" if the request has been finalized.
API Stability:
Evolving.
See Also:
bool isSecure ()

Test if the connection is using SSL and is secure.

Returns:
"true" if the connection is using SSL.
API Stability:
Evolving.
See Also:
MprHash * makeHash (cchar *fmt, ...)

Make a hash table container of property values.

Description:
This routine formats the given arguments, parses the result as a JSON string and returns an equivalent hash of property values. The result after formatting should be of the form: hash("{ key: 'value', key2: 'value', key3: 'value' }");.
Parameters:
fmtPrintf style format string.
...arguments.
Returns:
MprHash instance.
API Stability:
Evolving.
See Also:
MprJson * makeJson (cchar *fmt, ...)

Make a JSON object container of property values.

Description:
This routine formats the given arguments, parses the result into a JSON object.
Parameters:
fmtPrintf style format string.
...arguments.
Returns:
MprJson instance.
API Stability:
Evolving.
See Also:
EdiRec * makeRec (cchar *content)

Make a record.

Description:
This call makes a free-standing data record based on the JSON format content string. The record is not saved to the database.
Parameters:
contentJSON 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:
cchar * md5 (cchar *str)

Get an MD5 checksum.

Parameters:
strString to hash.
Returns:
An allocated MD5 checksum string.
API Stability:
Prototype.
See Also:
bool modeIs (cchar *check)

Test the the application mode.

Description:
This is typically set to "debug" or "release". The mode is defined by the "mode" property in the package.json.
Parameters:
checkMode to compare with the current application mode.
Returns:
True if the current app mode matches the check mode.
API Stability:
Prototype.
See Also:
cchar * nonce ()

Generate a onetime random string.

Returns:
An MD5 encoded random string.
API Stability:
Prototype.
See Also:
cchar * param (cchar *name)

Get a request parameter.

Description:
Get the value of a named request parameter. Form variables are defined via www-urlencoded query or post data contained in the request. This routine calls espGetParam
Parameters:
nameName 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:
MprJson * params ()

Get the request parameter hash table.

Description:
This call gets the params hash table for the current request. Route tokens, request query data, and www-url encoded form data are all entered into the params table after decoding. Use mprLookupKey to retrieve data from the table. This routine calls espGetParams
Returns:
MprJson instance containing the request parameters.
API Stability:
Evolving.
See Also:
EdiRec * readRec (cchar *tableName, cchar *key)

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:
tableNameDatabase table name.
keyKey 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:
EdiRec * readRecByKey (cchar *tableName, cchar *key)

Read a record identified by key value.

Description:
Read a record from the given table as identified by the key value. The record is remembered for this request as the "current" record and can be retrieved via: getRec()
Parameters:
tableNameDatabase table name.
keyKey value of the record to read.
Returns:
Record instance of EdiRec.
API Stability:
Evolving.
See Also:
EdiRec * readRecWhere (cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read one record.

Description:
This runs a simple query on the database and selects the first matching record. The query selects a row that has a "field" that matches the given "value". The record is remembered for this request as the "current" record and can be retrieved via: getRec()
Parameters:
tableNameDatabase table name.
fieldNameDatabase field name to evaluate.
operationComparison operation. Set to "==", "!=", "<", ">", "<=" or ">=".
valueData value to compare with the field values.
Returns:
First matching record. Returns NULL if no matching records.
API Stability:
Evolving.
See Also:
EdiGrid * readTable (cchar *tableName)

Read all the records in table from the database.

Description:
This reads a table and returns a grid containing the table data. The grid of records is remembered for this request as the "current" grid and can be retrieved via: getGrid()
Parameters:
tableNameDatabase table name.
Returns:
A grid containing all table rows. Returns NULL if the table cannot be found.
API Stability:
Evolving.
See Also:
EdiGrid * readWhere (cchar *tableName, cchar *fieldName, cchar *operation, cchar *value)

Read matching records.

Description:
This runs a simple query on the database and returns matching records in a grid. The query selects all rows that have a "field" that matches the given "value". The grid of records is remembered for this request as the "current" grid and can be retrieved via: getGrid()
Parameters:
tableNameDatabase table name.
fieldNameDatabase field name to evaluate.
operationComparison operation. Set to "==", "!=", "<", ">", "<=" or ">=".
valueData 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:
ssize receive (char *buf, ssize size)

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:
bufBuffer to accept content data.
sizeSize of the buffer.
Returns:
A count of bytes read into the buffer.
API Stability:
Evolving.
See Also:
void redirect (cchar *target)

Redirect the client.

Description:
Redirect the client to a new uri. This will redirect with an HTTP 302 status. If a different HTTP status code is required, use espRedirect
Parameters:
targetNew target uri for the client.
API Stability:
Evolving.
See Also:
void redirectBack ()

Redirect the client back to the referrer.

Description:
Redirect the client to the referring URI.
API Stability:
Evolving.
See Also:
void removeCookie (cchar *name)

Remove a cookie.

Parameters:
nameCookie name.
API Stability:
Evolving.
See Also:
bool removeRec (cchar *tableName, cchar *key)

Remove a record from a database table.

Description:
Remove the record identified by the key value from the given table. 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:
tableNameDatabase table name.
keyKey value of the record to remove.
Returns:
Record instance of EdiRec.
API Stability:
Evolving.
See Also:
void removeSessionVar (cchar *name)

Remove a session state variable.

Parameters:
nameVariable name to set.
API Stability:
Prototype.
See Also:
ssize render (cchar *fmt, ...)

Render a formatted string.

Description:
Render a formatted string of data into packets to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
fmtPrintf style formatted string.
...Arguments for fmt.
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
ssize renderCached ()

Render cached content.

Description:
Render the saved, cached response from a prior request to this URI. This is useful if the caching mode has been set to "manual".
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
ssize renderConfig ()

Render the package.json.

Returns:
A count of the bytes actually written.
API Stability:
Prototype.
See Also:
void renderError (int status, cchar *fmt, ...)

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

The output is Html escaped for security
Parameters:
statusHttp status code.
fmtPrintf style message format.
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
void renderFeedback (cchar *types)

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:
typesTypes 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:
ssize renderFile (cchar *path)

Render a file back to the client.

Description:
Render a formatted string of data and then HTML escape. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
pathFilename of the file to send to the client.
...Arguments for fmt.
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
ssize renderSafe (cchar *fmt, ...)

Render a formatted string after HTML escaping.

Description:
Render a formatted string of data and then HTML escape. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
fmtPrintf style formatted string.
...Arguments for fmt.
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
ssize renderString (cchar *s)

Render a string of data to the client.

Description:
Render a string of data to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
sString containing the data to write.
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
ssize renderVar (cchar *name)

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:
nameForm variable name.
Returns:
A count of the bytes actually written.
API Stability:
Evolving.
See Also:
void renderView (cchar *view)

Render an ESP page to the client.

Parameters:
viewView name. The view name is interpreted relative to the matching route documents directory and may omit an ESP extension.
API Stability:
Evolving.
See Also:
int runCmd (cchar *command, char *input, char **output, char **error, MprTicks timeout, int flags)

Run a command.

Description:
Run a command and return output.
Parameters:
commandCommand line and arguments to run.
inputInput data to pass to the command. Set to null if not required.
outputPointer to accept command standard output response. Set to null if not required.
errorPointer to accept command standard error response. Set to null if not required.
flagsMprCmd flags. Use MPR_CMD_DETACH to run in the background.
timeoutTime in milliseconds to wait for the command to complete and exit.
API Stability:
Prototype.
See Also:
void scripts (cchar *patterns)

Render scripts.

Description:
This renders script elements for all matching filenames on the server.
Parameters:
patternsAn 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:
void securityToken ()

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:
cchar * session (cchar *name)

Get a session state variable.

Description:
This is a convenient alias for getSessionVar
Parameters:
nameVariable name to get.
Returns:
The session variable value. Returns NULL if not set.
API Stability:
Evolving.
See Also:
void setConn (HttpConn *conn)

Set the current request connection.

Parameters:
connThe HttpConn connection object to define.
API Stability:
Evolving.
See Also:
void setContentType (cchar *mimeType)

Set the transmission (response) content mime type.

Description:
Set the mime type Http header in the transmission.
Parameters:
mimeTypeMime type string.
API Stability:
Evolving.
See Also:
void setCookie (cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, bool isSecure)

Define a cookie header to send with the response.

The Path, Domain, and Expires properties can be set to null for default values
Parameters:
nameCookie name.
valueCookie value.
pathUri path to which the cookie applies.
domainString 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.
lifespanLifespan of the cookie in seconds.
isSecureBoolean Set to "true" if the cookie only applies for SSL based connections.
API Stability:
Evolving.
See Also:
void setData (void *data)

Set a private data reference for the current request.

Returns:
Reference to private data.
API Stability:
Prototype.
See Also:
EdiRec * setField (EdiRec *rec, cchar *fieldName, cchar *value)

Update a record field without writing to the database.

Description:
This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use updateRec
Parameters:
recRecord to update.
fieldNameRecord field name to update.
valueValue to update.
Returns:
The record instance if successful, otherwise NULL.
API Stability:
Evolving.
See Also:
EdiRec * setFields (EdiRec *rec, MprJson *data)

Update record fields without writing to the database.

Description:
This routine updates the record object with the given values. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request params or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: updateFields(rec, hash("{ name: '%s', address: '%s' }", name, address)) The record will not be written to the database. To write to the database, use ediUpdateRec
Parameters:
recRecord to update.
dataJson object of field data.
Returns:
The record instance if successful, otherwise NULL.
API Stability:
Evolving.
See Also:
EdiGrid * setGrid (EdiGrid *grid)

Set the current database grid.

Returns:
The grid instance. This permits chaining.
API Stability:
Evolving.
See Also:
void setHeader (cchar *key, cchar *fmt, ...)

Set a transmission header.

Description:
Set a Http header to send with the request. If the header already exists, its value is overwritten.
Parameters:
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
API Stability:
Evolving.
See Also:
void setIntParam (cchar *name, int value)

Set an integer request parameter value.

Description:
Set the value of a named request parameter to an integer value. Form variables are defined via www-urlencoded query or post data contained in the request.
Parameters:
nameName of the request parameter to set.
valueInteger value to set.
API Stability:
Evolving.
See Also:
void setNotifier (HttpNotifier notifier)

Set a notifier callback for the connection.

This wraps httpSetConnNotifier and calls espSetConn before invoking the notifier for connection events
Parameters:
notifierCallback function.
API Stability:
Evolving.
See Also:
void setParam (cchar *name, cchar *value)

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:
nameName of the request parameter to set.
valueValue to set.
API Stability:
Evolving.
See Also:
EdiRec * setRec (EdiRec *rec)

Set the current database record.

Description:
The current record is used to supply data to various abbreviated controls, such as: text(), input(), checkbox and dropdown().
Returns:
The grid instance. This permits chaining.
API Stability:
Evolving.
See Also:
void setSessionVar (cchar *name, cchar *value)

Set a session state variable.

Parameters:
nameVariable name to set.
valueValue to set.
API Stability:
Evolving.
See Also:
void setStatus (int status)

Set a Http response status.

Description:
Set the Http response status for the request. This defaults to 200 (OK).
Parameters:
statusHttp status code.
API Stability:
Evolving.
See Also:
void setTimeout (void *proc, MprTicks timeout, void *data)

Create a timeout event.

Description:
Invoke the given procedure after the timeout.
Parameters:
procFunction to invoke.
timeoutTime in milliseconds to elapse before invoking the timeout.
dataArgument to pass to proc.
API Stability:
Evolving.
See Also:
void showRequest ()

Show request details.

Description:
This echoes request details back to the client. This is useful as a debugging tool.
API Stability:
Evolving.
See Also:
void stylesheets (cchar *patterns)

Render stylesheets.

Description:
This renders stylesheet elements for all matching filenames on the server.
Parameters:
patternsAn 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:
void updateCache (cchar *uri, cchar *data, int lifesecs)

Update the cached content for a request.

Description:
Save the given content for future requests. This is useful if the caching mode has been set to "manual".
Parameters:
uriRequest URI to cache for.
dataData to cache.
lifesecsTime in seconds to cache the data.
API Stability:
Evolving.
See Also:
bool updateField (cchar *tableName, cchar *key, cchar *fieldName, cchar *value)

Write a value to a database table field.

Description:
Update the value of a table field in the selected table row. Note: validations are not run.
Parameters:
tableNameDatabase table name.
keyKey value for the table row to update.
fieldNameColumn name to update.
valueValue to write to the database field.
Returns:
"true" if the field can be successfully written.
API Stability:
Evolving.
See Also:
bool updateFields (cchar *tableName, MprJson *data)

Write field values to a database row.

Description:
This routine updates the current record with the given data and then saves the record to the database. The "data' argument supplies a hash of fieldNames and values. The data hash may come from the request params or it can be manually created via ediMakeHash to convert a JSON string into an options hash. For example: ediWriteFields(rec, params()); The record runs field validations before saving to the database.
Parameters:
tableNameDatabase table name.
dataJson 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:
bool updateRec (EdiRec *rec)

Write a record to the database.

Description:
The record will be saved to the database after running any field validations. If any field validations fail to pass, the record will not be written and error details can be retrieved via ediGetRecErrors. If the record is a new record and the "id" column is EDI_AUTO_INC, then the "id" will be assigned prior to saving the record. 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:
recRecord to write to the database.
Returns:
"true" if the record can be successfully written.
API Stability:
Evolving.
See Also:
bool updateRecFromParams (cchar *table)

Update a record from the request parameters.

Description:
The record identified by the params(id) is read and updated with the request parameters.
Parameters:
tableDatabase table to update.
Returns:
True if the update is successful.
API Stability:
Prototype.
See Also:
cchar * uri (cchar *target, ...)

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:
targetThe 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

EspParse

ESP page parser structure.

See Also:
Esp

EspReq

EspReq

ESP request structure.

API Stability:
Internal.
See Also:
Esp
Fields:
intautoFinalize 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.
intlastDomID Last generated DOM ID.
MprHash *lastFeedback Feedback messages from the last request.
HttpNotifiernotifier Connection Http state change notification callback.
HttpRoute *route Route reference.
intsessionProbed Already probed for session store.
void *staticData Custom data for request (unmanaged).
void espAddHeader (HttpConn *conn, cchar *key, cchar *fmt, ...)

Add a header to the transmission using a format string.

Description:
Add a header if it does not already exist.
Parameters:
connHttpConn connection object.
keyHttp response header key.
fmtPrintf 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
void espAddHeaderString (HttpConn *conn, cchar *key, cchar *value)

Add a header to the transmission.

Description:
Add a header if it does not already exist.
Parameters:
connHttpConn connection object.
keyHttp response header key.
valueValue 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
void espAddParam (HttpConn *conn, cchar *var, cchar *value)

Add a request parameter value if it is not already defined.

Parameters:
connHttpConn connection object.
varName of the request parameter to set.
valueValue to set.
API Stability:
Stable.
See Also:
Esp
void espAppendHeader (HttpConn *conn, cchar *key, cchar *fmt, ...)

Append a transmission header.

Description:
Set the header if it does not already exist. Append with a ", " separator if the header already exists.
Parameters:
connHttpConn connection object.
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
API Stability:
Stable.
See Also:
Esp
void espAppendHeaderString (HttpConn *conn, cchar *key, cchar *value)

Append a transmission header string.

Description:
Set the header if it does not already exist. Append with a ", " separator if the header already exists.
Parameters:
connHttpConn connection object.
keyHttp response header key.
valueValue to set for the header.
API Stability:
Stable.
See Also:
Esp
void espAutoFinalize (HttpConn *conn)

Auto-finalize transmission of the http request.

Description:
If auto-finalization is enabled via espSetAutoFinalizing, this call will finalize writing Http response data by writing the final chunk trailer if required. If using chunked transfers, a null chunk trailer is required to signify the end of write data. If the request is already finalized, this call does nothing.
Parameters:
connHttpConn connection object.
API Stability:
Stable.
See Also:
Esp
void espClearCurrentSession (HttpConn *conn)

Clear the current authenticated session.

API Stability:
Evolving.
See Also:
Esp
cchar * espCreateSession (HttpConn *conn)

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:
connHttpConn connection object.
Returns:
Session ID string.
API Stability:
Stable.
See Also:
Esp
void espDestroySession (HttpConn *conn)

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:
connHttpConn connection object.
API Stability:
Stable.
See Also:
Esp
void espFinalize (HttpConn *conn)

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:
connHttpConn connection object.
API Stability:
Stable.
See Also:
Esp
void espFlush (HttpConn *conn)

Flush transmit data.

Description:
This writes any buffered data.
Parameters:
connHttpConn connection object.
API Stability:
Stable.
See Also:
Esp
HttpAuth * espGetAuth ()

Get the current route HttpAuth object.

Returns:
The HttpAuth object.
API Stability:
Stable.
See Also:
Esp
HttpConn * espGetConn ()

Get the current request connection.

Returns:
The HttpConn connection object.
API Stability:
Stable.
See Also:
Esp
MprOff espGetContentLength (HttpConn *conn)

Get the receive body content length.

Description:
Get the length of the receive body content (if any). This is used in servers to get the length of posted data and, in clients, to get the response body length.
Parameters:
connHttpConn connection object.
Returns:
A count of the response content data in bytes.
API Stability:
Stable.
See Also:
Esp
cchar * espGetContentType (HttpConn *conn)

Get the receive body content type.

Description:
Get the content mime type of the receive body content (if any).
Parameters:
connHttpConn connection object.
Returns:
Mime type of any receive content. Set to NULL if not posted data.
API Stability:
Stable.
See Also:
Esp
cchar * espGetCookie (HttpConn *conn, cchar *name)

Get a request cookie.

Description:
Get the cookie for the given name.
Parameters:
connHttpConn connection object.
nameCookie name to retrieve.
Returns:
The cookie value Return null if the cookie is not defined.
API Stability:
Stable.
See Also:
Esp
cchar * espGetCookies (HttpConn *conn)

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:
connHttpConn connection object.
Returns:
Return a string containing the cookies sent in the Http header of the last request.
API Stability:
Stable.
See Also:
Esp
void * espGetData (HttpConn *conn)

Get the private data reference for the current request set via setData

Parameters:
connHttpConn object.
Returns:
Reference to private data.
API Stability:
Prototype.
See Also:
Esp
Edi * espGetDatabase (HttpConn *conn)

Get the current database instance.

Description:
A route may have a default database configured via the EspDb Appweb.conf configuration directive. The database will be opened when the web server initializes and will be shared between all requests using the route.
Returns:
Edi EDI database handle.
API Stability:
Stable.
See Also:
Esp
cchar * espGetDocuments (HttpConn *conn)

Get the default documents directory for the request route.

Parameters:
connHttpConn connection object.
Returns:
A directory path name.
API Stability:
Stable.
See Also:
Esp
EspRoute * espGetEspRoute (HttpConn *conn)

Get the current extended route information.

Returns:
EspRoute instance.
API Stability:
Evolving.
See Also:
Esp
cchar * espGetFeedback (HttpConn *conn, cchar *type)

Get a feedback message defined via feedback

Parameters:
connHttpConn object.
typetype 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
EdiGrid * espGetGrid (HttpConn *conn)

Get the current database grid.

Description:
The current grid is defined via setGrid
Returns:
EdiGrid instance.
API Stability:
Deprecated.
See Also:
Esp
cchar * espGetHeader (HttpConn *conn, cchar *key)

Get an rx http header.

Description:
Get a http response header for a given header key.
Parameters:
connHttpConn connection object.
keyName 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
MprHash * espGetHeaderHash (HttpConn *conn)

Get the hash table of rx Http headers.

Description:
Get the internal hash table of rx headers.
Parameters:
connHttpConn connection object.
Returns:
Hash table. See MprHash for how to access the hash table.
API Stability:
Stable.
See Also:
Esp
char * espGetHeaders (HttpConn *conn)

Get all the request http headers.

Description:
Get all the rx headers. The returned string formats all the headers in the form: key: value\nkey2: value2\n.
Parameters:
connHttpConn connection object.
Returns:
String containing all the headers. The caller must free this returned string.
API Stability:
Stable.
See Also:
Esp
int espGetIntParam (HttpConn *conn, cchar *var, int defaultValue)

Get a request pararmeter as an integer.

Description:
Get the value of a named request parameter as an integer. Form variables are defined via www-urlencoded query or post data contained in the request.
Parameters:
connHttpConn connection object.
varName of the request parameter to retrieve.
defaultValueDefault 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
cchar * espGetMethod (HttpConn *conn)

Get the HTTP method.

Description:
This is a convenience API to return the Http method.
Returns:
The HttpConn.rx.method property.
API Stability:
Stable.
See Also:
Esp
cchar * espGetParam (HttpConn *conn, cchar *var, cchar *defaultValue)

Get a request parameter.

Description:
Get the value of a named request parameter. Form variables are defined via www-urlencoded query or post data contained in the request.
Parameters:
connHttpConn connection object.
varName of the request parameter to retrieve.
defaultValueDefault 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
MprJson * espGetParams (HttpConn *conn)

Get the request parameter hash table.

Description:
This call gets the params hash table for the current request. Route tokens, request query data, and www-url encoded form data are all entered into the params table after decoding. Use mprLookupKey to retrieve data from the table.
Parameters:
connHttpConn connection object.
Returns:
MprJson instance containing the request parameters.
API Stability:
Stable.
See Also:
Esp
cchar * espGetPath (HttpConn *conn)

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
cchar * espGetQueryString (HttpConn *conn)

Get the request query string.

Description:
Get query string sent with the current request.
Parameters:
connHttpConn connection object.
Returns:
String containing the request query string. Caller should not free.
API Stability:
Stable.
See Also:
Esp
char * espGetReferrer (HttpConn *conn)

Get the referring URI.

Description:
This returns the referring URI as described in the HTTP "referer" (yes the HTTP specification does spell it incorrectly) header. If this header is not defined, this routine will return the home URI as returned by uri("~").
Parameters:
connHttpConn 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
HttpRoute * espGetRoute ()

Get the current route HttpRoute object.

Returns:
The HttpRoute object.
API Stability:
Stable.
See Also:
Esp
Edi * espGetRouteDatabase (HttpRoute *route)

Get the default database defined on a route.

Parameters:
routeHttpRoute object.
Returns:
Database instance object.
API Stability:
Stable.
See Also:
Esp
cchar * espGetRouteVar (HttpConn *conn, cchar *var)

Get a route variable.

Description:
Get the value of a request route variable.
Parameters:
connHttpConn connection object.
varName of the request parameter to retrieve.
Returns:
String containing the route variable value. Caller should not free.
API Stability:
Evolving.
See Also:
Esp
cchar * espGetSessionID (HttpConn *conn, int create)

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:
connHttpConn connection object.
createSet 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
int espGetStatus (HttpConn *conn)

Get the response status.

Parameters:
connHttpConn connection object.
Returns:
An integer Http response code. Typically 200 is success.
API Stability:
Stable.
See Also:
Esp
char * espGetStatusMessage (HttpConn *conn)

Get the Http response status message.

Description:
The HTTP status message is supplied on the first line of the HTTP response.
Parameters:
connHttpConn connection object.
Returns:
A Http status message.
API Stability:
Stable.
See Also:
Esp
MprList * espGetUploads (HttpConn *conn)

Get the uploaded files.

Description:
Get the list of uploaded files. This list entries are HttpUploadFile objects.
Parameters:
connHttpConn connection object.
Returns:
A list of HttpUploadFile objects.
API Stability:
Stable.
See Also:
Esp
cchar * espGetUri (HttpConn *conn)

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
bool espHasGrid (HttpConn *conn)

Test if a current grid has been defined.

Returns:
"True" if a current grid has been defined.
API Stability:
Deprecated.
See Also:
Esp
bool espHasRec (HttpConn *conn)

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

Description:
This call returns "true" if a current record is defined and has been saved to the database with a valid "id" field.
Returns:
"True" if a current record with a valid "id" is defined.
API Stability:
Deprecated.
See Also:
Esp
bool espIsCurrentSession (HttpConn *conn)

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
bool espIsEof (HttpConn *conn)

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

Parameters:
connHttpConn connection object.
Returns:
"True" if there is no more receive data to read.
API Stability:
Stable.
See Also:
Esp
bool espIsFinalized (HttpConn *conn)

Test if the request has been finalized.

Description:
This tests if espFinalize or httpFinalize has been called for a request.
Parameters:
connHttpConn connection object.
Returns:
"True" if the request has been finalized.
API Stability:
Stable.
See Also:
Esp
bool espIsSecure (HttpConn *conn)

Test if the connection is using SSL and is secure.

Parameters:
connHttpConn connection object.
Returns:
"True" if the connection is using SSL.
API Stability:
Stable.
See Also:
Esp
bool espMatchParam (HttpConn *conn, cchar *var, cchar *value)

Match a request parameter with an expected value.

Description:
Compare a request parameter and return "true" if it exists and its value matches.
Parameters:
connHttpConn connection object.
varName of the request parameter.
valueExpected value to match.
Returns:
"True" if the value matches.
API Stability:
Stable.
See Also:
Esp
EdiGrid * espReadTable (HttpConn *conn, cchar *tableName)

Read a table from the current database.

Parameters:
connHttpConn connection object.
tableNameDatabase table name.
Returns:
An EDI grid containing data for the table.
API Stability:
Evolving.
See Also:
Esp
ssize espReceive (HttpConn *conn, char *buf, ssize size)

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:
connHttpConn connection object.
bufBuffer to accept content data.
sizeSize of the buffer.
Returns:
A count of bytes read into the buffer.
API Stability:
Stable.
See Also:
Esp
void espRedirect (HttpConn *conn, int status, cchar *target)

Redirect the client.

Description:
Redirect the client to a new uri.
Parameters:
connHttpConn connection object.
statusHttp status code to send with the response.
targetNew target uri for the client.
API Stability:
Stable.
See Also:
Esp
void espRedirectBack (HttpConn *conn)

Redirect the client back to the referrer.

Description:
Redirect the client to the referring URI.
Parameters:
connHttpConn connection object.
API Stability:
Stable.
See Also:
Esp
void espRemoveCookie (HttpConn *conn, cchar *name)

Remove a cookie.

Parameters:
connHttpConn connection object.
nameCookie name.
API Stability:
Stable.
See Also:
Esp
int espRemoveHeader (HttpConn *conn, cchar *key)

Remove a header from the transmission.

Description:
Remove a header if present.
Parameters:
connHttpConn connection object.
keyHttp response header key.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
Esp
void espRemoveSessionVar (HttpConn *conn, cchar *name)

Remove a session state variable.

Parameters:
connHttpConn connection object.
nameVariable name to set.
API Stability:
Stable.
See Also:
Esp
ssize espRender (HttpConn *conn, cchar *fmt, ...)

Render a formatted string.

Description:
Render a formatted string of data into packets to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
connHttpConn connection object.
fmtPrintf style formatted string.
...Arguments for fmt.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderBlock (HttpConn *conn, cchar *buf, ssize size)

Render a block of data to the client.

Description:
Render a block of data to the client. Data packets will be created as required to store the write data.
Parameters:
connHttpConn connection object.
bufBuffer containing the write data.
sizeSize of the data in buf.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderCached (HttpConn *conn)

Render cached content.

Description:
Render the saved, cached response from a prior request to this URI. This is useful if the caching mode has been set to "manual".
Parameters:
connHttpConn connection object.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderConfig (HttpConn *conn)

Render the client configuration string in JSON.

Parameters:
connHttpConn connection object.
Returns:
A count of the bytes actually written.
API Stability:
PRototype.
See Also:
Esp
void espRenderDocument (HttpConn *conn, cchar *path)

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:
connHttp connection object.
pathRelative pathname from route->documents to the document to render.
API Stability:
Stable.
See Also:
Esp
ssize espRenderError (HttpConn *conn, int status, cchar *fmt, ...)

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

The output is Html escaped for security
Parameters:
connHttpConn connection object.
statusHttp status code.
fmtPrintf style message format.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderFile (HttpConn *conn, cchar *path)

Render the contents of a file back to the client.

Parameters:
connHttpConn connection object.
pathFile path name.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderSafe (HttpConn *conn, cchar *fmt, ...)

Render a formatted string after HTML escaping.

Description:
Render a formatted string of data and then HTML escape. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
connHttpConn connection object.
fmtPrintf style formatted string.
...Arguments for fmt.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderSafeString (HttpConn *conn, cchar *s)

Render a safe string of data to the client.

Description:
HTML escape a string and then write the string of data to the client. Data packets will be created as required to store the write data. This call may block waiting for the data to the client to drain.
Parameters:
connHttpConn connection object.
sString containing the data to write.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderString (HttpConn *conn, cchar *s)

Render a string of data to the client.

Description:
Render a string of data to the client. Data packets will be created as required to store the write data. This call may block waiting for data to drain to the client.
Parameters:
connHttpConn connection object.
sString containing the data to write.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
ssize espRenderVar (HttpConn *conn, cchar *name)

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:
connHttpConn connection object.
nameForm variable name.
Returns:
A count of the bytes actually written.
API Stability:
Stable.
See Also:
Esp
bool espRenderView (HttpConn *conn, cchar *view, int flags)

Render an ESP view page to the client.

Parameters:
connHttp connection object.
viewView name. The view name is interpreted relative to the matching route documents directory and may omit an ESP extension.
flagsReserved. Set to zero.
Returns:
True if a vew can be rendered.
API Stability:
Evolving.
See Also:
Esp
ssize espSendGrid (HttpConn *conn, EdiGrid *grid, int flags)

Send a database grid as a JSON string.

Description:
The JSON string is rendered as part of an enclosing "{ data: JSON }" wrapper.
Parameters:
connHttpConn connection object.
gridEDI grid.
flagsReserved. Set to zero.
Returns:
Number of bytes rendered.
API Stability:
Evolving.
See Also:
Esp
ssize espSendRec (HttpConn *conn, EdiRec *rec, int flags)

Send a database record as a JSON string.

Description:
The JSON string is rendered as part of an enclosing "{ data: JSON }" wrapper.
Parameters:
connHttpConn connection object.
recEDI record.
flagsReserved. Set to zero.
Returns:
Number of bytes rendered.
API Stability:
Evolving.
See Also:
Esp
ssize espSendResult (HttpConn *conn, bool success)

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:
connHttpConn connection object.
successTrue if the operation was a success.
Returns:
Number of bytes sent.
API Stability:
Evolving.
See Also:
Esp
bool espSetAutoFinalizing (HttpConn *conn, bool on)

Enable auto-finalizing for this request.

Parameters:
connHttpConn connection object.
onSet to "true" to enable auto-finalizing.
Returns:
"True" if auto-finalizing was enabled prior to this call.
API Stability:
Stable.
See Also:
Esp
void espSetConn (HttpConn *conn)

Set the current request connection.

Parameters:
connThe HttpConn connection object to define.
API Stability:
Stable.
See Also:
Esp
void espSetContentLength (HttpConn *conn, MprOff length)

Define a content length header in the transmission.

Description:
This will define a "Content-Length: NNN" request header.
Parameters:
connHttpConn connection object.
lengthNumeric value for the content length header.
API Stability:
Stable.
See Also:
Esp
void espSetContentType (HttpConn *conn, cchar *mimeType)

Set the transmission (response) content mime type.

Description:
Set the mime type Http header in the transmission.
Parameters:
connHttpConn connection object.
mimeTypeMime type string.
API Stability:
Stable.
See Also:
Esp
void espSetCookie (HttpConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, MprTicks lifespan, bool isSecure)

Set a cookie in the transmission.

Description:
Define a cookie to send in the transmission Http header.
Parameters:
connHttpConn connection object.
nameCookie name.
valueCookie value.
pathURI path to which the cookie applies.
domainString 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.
lifespanDuration 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.
isSecureSet to "true" if the cookie only applies for SSL based connections.
API Stability:
Stable.
See Also:
Esp
void espSetCurrentSession (HttpConn *conn)

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
void espSetFeedback (HttpConn *conn, cchar *type, cchar *fmt, ...)

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:
connHttp connection object.
typetype 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".
fmtPrintf style formatted string to use as the message.
API Stability:
Stable.
See Also:
Esp
void espSetFeedbackv (HttpConn *conn, cchar *type, cchar *fmt, va_list args)

Send a feedback message.

Parameters:
connHttp connection object.
typetype 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".
fmtPrintf style formatted string to use as the message.
argsVarargs style list.
API Stability:
Internal.
See Also:
Esp
EdiGrid * espSetGrid (HttpConn *conn, EdiGrid *grid)

Set the current database grid.

Returns:
The grid instance. This permits chaining.
API Stability:
Stable.
See Also:
Esp
void espSetHeader (HttpConn *conn, cchar *key, cchar *fmt, ...)

Set a transmission header.

Description:
Set a Http header to send with the request. If the header already exists, its value is overwritten.
Parameters:
connHttpConn connection object.
keyHttp response header key.
fmtPrintf style formatted string to use as the header key value.
...Arguments for fmt.
API Stability:
Stable.
See Also:
Esp
void espSetHeaderString (HttpConn *conn, cchar *key, cchar *value)

Set a simple key/value transmission header.

Description:
Set a Http header to send with the request. If the header already exists, its value is overwritten.
Parameters:
connHttpConn connection object.
keyHttp response header key.
valueString value for the key.
API Stability:
Stable.
See Also:
Esp
void espSetIntParam (HttpConn *conn, cchar *var, int value)

Set an integer request parameter value.

Description:
Set the value of a named request parameter to an integer value. Form variables are defined via www-urlencoded query or post data contained in the request.
Parameters:
connHttpConn connection object.
varName of the request parameter to set.
valueValue to set.
API Stability:
Stable.
See Also:
Esp
void espSetNotifier (HttpConn *conn, HttpNotifier notifier)

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
Before the notifier is invoked, espSetConn is called to set the connection object in the thread local storage. This enables the ESP Abbreviated API.
Parameters:
connHttpConn connection object created via httpCreateConn
notifierNotifier function.
API Stability:
Stable.
See Also:
Esp
void espSetParam (HttpConn *conn, cchar *var, cchar *value)

Set a request parameter value.

Description:
Set the value of a named request parameter to a string value. Parameters are defined via requeset POST data or request URI queries. This API permits these initial request parameters to be set or modified.
Parameters:
connHttpConn connection object.
varName of the request parameter to set.
valueValue to set.
API Stability:
Stable.
See Also:
Esp
EdiRec * espSetRec (HttpConn *conn, EdiRec *rec)

Set the current database record.

Description:
The current record is used to supply data to various abbreviated controls, such as: text(), input(), checkbox and dropdown().
Parameters:
connHttpConn connection object.
recRecord object to define as the current record.
Returns:
The grid instance. This permits chaining.
API Stability:
Stable.
See Also:
Esp
void espSetStatus (HttpConn *conn, int status)

Set a Http response status.

Description:
Set the Http response status for the request. This defaults to 200 (OK).
Parameters:
connHttpConn connection object.
statusHttp status code.
API Stability:
Stable.
See Also:
Esp
void espShowRequest (HttpConn *conn)

Show request details.

Description:
This e request details back to the client. This is useful as a debugging tool.
Parameters:
connHttpConn connection object.
API Stability:
Stable.
See Also:
Esp
void espUpdateCache (HttpConn *conn, cchar *uri, cchar *data, int lifesecs)

Update the cached content for a request.

Description:
Save the given content for future requests. This is useful if the caching mode has been set to "manual".
Parameters:
connHttpConn connection object.
uriRequest URI to cache for.
dataData to cache.
lifesecsTime in seconds to cache the data.
API Stability:
Stable.
See Also:
Esp
bool espUpdateRec (HttpConn *conn, EdiRec *rec)

Write a record to the database.

Description:
The record will be saved to the database after running any field validations. If any field validations fail to pass, the record will not be written and error details can be retrieved via ediGetRecErrors. If the record is a new record and the "id" column is EDI_AUTO_INC, then the "id" will be assigned prior to saving the record.
Parameters:
connHttpConn connection object.
recRecord to write to the database.
Returns:
"true" if the record can be successfully written.
API Stability:
Stable.
See Also:
Esp
cchar * espUri (HttpConn *conn, cchar *target)

Create a URI.

Description:
Create a URI link by expansions tokens based on the current request and route state. The target parameter may contain partial or complete URI information. The missing parts are supplied using the current request and route tables. The resulting URI is a normalized, server-local URI (that begins with "/"). The URI will include any defined route prefix, but will not include scheme, host or port components.
Parameters:
connHttpConn connection object.
targetThe 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
cchar * getMethod ()

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
cchar * makeUri (cchar *target)

Create a URI.

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

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:
gridEDI grid.
Returns:
Number of bytes sent.
API Stability:
Evolving.
See Also:
Esp
ssize sendRec (EdiRec *rec)

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:
recEDI record.
Returns:
Number of bytes sent.
API Stability:
Evolving.
See Also:
Esp
void sendResult (bool status)

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:
statusRequest success status. Note: this is not the HTTP response status code.
API Stability:
Evolving.
See Also:
Esp

EspRoute

EspRoute

EspRoute extended route configuration.

See Also:
Esp
Fields:
MprHash *actions Table of actions.
uintapp Is an esp mvc application.
cchar *appName App module name when compiled in combine mode.
uintcombine Combine C source into a single file.
cchar *combineScript Combine mode script filename.
cchar *combineSheet Combine mode stylesheet filename.
EspProccommonController Common code for all controllers.
uintcompile Enable recompiling the application or esp page.
cchar *compileCmd Compile command template.
uintcompileMode 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.
uintkeep Keep intermediate source code after compiling.
cchar *linkCmd Link command template.
MprTimeloaded 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.
uintupdate Enable dynamically updating the application.
MprHash *views Table of views.
cchar *winsdk Windows SDK.
void espAddHomeRoute (HttpRoute *route)

Add a route for the home page.

Description:
This will add a home page to route ESP applications. This will add the following route:
NameMethodPatternTarget
homeGET,POST,PUT^/$index.esp
Parameters:
routeParent route from which to inherit configuration.
API Stability:
Evolving.
See Also:
Esp
void espAddPak (HttpRoute *route, cchar *name, cchar *version)

Add the specified pak to the package.json packs list.

Parameters:
routeHttpRoute defining the ESP application.
nameDesired pak name. For example: "angular-mvc".
versionPack version string.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Prototype.
See Also:
Esp
void espAddRouteSet (HttpRoute *route, cchar *set)

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.
NameMethodPatternTarget
homeGET,POST,PUT^/$index.esp
Parameters:
routeParent route from which to inherit configuration.
setRoute set to select. Use "angular-mvc", or "html-mvc".
API Stability:
Stable.
See Also:
Esp
int espBindProc (HttpRoute *route, cchar *pattern, void *actionProc)

Define an action for a URI pattern.

Description:
This creates a new route and binds the action function to a URI pattern.
Parameters:
routeParent route object from which to inherit settings when creating the new route.
patternURI pattern to use to find the releavant route.
actionProcEspProc callback procedure to invoke when the action is requested.
API Stability:
Stable.
See Also:
Esp
char * espBuildScript (HttpRoute *route, cchar *page, cchar *path, cchar *cacheName, cchar *layout, EspState *state, char **err)

Convert an ESP web page into C code.

Description:
This parses an ESP web page into an equivalent C source view.
Parameters:
routeHttpRoute object.
pageESP web page script.
pathPathname for the ESP web page. This is used to process include directives which are resolved relative to this path.
cacheNameMD5 cache name. Not a full path.
layoutDefault layout page. Deprecated.
stateReserved. Must set to NULL.
errOutput parameter to hold any relevant error message.
Returns:
Compiled script. Return NULL on errors.
API Stability:
Evolving.
See Also:
Esp
int espCache (HttpRoute *route, cchar *uri, int lifesecs, int flags)

Add caching for response content.

Description:
This call configures caching for request responses. Caching may be used for any HTTP method, though typically it is most useful for state-less GET requests. Output data may be uniquely cached for requests with different request parameters (query, post and route parameters).

When server-side caching is requested and manual-mode is not enabled, the request response will be automatically cached. Subsequent client requests will revalidate the cached content with the server. If the server-side cached content has not expired, a HTTP Not-Modified (304) response will be sent and the client will use its client-side cached content. This results in a very fast transaction with the client as no response data is sent. Server-side caching will cache both the response headers and content.

If manual server-side caching is requested, the response will be automatically cached, but subsequent requests will require the handler to explicitly send cached content by calling httpWriteCached.

If client-side caching is requested, a "Cache-Control" Http header will be sent to the client with the caching "max-age" set to the lifesecs argument value. This causes the client to serve client-cached content and to not contact the server at all until the max-age expires. Alternatively, you can use httpSetHeader to explicitly set a "Cache-Control header. For your reference, here are some keywords that can be used in the Cache-Control Http header.

"max-age" Max time in seconds the resource is considered fresh. "s-maxage" Max time in seconds the resource is considered fresh from a shared cache. "public" marks authenticated responses as cacheable. "private" shared caches may not store the response. "no-cache" cache must re-submit request for validation before using cached copy. "no-store" response may not be stored in a cache. "must-revalidate" forces clients to revalidate the request with the server. "proxy-revalidate" similar to must-revalidate except only for proxy caches.

Use client-side caching for static content that will rarely change or for content for which using "reload" in the browser is an adequate solution to force a refresh. Use manual server-side caching for situations where you need to explicitly control when and how cached data is returned to the client. For most other situations, use server-side caching.
Parameters:
routeHttpRoute object.
uriURI 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}.
lifesecsLifespan of cache items in seconds. If not set to positive integer, the lifesecs will default to the route lifespan.
flagsCache 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
bool espCompile (HttpRoute *route, MprDispatcher *dispatcher, cchar *source, cchar *module, cchar *cacheName, int isView, char **errMsg)

Compile an ESP page, controller or view.

Description:
This compiles ESP resources into loadable, cached modules.
Parameters:
routeHttpRoute object.
dispatcherOptional dispatcher to use when waiting for the compilation command.
sourceESP source file name.
moduleOutput module file name.
cacheNameMD5 cache name. Not a full path.
isViewSet to "true" if the source is a view.
errMsgReference 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
void espDefineAction (HttpRoute *route, cchar *targetKey, void *actionProc)

Define an action.

Description:
Actions are C procedures that are invoked when specific URIs are routed to the controller/action pair.
Parameters:
routeHttpRoute object.
targetKeyTarget key used to select the action in a HttpRoute target. This is typically a URI prefix.
actionProcEspProc callback procedure to invoke when the action is requested.
API Stability:
Stable.
See Also:
Esp
void espDefineBase (HttpRoute *route, EspProc baseProc)

Define a base function to invoke for all controller actions.

Description:
A base function can be defined that will be called before calling any controller action. This emulates a super class constructor.
Parameters:
routeHttpRoute object.
baseProcFunction to call just prior to invoking a controller action.
API Stability:
Stable.
See Also:
Esp
void espDefineView (HttpRoute *route, cchar *path, void *viewProc)

Define a view.

Description:
Views are ESP web pages that are executed to return presentation data back to the client.
Parameters:
routeHttp route object.
pathPath to the ESP view source code.
viewProcEspViewPrococ callback procedure to invoke when the view is requested.
API Stability:
Stable.
See Also:
Esp
char * espExpandCommand (HttpRoute *route, cchar *command, cchar *source, cchar *module)

Expand a compile or link command template.

Description:
This expands a command template and replaces "${tokens}" with their equivalent value. The supported tokens are:
  • ARCH - Build architecture (i386, x86_64)
  • CC - Compiler pathname
  • DEBUG - Compiler debug options (-g, -Zi, -Od)
  • INC - Include directory (out/inc)
  • LIB - Library directory (out/lib, out/bin)
  • LIBS - Required libraries directory (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:
routeHttpRoute object.
commandHttp connection object.
sourceESP web page source pathname.
moduleOutput module pathname.
Returns:
An expanded command line.
API Stability:
Evolving.
See Also:
Esp
cchar * espGetConfig (HttpRoute *route, cchar *key, cchar *defaultValue)

Get a configuration value from the ESP package.json.

Parameters:
routeHttpRoute defining the ESP application.
keyConfiguration property path. May contain dots.
defaultValueDefault value to use if the configuration is not defined. May be null.
Returns:
The Configuration string value.
API Stability:
Stable.
See Also:
Esp
bool espHasPak (HttpRoute *route, cchar *name)

Test if the ESP application includes the specified pak.

Description:
This tests the dependencies property specified pak.
Parameters:
routeHttpRoute defining the ESP application.
nameDesired pak name. For example: "angular-mvc".
Returns:
True if the specified pak is supported.
API Stability:
Prototype.
See Also:
Esp
int espInit (HttpRoute *route, cchar *prefix, cchar *path)

Initialize ESP.

Description:
This initializes a route for ESP. This may be called multiple times for different routes.
Parameters:
routeParent route from which to inherit configuration.
prefixOptional URI prefix for all application URIs.
pathPathname to the esp.json file.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Prototype.
See Also:
Esp
int espLoadCompilerRules (HttpRoute *route)

Load the compiler rules from esp-compile.json.

Parameters:
routeHttpRoute object.
API Stability:
Prototype.
See Also:
Esp
int espLoadConfig (HttpRoute *route)

Configure an ESP application.

Description:
Load the esp.json and package.json configuration files.
Parameters:
routeParent route from which to inherit configuration.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Prototype.
See Also:
Esp
EspRoute * espRoute (HttpRoute *route)

Return the corresponding EspRoute for the given Route.

Description:
Returns the defined EspRoute for the given Route. Creates a new EspRoute if required.
Parameters:
routeParent route from which to inherit configuration.
Returns:
The EspRoute object.
API Stability:
Prototype.
Parameters:
route
See Also:
Esp
int espSaveConfig (HttpRoute *route)

Save the in-memory ESP package.json configuration to the default location for the ESP application defined by the specified route.

Parameters:
routeHttpRoute defining the ESP application.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Evolving.
See Also:
Esp
int espSetConfig (HttpRoute *route, cchar *key, cchar *value)

Set a configuration value to the ESP package.json.

Description:
This updates the in-memory copy of the package.json only.
Parameters:
routeHttpRoute defining the ESP application.
keyConfiguration property path. May contain dots.
valueValue to set the property to.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Evolving.
See Also:
Esp
bool espTestConfig (HttpRoute *route, cchar *key, cchar *desired)

Test if a configuration property from the ESP package.json has a desired value.

Parameters:
routeHttpRoute defining the ESP application.
keyConfiguration property path. May contain dots.
desiredDesired value to compare with.
Returns:
True if the configuration property has the desired value.
API Stability:
Evolving.
See Also:
Esp

Functions

EspRoute * espCreateRoute (HttpRoute *route)

Create an EspRoute object.

Parameters:
routeHttpRoute to associate with.
Returns:
EspRoute object.
int espEmail (HttpConn *conn, cchar *to, cchar *from, cchar *subject, MprTime date, cchar *mime, cchar *message, MprList *files)

Send mail using sendmail.

Parameters:
connHttpConn connection object.
toMessage recipient.
fromMessage sender.
subjectMessage subject.
dateMessage creation date. Set to null to use the current date/time.
mimeMessage mime type. Set to null for text/plain.
messageMessage body.
filesMprList of files to send with the message.
Returns:
Zero if the email is successfully sent.
API Stability:
Evolving.
void espInitHtmlOptions (Esp *esp)

Add HTLM internal options to the Esp.options hash.

int espInitParser ()

Initialize the ESP configuration file parser.

int espOpen (MprModule *module)

ESP initialization entry point.

Parameters:
moduleModule object if loaded as an MPR module.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Evolving.
ssize espRenderFeedback (HttpConn *conn, cchar *types)

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:
connHttp connection object.
typesTypes 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.
void espSetData (HttpConn *conn, void *data)

Set a private data reference for the current request.

Parameters:
connHttpConn object.
dataData object to associate with the current request. This must be a managed reference.
Returns:
Reference to private data.
API Stability:
Prototype.
int espStaticInitialize (EspModuleEntry entry, cchar *appName, cchar *routeName)

Initialize a static library ESP module.

Description:
This invokes the ESP initializers for the required pre-compiled ESP shared library.
Parameters:
entryESP initialization function.
appNameName of the ESP application.
routeNameName 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

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

Procedure callback.

API Stability:
Stable.
typedef EspProc EspAction.

ESP Action.

Description:
Actions are run after a request URI is routed to a controller.
API Stability:
Stable.
See Also:
Esp
typedef void(* EspViewProc)(HttpConn *conn).

View procedure callback.

Parameters:
connHttp connection object.
API Stability:
Stable.
See Also:
Esp
typedef int(* EspModuleEntry)(struct HttpRoute *route, MprModule *module).

Entry point for a loadable ESP module.

Parameters:
routeHttpRoute object.
moduleMpr module object.
Returns:
Zero if successful, otherwise a negative MPR error code.
API Stability:
Stable.
See Also:
Esp
Esp

Top level ESP structure.

Fields:
intcompileMode 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.
intinUse Active ESP request counter.
MprThreadLocal *local Thread local data.
MprMutex *mutex Multithread lock.
intreloading Reloading ESP and modules.
MprHash *vstudioEnv Visual Studio environment.

© Embedthis Software, 2003-2015. All rights reserved.