ESP API

Extensions

EspParse	ESP page parser structure.
EspReq	ESP request structure.
EspRoute	EspRoute extended route configuration.

Functions

void	espAction(HttpRoute route, cchar targetKey, cchar *abilities, EspProc actionProc)
	Define an action.
void	espAddHeader(HttpStream stream, cchar key, cchar *fmt, ...)
	Add a header to the transmission using a format string.
void	espAddHeaderString(HttpStream stream, cchar key, cchar *value)
	Add a header to the transmission.
void	espAddHomeRoute(HttpRoute *route)
	Add a route for the home page.
void	espAddParam(HttpStream stream, cchar var, cchar *value)
	Add a request parameter value if it is not already defined.
void	espAddRouteSet(HttpRoute route, cchar set)
	Add a route set.
void	espAppendHeader(HttpStream stream, cchar key, cchar *fmt, ...)
	Append a transmission header.
void	espAppendHeaderString(HttpStream stream, cchar key, cchar *value)
	Append a transmission header string.
void	espAutoFinalize(HttpStream *stream)
	Auto-finalize transmission of the http request.
int	espBindProc(HttpRoute route, cchar pattern, void *actionProc)
	Define an action for a URI pattern.
char *	espBuildScript(HttpRoute route, cchar page, cchar path, cchar cacheName, cchar layout, EspState state, char **err)
	Convert an ESP web page into C code.
int	espCache(HttpRoute route, cchar uri, int lifesecs, int flags)
	Add caching for response content.
void	espClearCurrentSession(HttpStream *stream)
	Clear the current authenticated session.
bool	espCompile(HttpRoute route, MprDispatcher dispatcher, cchar source, cchar module, cchar cacheName, int isView, char *errMsg)
	Compile an ESP page, controller or view.
void	espController(HttpRoute *route, EspProc baseProc)
	Define a common controller function to invoke before invoking for all controller actions.
EspRoute *	espCreateRoute(HttpRoute *route)
	Create an EspRoute object.
cchar *	espCreateSession(HttpStream *stream)
	Create a session state object.
void	espDefineBase(HttpRoute *route, EspLegacyProc baseProc),ME_DEPRECATED("Use,espDefineCommon,instead")
	Define a base controller function to invoke for all controller actions.
void	espDefineView(HttpRoute route, cchar path, void *viewProc)
	Define a view.
void	espDestroySession(HttpStream *stream)
	Destroy a session state object.
int	espEmail(HttpStream stream, cchar to, cchar from, cchar subject, MprTime date, cchar mime, cchar message, MprList *files)
	Send mail using sendmail.
char *	espExpandCommand(HttpRoute route, cchar command, cchar source, cchar module)
	Expand a compile or link command template.
void	espFinalize(HttpStream *stream)
	Indicate the request is finalized.
void	espFlush(HttpStream *stream)
	Flush transmit data.
HttpAuth *	espGetAuth(HttpStream *stream)
	Get the current route HttpAuth object.
cchar *	espGetConfig(HttpRoute route, cchar key, cchar *defaultValue)
	Get a configuration value from the ESP pak.json.
MprOff	espGetContentLength(HttpStream *stream)
	Get the receive body content length.
cchar *	espGetContentType(HttpStream *stream)
	Get the receive body content type.
cchar *	espGetCookie(HttpStream stream, cchar name)
	Get a request cookie.
cchar *	espGetCookies(HttpStream *stream)
	Get the request cookies.
void *	espGetData(HttpStream *stream)
	Get the private data reference for the current request set via setData.
Edi *	espGetDatabase(HttpStream *stream)
	Get the current database instance.
cchar *	espGetDocuments(HttpStream *stream)
	Get the default documents directory for the request route.
EspRoute *	espGetEspRoute(HttpStream *stream)
	Get the current extended route information.
cchar *	espGetFeedback(HttpStream stream, cchar type)
	Get a feedback message defined via feedback.
EdiGrid *	espGetGrid(HttpStream *stream)
	Get the current database grid reference.
cchar *	espGetHeader(HttpStream stream, cchar key)
	Get an rx http header.
MprHash *	espGetHeaderHash(HttpStream *stream)
	Get the hash table of rx Http headers.
char *	espGetHeaders(HttpStream *stream)
	Get all the request http headers.
int	espGetIntParam(HttpStream stream, cchar var, int defaultValue)
	Get a request pararmeter as an integer.
cchar *	espGetMethod(HttpStream *stream)
	Get the HTTP method.
cchar *	espGetParam(HttpStream stream, cchar var, cchar *defaultValue)
	Get a request parameter.
MprJson *	espGetParamObj(HttpStream stream, cchar var)
	Get a request pararmeter as a JSON object.
MprJson *	espGetParams(HttpStream *stream)
	Get the request parameters.
cchar *	espGetPath(HttpStream *stream)
	Get the request URI path string.
cchar *	espGetQueryString(HttpStream *stream)
	Get the request URI query string.
cchar *	espGetReferrer(HttpStream *stream)
	Get the referring URI.
HttpRoute *	espGetRoute(HttpStream *stream)
	Get the current route HttpRoute object.
Edi *	espGetRouteDatabase(HttpRoute *route)
	Get the default database defined on a route.
cchar *	espGetRouteVar(HttpStream stream, cchar var)
	Get a route variable.
cchar *	espGetSessionID(HttpStream *stream, int create)
	Get the session state ID.
int	espGetStatus(HttpStream *stream)
	Get the response status.
cchar *	espGetStatusMessage(HttpStream *stream)
	Get the Http response status message.
HttpStream *	espGetStream(void)
	Get the current request stream.
MprList *	espGetUploads(HttpStream *stream)
	Get the uploaded files.
cchar *	espGetUri(HttpStream *stream)
	Get the request URI string.
bool	espHasGrid(HttpStream *stream)
	Test if a current grid has been defined via espSetGrid
bool	espHasRec(HttpStream *stream)
	Test if a current record has been defined and save to the database.
int	espInit(HttpRoute route, cchar prefix, cchar *path)
	Initialize ESP.
void	espInitHtmlOptions(Esp *esp)
	Add HTLM internal options to the Esp.options hash.
int	espInitParser(void)
	Initialize the ESP configuration file parser.
bool	espIsAuthenticated(HttpStream *stream)
	Test if the user is authenticated.
bool	espIsCurrentSession(HttpStream *stream)
	Test if the request is being made on behalf of the current, single authenticated user.
bool	espIsEof(HttpStream *stream)
	Test if the receive input stream is at end-of-file.
bool	espIsFinalized(HttpStream *stream)
	Test if the request has been finalized.
bool	espIsSecure(HttpStream *stream)
	Test if the stream is using SSL and is secure.
int	espLoadCompilerRules(HttpRoute *route)
	Load the compiler rules from esp-compile.json.
int	espLoadConfig(HttpRoute *route)
	Load configuration for an ESP application.
bool	espMatchParam(HttpStream stream, cchar var, cchar *value)
	Match a request parameter with an expected value.
int	espOpen(MprModule *module)
	ESP initialization entry point.
EdiGrid *	espReadTable(HttpStream stream, cchar tableName)
	Read a table from the current database.
ssize	espReceive(HttpStream stream, char buf, ssize size)
	Read receive body content.
void	espRedirect(HttpStream stream, int status, cchar target)
	Redirect the client.
void	espRedirectBack(HttpStream *stream)
	Redirect the client back to the referrer.
void	espRemoveCookie(HttpStream stream, cchar name)
	Remove a cookie.
int	espRemoveHeader(HttpStream stream, cchar key)
	Remove a header from the transmission.
void	espRemoveSessionVar(HttpStream stream, cchar name)
	Remove a session state variable.
ssize	espRender(HttpStream stream, cchar fmt, ...)
	Render a formatted string.
ssize	espRenderBlock(HttpStream stream, cchar buf, ssize size)
	Render a block of data to the client.
ssize	espRenderCached(HttpStream *stream)
	Render cached content.
ssize	espRenderConfig(HttpStream *stream)
	Render the client configuration string in JSON.
void	espRenderDocument(HttpStream stream, cchar path)
	Render an ESP document.
ssize	espRenderError(HttpStream stream, int status, cchar fmt, ...)
	Render an error message back to the client and finalize the request.
ssize	espRenderFeedback(HttpStream stream, cchar types)
	Render feedback messages.
ssize	espRenderFile(HttpStream stream, cchar path)
	Render the contents of a file back to the client.
ssize	espRenderSafe(HttpStream stream, cchar fmt, ...)
	Render a formatted string after HTML escaping.
ssize	espRenderSafeString(HttpStream stream, cchar s)
	Render a safe string of data to the client.
ssize	espRenderString(HttpStream stream, cchar s)
	Render a string of data to the client.
ssize	espRenderVar(HttpStream stream, cchar name)
	Render the value of a request variable to the client.
bool	espRenderView(HttpStream stream, cchar view, int flags)
	Render an ESP view page to the client.
EspRoute *	espRoute(HttpRoute *route, bool create)
	Return the corresponding EspRoute for the given Route.
ssize	espSendGrid(HttpStream stream, EdiGrid grid, int flags)
	Send a database grid as a JSON string.
ssize	espSendRec(HttpStream stream, EdiRec rec, int flags)
	Send a database record as a JSON string.
ssize	espSendResult(HttpStream *stream, bool success)
	Send a JSON response result.
bool	espSetAutoFinalizing(HttpStream *stream, bool on)
	Enable auto-finalizing for this request.
int	espSetConfig(HttpRoute route, cchar key, cchar *value)
	Set a configuration value to the ESP pak.json.
void	espSetContentLength(HttpStream *stream, MprOff length)
	Define a content length header in the transmission.
void	espSetContentType(HttpStream stream, cchar mimeType)
	Set the transmission (response) content mime type.
void	espSetCookie(HttpStream stream, cchar name, cchar value, cchar path, cchar *domain, MprTicks lifespan, bool isSecure)
	Set a cookie in the transmission.
void	espSetCurrentSession(HttpStream *stream)
	Set this authenticated session as the current session.
void	espSetData(HttpStream stream, void data)
	Set a private data reference for the current request.
void	espSetFeedback(HttpStream stream, cchar type, cchar *fmt, ...)
	Set a feedback message.
void	espSetFeedbackv(HttpStream stream, cchar type, cchar *fmt, va_list args)
	Send a feedback message.
EdiGrid *	espSetGrid(HttpStream stream, EdiGrid grid)
	Set the current database grid.
void	espSetHeader(HttpStream stream, cchar key, cchar *fmt, ...)
	Set a transmission header.
void	espSetHeaderString(HttpStream stream, cchar key, cchar *value)
	Set a simple key/value transmission header.
void	espSetNotifier(HttpStream *stream, HttpNotifier notifier)
	Define a notifier callback for this stream.
void	espSetParam(HttpStream stream, cchar var, cchar *value)
	Set a request parameter value.
void	espSetParamInt(HttpStream stream, cchar var, int value)
	Set an integer request parameter value.
EdiRec *	espSetRec(HttpStream stream, EdiRec rec)
	Set the current database record.
void	espSetStatus(HttpStream *stream, int status)
	Set a Http response status.
void	espSetStream(HttpStream *stream)
	Set the current request stream.
void	espShowRequest(HttpStream *stream)
	Show request details.
int	espStaticInitialize(EspModuleEntry entry, cchar appName, cchar routeName)
	Initialize a static library ESP module.
bool	espTestConfig(HttpRoute route, cchar key, cchar *desired)
	Test if a configuration property from the ESP pak.json has a desired value.
void	espUpdateCache(HttpStream stream, cchar uri, cchar *data, int lifesecs)
	Update the cached content for a request.
bool	espUpdateRec(HttpStream stream, EdiRec rec)
	Write a record to the database.
cchar *	espUri(HttpStream stream, cchar target)
	Create a URI.

Typedefs

Esp	Top level ESP structure.
EspAction	Action definition.
EspLegacyProc	Procedure callback.
EspModuleEntry	Entry point for a loadable ESP module.
EspViewProc	View procedure callback.

Defines

#define	ESP_COMPILE_JSON "esp-compile.json"
	Compile rules filename.
#define	ESP_COMPILE_OPTIMIZED 1
	Override to compile in release mode.
#define	ESP_COMPILE_SYMBOLS 0
	Override to compile in debug mode.
#define	ESP_LIFESPAN (3600 * TPS)
	Default generated content cache lifespan.
#define	ESP_LISTEN "4000"
	Default listening endpoint for the esp program.
#define	ESP_TOK_INCR 1024
	Growth increment for ESP tokens.
#define	ESP_UNLOAD_TIMEOUT (10)
	Very short timeout for reloading.
#define	ME_ESP_ABBREV 1
	Enable the ESP Abbreviated API.
#define	ME_ESP_EMAIL_TIMEOUT (60 * 1000)
	Timeout for sending email.
#define	ME_ESP_RELOAD_TIMEOUT (5 * 1000)
	Timeout for reloading esp modules.

EspParse

ESP page parser structure.

See Also:: Esp

EspReq

ESP request structure.

API Stability:: Internal.

See Also:: Esp

Fields:

int	autoFinalize	Request is or will be auto-finalized.
cchar *	commandLine	Command line for compile/link.
void *	data	Custom data for request (managed).
Edi *	edi	Database for this request.
Esp *	esp	Convenient esp reference.
MprHash *	feedback	Feedback messages.
int	lastDomID	Last generated DOM ID.
MprHash *	lastFeedback	Feedback messages from the last request.
HttpNotifier	notifier	Http state change notification callback.
HttpRoute *	route	Route reference.
int	sessionProbed	Already probed for session store.
void *	staticData	Custom data for request (unmanaged).

void espAddHeader (HttpStream *stream, 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:

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

API Stability:: Stable.

See Also:: Esp

void espAddHeaderString (HttpStream *stream, cchar *key, cchar *value)

Add a header to the transmission.

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

Parameters:

stream	HttpStream stream object.
key	Http response header key.
value	Value to set for the header.

API Stability:: Stable.

See Also:: Esp

void espAddParam (HttpStream *stream, cchar *var, cchar *value)

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

Parameters:

stream	HttpStream stream object.
var	Name of the request parameter to set.
value	Value to set.

API Stability:: Stable.

See Also:: Esp

void espAppendHeader (HttpStream *stream, 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:

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

API Stability:: Stable.

See Also:: Esp

void espAppendHeaderString (HttpStream *stream, 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:

stream	HttpStream stream object.
key	Http response header key.
value	Value to set for the header.

API Stability:: Stable.

See Also:: Esp

void espAutoFinalize (HttpStream *stream)

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:

stream

HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

void espClearCurrentSession (HttpStream *stream)

Clear the current authenticated session.

API Stability:: Stable.

See Also:: Esp

cchar * * espCreateSession (HttpStream *stream)

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:

stream

HttpStream stream object.

Returns:: Session ID string.

API Stability:: Stable.

See Also:: Esp

void espDestroySession (HttpStream *stream)

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:

stream

HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

void espFinalize (HttpStream *stream)

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:

stream

HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

void espFlush (HttpStream *stream)

Flush transmit data.

Description:: This writes any buffered data and initiates writing to the peer. This will not block.

Parameters:

stream

HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

HttpAuth * * espGetAuth (HttpStream *stream)

Get the current route HttpAuth object.

Parameters:

stream

HttpStream stream object.

Returns:: The HttpAuth object.

API Stability:: Stable.

See Also:: Esp

MprOff espGetContentLength (HttpStream *stream)

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:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

cchar * * espGetContentType (HttpStream *stream)

Get the receive body content type.

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

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

cchar * * espGetCookie (HttpStream *stream, cchar *name)

Get a request cookie.

Description:: Get the cookie for the given name.

Parameters:

stream	HttpStream stream object.
name	Cookie name to retrieve.

Returns:: The cookie value Return null if the cookie is not defined.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetCookies (HttpStream *stream)

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:

stream

HttpStream stream 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 (HttpStream *stream)

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

Parameters:

stream

HttpStream object.

API Stability:: Stable.

See Also:: Esp

Edi * * espGetDatabase (HttpStream *stream)

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 (HttpStream *stream)

Get the default documents directory for the request route.

Parameters:

stream

HttpStream stream object.

Returns:: A directory path name.

API Stability:: Stable.

See Also:: Esp

EspRoute * * espGetEspRoute (HttpStream *stream)

Get the current extended route information.

Returns:: EspRoute instance.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetFeedback (HttpStream *stream, cchar *type)

Get a feedback message defined via feedback.

Parameters:

stream	HttpStream object.
type	type of feedback message to retrieve. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".

Returns:: Reference to the feedback message.

API Stability:: Stable.

See Also:: Esp

EdiGrid * * espGetGrid (HttpStream *stream)

Get the current database grid reference.

Description:: The current grid is defined via setGrid.

Returns:: EdiGrid instance.

API Stability:: Deprecated.

See Also:: Esp

cchar * * espGetHeader (HttpStream *stream, cchar *key)

Get an rx http header.

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

Parameters:

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

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

API Stability:: Stable.

See Also:: Esp

MprHash * * espGetHeaderHash (HttpStream *stream)

Get the hash table of rx Http headers.

Description:: Get the internal hash table of rx headers.

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

char * * espGetHeaders (HttpStream *stream)

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:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

int espGetIntParam (HttpStream *stream, cchar *var, int defaultValue)

Get a request pararmeter as an integer.

Description:: Get the value of a named request parameter. Request parameters are defined via www-urlencoded query, post data contained in the request and route parameters. Request parameters are stored as JSON tree objects and may contain nested properties.

Parameters:

stream	HttpStream stream object.
var	Name of the request parameter to retrieve.
defaultValue	Default value to return if the variable is not defined. Can be null.

Returns:: Integer containing the request parameter's value.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetMethod (HttpStream *stream)

Get the HTTP method.

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

Returns:: The HttpStream.rx.method property.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetParam (HttpStream *stream, cchar *var, cchar *defaultValue)

Get a request parameter.

Description:: Get the value of a named request parameter. Request parameters are defined via www-urlencoded query, post data contained in the request and route parameters. Route parameters are stored as JSON tree objects and may contain nested properties.

Parameters:

stream	HttpStream stream object.
var	Name of the request parameter to retrieve.
defaultValue	Default value to return if the variable is not defined. Can be null.

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

API Stability:: Stable.

See Also:: Esp

MprJson * * espGetParamObj (HttpStream *stream, cchar *var)

Get a request pararmeter as a JSON object.

Description:: Get the value of a named request parameter. Request parameters are defined via www-urlencoded query, post data contained in the request and route parameters. Request parameters are stored as JSON tree objects and may contain nested properties.

Parameters:

stream	HttpStream stream object.
var	Name of the request parameter to retrieve.

Returns:: JSON parameter object.

API Stability:: Stable.

See Also:: Esp

MprJson * * espGetParams (HttpStream *stream)

Get the request parameters.

Description:: This call gets the request parameters for the current request.

Description:: Request parameters are defined via www-urlencoded query, post data contained in the request and route parameters. Request parameters are stored as JSON tree objects and may contain nested properties.

Parameters:

stream

HttpStream stream object.

Returns:: MprJson instance containing the request parameters.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetPath (HttpStream *stream)

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 espGetStream()->rx->pathInfo.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetQueryString (HttpStream *stream)

Get the request URI query string.

Description:: Get URI query string sent with the current request.

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

cchar * * espGetReferrer (HttpStream *stream)

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:

stream

HttpStream stream 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 (HttpStream *stream)

Get the current route HttpRoute object.

Parameters:

stream

HttpStream stream object.

Returns:: The HttpRoute object.

API Stability:: Stable.

See Also:: Esp

Edi * * espGetRouteDatabase (HttpRoute *route)

Get the default database defined on a route.

Parameters:

route

HttpRoute object.

Returns:: Database instance object.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetRouteVar (HttpStream *stream, cchar *var)

Get a route variable.

Description:: Get the value of a request route variable.

Parameters:

stream	HttpStream stream object.
var	Name of the request parameter to retrieve.

Returns:: String containing the route variable value. Caller should not free.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetSessionID (HttpStream *stream, 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 stream.

Parameters:

stream	HttpStream stream object.
create	Set to true to create a new session if one does not already exist.

Returns:: The session state identifier string.

API Stability:: Stable.

See Also:: Esp

int espGetStatus (HttpStream *stream)

Get the response status.

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

cchar * * espGetStatusMessage (HttpStream *stream)

Get the Http response status message.

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

Parameters:

stream

HttpStream stream object.

Returns:: A Http status message.

API Stability:: Stable.

See Also:: Esp

HttpStream * * espGetStream (void )

Get the current request stream.

Returns:: The HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

MprList * * espGetUploads (HttpStream *stream)

Get the uploaded files.

Description:: Get the list of uploaded files. This list entries are HttpUploadFile objects.

Parameters:

stream

HttpStream stream object.

Returns:: A list of HttpUploadFile objects.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetUri (HttpStream *stream)

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 espGetStream()->rx->uri.

API Stability:: Stable.

See Also:: Esp

bool espHasGrid (HttpStream *stream)

Test if a current grid has been defined via espSetGrid

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

API Stability:: Deprecated.

See Also:: Esp

bool espHasRec (HttpStream *stream)

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 espIsAuthenticated (HttpStream *stream)

Test if the user is authenticated.

Parameters:

stream

HttpStream stream object.

Returns:: True if the username and password have been authenticated.

API Stability:: Stable.

See Also:: Esp

bool espIsCurrentSession (HttpStream *stream)

Test if the request 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:: Stable.

See Also:: Esp

bool espIsEof (HttpStream *stream)

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

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

bool espIsFinalized (HttpStream *stream)

Test if the request has been finalized.

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

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

bool espIsSecure (HttpStream *stream)

Test if the stream is using SSL and is secure.

Parameters:

stream

HttpStream stream object.

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

API Stability:: Stable.

See Also:: Esp

bool espMatchParam (HttpStream *stream, 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:

stream	HttpStream stream object.
var	Name of the request parameter.
value	Expected value to match.

Returns:: "True" if the value matches.

API Stability:: Stable.

See Also:: Esp

EdiGrid * * espReadTable (HttpStream *stream, cchar *tableName)

Read a table from the current database.

Parameters:

stream	HttpStream stream object.
tableName	Database table name.

Returns:: An EDI grid containing data for the table.

API Stability:: Stable.

See Also:: Esp

ssize espReceive (HttpStream *stream, 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:

stream	HttpStream stream object.
buf	Buffer to accept content data.
size	Size of the buffer.

Returns:: A count of bytes read into the buffer.

API Stability:: Stable.

See Also:: Esp

void espRedirect (HttpStream *stream, int status, cchar *target)

Redirect the client.

Description:: Redirect the client to a new uri.

Parameters:

stream	HttpStream stream object.
status	Http status code to send with the response.
target	New target uri for the client.

API Stability:: Stable.

See Also:: Esp

void espRedirectBack (HttpStream *stream)

Redirect the client back to the referrer.

Description:: Redirect the client to the referring URI.

Parameters:

stream

HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

void espRemoveCookie (HttpStream *stream, cchar *name)

Remove a cookie.

Parameters:

stream	HttpStream stream object.
name	Cookie name.

API Stability:: Stable.

See Also:: Esp

int espRemoveHeader (HttpStream *stream, cchar *key)

Remove a header from the transmission.

Description:: Remove a header if present.

Parameters:

stream	HttpStream stream object.
key	Http response header key.

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

API Stability:: Stable.

See Also:: Esp

void espRemoveSessionVar (HttpStream *stream, cchar *name)

Remove a session state variable.

Parameters:

stream	HttpStream stream object.
name	Variable name to set.

API Stability:: Stable.

See Also:: Esp

ssize espRender (HttpStream *stream, 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 and may yield to the garbage collector.

Parameters:

stream	HttpStream stream object.
fmt	Printf style formatted string.
...	Arguments for fmt.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderBlock (HttpStream *stream, 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. This call may block waiting for the client to absorb the data.

Parameters:

stream	HttpStream stream object.
buf	Buffer containing the write data.
size	Size of the data in buf.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderCached (HttpStream *stream)

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:

stream

HttpStream stream object.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderConfig (HttpStream *stream)

Render the client configuration string in JSON.

Parameters:

stream

HttpStream stream object.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

void espRenderDocument (HttpStream *stream, 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. This routine may yield.

Parameters:

stream	Http stream object.
path	Relative pathname from route->documents to the document to render.

API Stability:: Stable.

See Also:: Esp

ssize espRenderError (HttpStream *stream, int status, cchar *fmt, ...)

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

The output is Html escaped for security

Parameters:

stream	HttpStream stream object.
status	Http status code.
fmt	Printf style message format.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderFile (HttpStream *stream, cchar *path)

Render the contents of a file back to the client.

Parameters:

stream	HttpStream stream object.
path	File path name.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderSafe (HttpStream *stream, 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:

stream	HttpStream stream object.
fmt	Printf style formatted string.
...	Arguments for fmt.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderSafeString (HttpStream *stream, 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:

stream	HttpStream stream object.
s	String containing the data to write.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderString (HttpStream *stream, 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:

stream	HttpStream stream object.
s	String containing the data to write.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderVar (HttpStream *stream, 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:

stream	HttpStream stream object.
name	Request parameter variable name.

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

bool espRenderView (HttpStream *stream, cchar *view, int flags)

Render an ESP view page to the client.

Parameters:

stream	Http stream object.
view	View name. The view name is interpreted relative to the matching route documents directory and may omit an ESP extension. This routine may yield.
flags	Reserved. Set to zero.

Returns:: True if a vew can be rendered.

API Stability:: Stable.

See Also:: Esp

ssize espSendGrid (HttpStream *stream, 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:

stream	HttpStream stream object.
grid	EDI grid.
flags	Reserved. Set to zero.

Returns:: Number of bytes rendered.

API Stability:: Stable.

See Also:: Esp

ssize espSendRec (HttpStream *stream, 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:

stream	HttpStream stream object.
rec	EDI record.
flags	Reserved. Set to zero.

Returns:: Number of bytes rendered.

API Stability:: Stable.

See Also:: Esp

ssize espSendResult (HttpStream *stream, 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: "{ error: 0/1, feedback: {messages}, fieldErrors: {messages}}" wrapper. The feedback messages are created via the espSetFeedback API. Field errors are created by ESP validations.

Parameters:

stream	HttpStream stream object.
success	True if the operation was a success.

Returns:: Number of bytes sent.

API Stability:: Stable.

See Also:: Esp

bool espSetAutoFinalizing (HttpStream *stream, bool on)

Enable auto-finalizing for this request.

Parameters:

stream	HttpStream stream object.
on	Set to "true" to enable auto-finalizing.

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

API Stability:: Stable.

See Also:: Esp

void espSetContentLength (HttpStream *stream, MprOff length)

Define a content length header in the transmission.

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

Parameters:

stream	HttpStream stream object.
length	Numeric value for the content length header.

API Stability:: Stable.

See Also:: Esp

void espSetContentType (HttpStream *stream, cchar *mimeType)

Set the transmission (response) content mime type.

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

Parameters:

stream	HttpStream stream object.
mimeType	Mime type string.

API Stability:: Stable.

See Also:: Esp

void espSetCookie (HttpStream *stream, 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:

stream	HttpStream stream object.
name	Cookie name.
value	Cookie value.
path	URI path to which the cookie applies.
domain	String Domain in which the cookie applies. Must have 2-3 "." and begin with a leading ".". For example: domain: .example.com. Set to NULL to use the current connection's client domain. Some browsers will accept cookies without the initial ".", but the spec: (RFC 2109) requires it.
lifespan	Duration for the cookie to persist in msec. Set to a negative number to delete a cookie. Set to zero for a "session" cookie that lives only for the user's session.
isSecure	Set to "true" if the cookie only applies for SSL based connections.

API Stability:: Stable.

See Also:: Esp

void espSetCurrentSession (HttpStream *stream)

Set this authenticated session as the current session.

Description:: Set esp.login.single to true to enable current session tracking.

API Stability:: Stable.

See Also:: Esp

void espSetFeedback (HttpStream *stream, 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:

stream	Http stream object.
type	type of feedback message. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".
fmt	Printf style formatted string to use as the message.

API Stability:: Stable.

See Also:: Esp

void espSetFeedbackv (HttpStream *stream, cchar *type, cchar *fmt, va_list args)

Send a feedback message.

Parameters:

stream	Http stream object.
type	type of feedback message. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".
fmt	Printf style formatted string to use as the message.
args	Varargs style list.

API Stability:: Internal.

See Also:: Esp

EdiGrid * * espSetGrid (HttpStream *stream, EdiGrid *grid)

Set the current database grid.

Returns:: The grid instance. This permits chaining.

API Stability:: Stable.

See Also:: Esp

void espSetHeader (HttpStream *stream, 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:

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

API Stability:: Stable.

See Also:: Esp

void espSetHeaderString (HttpStream *stream, 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:

stream	HttpStream stream object.
key	Http response header key.
value	String value for the key.

API Stability:: Stable.

See Also:: Esp

void espSetNotifier (HttpStream *stream, HttpNotifier notifier)

Define a notifier callback for this stream.

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 stream 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, espSetStream is called to set the stream object in the thread local storage. This enables the ESP Abbreviated API.

Parameters:

stream	HttpStream stream object created via httpCreateStream
notifier	Notifier function.

API Stability:: Stable.

See Also:: Esp

void espSetParam (HttpStream *stream, 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:

stream	HttpStream stream object.
var	Name of the request parameter to set.
value	Value to set.

API Stability:: Stable.

See Also:: Esp

void espSetParamInt (HttpStream *stream, cchar *var, int value)

Set an integer request parameter value.

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

Parameters:

stream	HttpStream stream object.
var	Name of the request parameter to set.
value	Value to set.

API Stability:: Stable.

See Also:: Esp

EdiRec * * espSetRec (HttpStream *stream, 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:

stream	HttpStream stream object.
rec	Record object to define as the current record.

Returns:: The grid instance. This permits chaining.

API Stability:: Stable.

See Also:: Esp

void espSetStatus (HttpStream *stream, int status)

Set a Http response status.

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

Parameters:

stream	HttpStream stream object.
status	Http status code.

API Stability:: Stable.

See Also:: Esp

void espSetStream (HttpStream *stream)

Set the current request stream.

Parameters:

stream

The HttpStream stream object to define.

API Stability:: Stable.

See Also:: Esp

void espShowRequest (HttpStream *stream)

Show request details.

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

Parameters:

stream

HttpStream stream object.

API Stability:: Stable.

See Also:: Esp

void espUpdateCache (HttpStream *stream, 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:

stream	HttpStream stream object.
uri	Request URI to cache for.
data	Data to cache.
lifesecs	Time in seconds to cache the data.

API Stability:: Stable.

See Also:: Esp

bool espUpdateRec (HttpStream *stream, 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:

stream	HttpStream stream object.
rec	Record to write to the database.

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

API Stability:: Stable.

See Also:: Esp

cchar * * espUri (HttpStream *stream, 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:

stream

HttpStream stream object.

target

The URI target. The target parameter can be a URI string or JSON style set of options. The target will have any embedded "{tokens}" expanded by using token values from the request parameters. If the target has an absolute URI path, that path is used directly after tokenization. If the target begins with "~", that character will be replaced with the route prefix. This is a very convenient way to create application top-level relative links.

If the target is a string that begins with "{AT}" it will be interpreted as a controller/action pair of the form "{AT}controller/action". If the "controller/" portion is absent, the current controller is used. If the action component is missing, the "list" action is used. A bare "{AT}" refers to the "list" action of the current controller.

If the target starts with "{" it is interpreted as being a JSON style set of options that describe the link. If the target is a relative URI path, it is appended to the current request URI path.

If the target is a JSON style of options, it can specify the URI components: scheme, host, port, path, reference and query. If these component properties are supplied, these will be combined to create a URI.

If the target specifies either a controller/action or a JSON set of options, The URI will be created according to the route URI template. The template may be explicitly specified via a "route" target property. Otherwise, if an "action" property is specified, the route of the same name will be used. If these don't result in a usable route, the "default" route will be used.

These are the properties supported in a JSON style "{ ... }" target:

scheme String URI scheme portion
host String URI host portion
port Number URI port number
path String URI path portion
reference String URI path reference. Does not include "#"
query String URI query parameters. Does not include "?"
controller String controller name if using a controller-based route. This can also be specified via the action option.
action String Action to invoke. This can be a URI string or a controller action of the form {AT}controller/action.
route String Route name to use for the URI template

Returns:: A normalized, server-local Uri string.

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

API Stability:: Stable.

See Also:: Esp

EspRoute

EspRoute extended route configuration.

See Also:: Esp

Fields:

MprHash *	actions	Table of actions.
uint	app	Is an esp mvc application.
cchar *	appName	App module name.
uint	combine	Combine C source into a single file.
EspProc	commonController	Common code for all controllers.
uint	compile	Enable recompiling the application or esp page.
cchar *	compileCmd	Compile command template.
uint	compileMode	Compile the application debug or release mode.
cchar *	configFile	Path to config file.
cchar *	currentSession	Current login session when enforcing a single login.
Edi *	edi	Default database for this route.
uint	encodeTypes	Encode data types in JSON API request/response.
MprHash *	env	Environment variables for route.
uint	keep	Keep intermediate source code after compiling.
cchar *	linkCmd	Link command template.
MprTime	loaded	When configuration was last loaded.
HttpRoute *	route	Back link to route.
cchar *	searchPath	Search path to use when locating compiler/linker.
struct EspRoute *	top	Top-level route for this application.
uint	update	Enable dynamically updating the application.
MprHash *	views	Table of views.
cchar *	winsdk	Windows SDK.

void espAction (HttpRoute *route, cchar *targetKey, cchar *abilities, EspProc actionProc)

Define an action.

Description:: Actions are C procedures that are invoked when specific URIs are routed to the controller/action pair. The action will require the specified abilities or roles.

Parameters:

route	HttpRoute object.
targetKey	Target key used to select the action in a HttpRoute target. This is typically a URI prefix.
abilities	String Comma separated list of abilities or roles. If set to the empty string, no specific abilities are required but an authenticated user is required. Set to NULL if an authenticated user is not required.
actionProc	EspProc callback procedure to invoke when the action is requested.

API Stability:: Stable.

See Also:: Esp

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:

Name	Method	Pattern	Target
home	GET,POST,PUT	^/$	index.esp

Parameters:

route

Parent route from which to inherit configuration.

API Stability:: Stable.

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.

Name	Method	Pattern	Target
home	GET,POST,PUT	^/$	index.esp

Parameters:

route	Parent route from which to inherit configuration.
set	Route set to select. Use "vue-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:

route	Parent route object from which to inherit settings when creating the new route.
pattern	URI pattern to use to find the releavant route.
actionProc	EspProc callback procedure to invoke when the action is requested.

API Stability:: Stable.

See Also:: Esp

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:

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

Returns:: Compiled script. Return NULL on errors.

API Stability:: Stable.

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. \n\n "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. \n\n 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. @param route HttpRoute object @param uri URI to cache. If the URI is set to "*" all URIs for that action are uniquely cached. If the request has POST data, the URI may include such post data in a sorted query format. E.g. {uri: /buy?item=scarf&quantity=1}. @param lifesecs Lifespan of cache items in seconds. If not set to positive integer, the lifesecs will default to the route lifespan. @param flags Cache control flags. Select ESP_CACHE_MANUAL to enable manual mode. In manual mode, cached content will not be automatically sent. Use #httpWriteCached in the request handler to write previously cached content. \n\n 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:: Stable.

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:

route	HttpRoute object.
dispatcher	Optional dispatcher to use when waiting for the compilation command.
source	ESP source file name.
module	Output module file name.
cacheName	MD5 cache name. Not a full path.
isView	Set to "true" if the source is a view.
errMsg	Reference to receive an error message if the routine fails.

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

API Stability:: Stable.

See Also:: Esp

void espController (HttpRoute *route, EspProc baseProc)

Define a common controller function to invoke before invoking for all controller actions.

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

Parameters:

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

API Stability:: Stable.

See Also:: Esp

void espDefineBase (HttpRoute *route, EspLegacyProc baseProc)

Define a base controller function to invoke for all controller actions.

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

Parameters:

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

API Stability:: Deprecated.

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:

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

API Stability:: Stable.

See Also:: Esp

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:

route	HttpRoute object.
command	Command to run.
source	ESP web page source pathname.
module	Output module pathname.

Returns:: An expanded command line.

API Stability:: Stable.

See Also:: Esp

cchar * * espGetConfig (HttpRoute *route, cchar *key, cchar *defaultValue)

Get a configuration value from the ESP pak.json.

Parameters:

route	HttpRoute defining the ESP application.
key	Configuration property path. May contain dots.
defaultValue	Default value to use if the configuration is not defined. May be null.

Returns:: The Configuration string value.

API Stability:: Stable.

See Also:: Esp

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:

route	Parent route from which to inherit configuration.
prefix	Optional URI prefix for all application URIs.
path	Pathname to the esp.json file.

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

API Stability:: Stable.

See Also:: Esp

int espLoadCompilerRules (HttpRoute *route)

Load the compiler rules from esp-compile.json.

Parameters:

route

HttpRoute object.

API Stability:: Stable.

See Also:: Esp

int espLoadConfig (HttpRoute *route)

Load configuration for an ESP application.

Description:: Load the application's esp.json and pak.json configuration files.

Parameters:

route

Parent route from which to inherit configuration.

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

API Stability:: Stable.

See Also:: Esp

EspRoute * * espRoute (HttpRoute *route, bool create)

Return the corresponding EspRoute for the given Route.

Description:: Returns the defined EspRoute for the given Route. Creates a new EspRoute if required.

Parameters:

route	Parent route from which to inherit configuration.
create	Set to true to create an EspRoute if a suitable one cannot be found.

Returns:: The EspRoute object.

API Stability:: Stable.

See Also:: Esp

int espSetConfig (HttpRoute *route, cchar *key, cchar *value)

Set a configuration value to the ESP pak.json.

Description:: This updates the in-memory copy of the pak.json only.

Parameters:

route	HttpRoute defining the ESP application.
key	Configuration property path. May contain dots.
value	Value to set the property to.

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

API Stability:: Stable.

See Also:: Esp

bool espTestConfig (HttpRoute *route, cchar *key, cchar *desired)

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

Parameters:

route	HttpRoute defining the ESP application.
key	Configuration property path. May contain dots.
desired	Desired value to compare with.

Returns:: True if the configuration property has the desired value.

API Stability:: Stable.

See Also:: Esp

Functions

EspRoute * * espCreateRoute (HttpRoute *route)

Create an EspRoute object.

Parameters:

route

HttpRoute to associate with.

Returns:: EspRoute object.

int espEmail (HttpStream *stream, cchar *to, cchar *from, cchar *subject, MprTime date, cchar *mime, cchar *message, MprList *files)

Send mail using sendmail.

Parameters:

stream	HttpStream stream object.
to	Message recipient.
from	Message sender.
subject	Message subject.
date	Message creation date. Set to null to use the current date/time.
mime	Message mime type. Set to null for text/plain.
message	Message body.
files	MprList of files to send with the message.

Returns:: Zero if the email is successfully sent.

API Stability:: Stable.

void espInitHtmlOptions (Esp *esp)

Add HTLM internal options to the Esp.options hash.

int espInitParser (void )

Initialize the ESP configuration file parser.

int espOpen (MprModule *module)

ESP initialization entry point.

Parameters:

module

Module object if loaded as an MPR module.

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

API Stability:: Stable.

ssize espRenderFeedback (HttpStream *stream, 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:

stream	Http stream object.
types	Types of feedback message to retrieve. Set to "*" to retrieve all types of feedback. This may be set to any word, but the following feedback types are typically supported as per RFC 5424: "debug", "info", "notice", "warn", "error", "critical".

Returns:: Number of bytes written.

API Stability:: Deprecated.

void espSetData (HttpStream *stream, void *data)

Set a private data reference for the current request.

Parameters:

stream	HttpStream object.
data	Data object to associate with the current request. This must be a managed reference.

Returns:: Reference to private data.

API Stability:: Stable.

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:

entry	ESP initialization function.
appName	Name of the ESP application.
routeName	Name of the route in the appweb.conf file for this ESP application or page.

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

API Stability:: Stable.

Typedefs

typedef void(* EspLegacyProc) (HttpStream *stream).

Procedure callback.

API Stability:: Stable.

typedef void(* EspViewProc) (HttpStream *stream).

View procedure callback.

Parameters:

stream

Http stream object.

API Stability:: Stable.

See Also:: Esp

typedef int(* EspModuleEntry) (struct HttpRoute *route, MprModule *module).

Entry point for a loadable ESP module.

Parameters:

route	HttpRoute object.
module	Mpr module object.

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

API Stability:: Stable.

See Also:: Esp

Esp

Top level ESP structure.

Fields:

int	compileMode	Force a debug compile.
MprHash *	databases	Cloned databases.
MprEvent *	databasesTimer	Database prune timer.
EdiService *	ediService	Database service.
cchar *	hostedDocuments	Documents directory if hosted.
MprHash *	internalOptions	Table of internal HTML control options
int	inUse	Active ESP request counter.
MprThreadLocal *	local	Thread local data.
MprMutex *	mutex	Multithread lock.
int	reloading	Reloading ESP and modules.
MprHash *	vstudioEnv	Visual Studio environment.

EspAction

Action definition.

API Stability:: Stable.

Fields:

cchar *	abilities	Abilities or roles for action. Comma separated.
EspProc	callback	Callback action.
cchar *	target	Route target string.