ESP Native API

Extensions

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

Functions

cchar*	absuri(cchar *target, ...)
	Create an absolute URI with a scheme and host.
void	addHeader(cchar key, cchar fmt, ...)
	Add a header to the transmission using a format string.
void	addParam(cchar name, cchar value)
	Add a request parameter value if not already defined.
bool	canUser(cchar *abilities, bool warn)
	Test if a user has the required abilities.
EdiRec*	createRec(cchar tableName, MprJson data)
	Create a record and initialize field values.
bool	createRecFromParams(cchar *table)
	Create a record from the request parameters.
cchar*	createSession()
	Create a session state object.
void	destroySession()
	Destroy a session state object.
void	dontAutoFinalize()
	Don't auto-finalize this request.
void	espAddHeader(HttpConn conn, cchar key, cchar *fmt, ...)
	Add a header to the transmission using a format string.
void	espAddHeaderString(HttpConn conn, cchar key, cchar *value)
	Add a header to the transmission.
void	espAddHomeRoute(HttpRoute *route)
	Add a route for the home page.
void	espAddPak(HttpRoute route, cchar name, cchar *version)
	Add the specified pak to the pak.json packs list.
void	espAddParam(HttpConn conn, cchar var, cchar *value)
	Add a request parameter value if it is not already defined.
void	espAddRouteSet(HttpRoute route, cchar set)
	Add a route set.
void	espAppendHeader(HttpConn conn, cchar key, cchar *fmt, ...)
	Append a transmission header.
void	espAppendHeaderString(HttpConn conn, cchar key, cchar *value)
	Append a transmission header string.
void	espAutoFinalize(HttpConn *conn)
	Auto-finalize transmission of the http request.
int	espBindProc(HttpRoute route, cchar pattern, void *actionProc)
	Define an action for a URI pattern.
char*	espBuildScript(HttpRoute route, cchar page, cchar path, cchar cacheName, cchar layout, EspState state, char **err)
	Convert an ESP web page into C code.
int	espCache(HttpRoute route, cchar uri, int lifesecs, int flags)
	Add caching for response content.
void	espClearCurrentSession(HttpConn *conn)
	Clear the current authenticated session.
bool	espCompile(HttpRoute route, MprDispatcher dispatcher, cchar source, cchar module, cchar cacheName, int isView, char *errMsg)
	Compile an ESP page, controller or view.
EspRoute*	espCreateRoute(HttpRoute *route)
	Create an EspRoute object.
cchar*	espCreateSession(HttpConn *conn)
	Create a session state object.
void	espDefineAction(HttpRoute route, cchar targetKey, void *actionProc)
	Define an action.
void	espDefineBase(HttpRoute *route, EspProc baseProc)
	Define a base function to invoke for all controller actions.
void	espDefineView(HttpRoute route, cchar path, void *viewProc)
	Define a view.
void	espDestroySession(HttpConn *conn)
	Destroy a session state object.
int	espEmail(HttpConn conn, cchar to, cchar from, cchar subject, MprTime date, cchar mime, cchar message, MprList *files)
	Send mail using sendmail.
char*	espExpandCommand(HttpRoute route, cchar command, cchar source, cchar module)
	Expand a compile or link command template.
void	espFinalize(HttpConn *conn)
	Indicate the request is finalized.
void	espFlush(HttpConn *conn)
	Flush transmit data.
HttpAuth*	espGetAuth()
	Get the current route HttpAuth object.
cchar*	espGetConfig(HttpRoute route, cchar key, cchar *defaultValue)
	Get a configuration value from the ESP pak.json.
HttpConn*	espGetConn()
	Get the current request connection.
MprOff	espGetContentLength(HttpConn *conn)
	Get the receive body content length.
cchar*	espGetContentType(HttpConn *conn)
	Get the receive body content type.
cchar*	espGetCookie(HttpConn conn, cchar name)
	Get a request cookie.
cchar*	espGetCookies(HttpConn *conn)
	Get the request cookies.
void*	espGetData(HttpConn *conn)
	Get the private data reference for the current request set via setData
Edi*	espGetDatabase(HttpConn *conn)
	Get the current database instance.
cchar*	espGetDocuments(HttpConn *conn)
	Get the default documents directory for the request route.
EspRoute*	espGetEspRoute(HttpConn *conn)
	Get the current extended route information.
cchar*	espGetFeedback(HttpConn conn, cchar type)
	Get a feedback message defined via feedback
EdiGrid*	espGetGrid(HttpConn *conn)
	Get the current database grid.
cchar*	espGetHeader(HttpConn conn, cchar key)
	Get an rx http header.
MprHash*	espGetHeaderHash(HttpConn *conn)
	Get the hash table of rx Http headers.
char*	espGetHeaders(HttpConn *conn)
	Get all the request http headers.
int	espGetIntParam(HttpConn conn, cchar var, int defaultValue)
	Get a request pararmeter as an integer.
cchar*	espGetMethod(HttpConn *conn)
	Get the HTTP method.
cchar*	espGetParam(HttpConn conn, cchar var, cchar *defaultValue)
	Get a request parameter.
MprJson*	espGetParams(HttpConn *conn)
	Get the request parameter hash table.
cchar*	espGetPath(HttpConn *conn)
	Get the request URI path string.
cchar*	espGetQueryString(HttpConn *conn)
	Get the request query string.
char*	espGetReferrer(HttpConn *conn)
	Get the referring URI.
HttpRoute*	espGetRoute()
	Get the current route HttpRoute object.
Edi*	espGetRouteDatabase(HttpRoute *route)
	Get the default database defined on a route.
cchar*	espGetRouteVar(HttpConn conn, cchar var)
	Get a route variable.
cchar*	espGetSessionID(HttpConn *conn, int create)
	Get the session state ID.
int	espGetStatus(HttpConn *conn)
	Get the response status.
char*	espGetStatusMessage(HttpConn *conn)
	Get the Http response status message.
MprList*	espGetUploads(HttpConn *conn)
	Get the uploaded files.
cchar*	espGetUri(HttpConn *conn)
	Get the request URI string.
bool	espHasGrid(HttpConn *conn)
	Test if a current grid has been defined.
bool	espHasPak(HttpRoute route, cchar name)
	Test if the ESP application includes the specified pak.
bool	espHasRec(HttpConn *conn)
	Test if a current record has been defined and save to the database.
int	espInit(HttpRoute route, cchar prefix, cchar *path)
	Initialize ESP.
void	espInitHtmlOptions(Esp *esp)
	Add HTLM internal options to the Esp.options hash.
int	espInitParser()
	Initialize the ESP configuration file parser.
bool	espIsCurrentSession(HttpConn *conn)
	Test if the connection is being made on behalf of the current, single authenticated user.
bool	espIsEof(HttpConn *conn)
	Test if the receive input stream is at end-of-file.
bool	espIsFinalized(HttpConn *conn)
	Test if the request has been finalized.
bool	espIsSecure(HttpConn *conn)
	Test if the connection is using SSL and is secure.
int	espLoadCompilerRules(HttpRoute *route)
	Load the compiler rules from esp-compile.json.
int	espLoadConfig(HttpRoute *route)
	Configure an ESP application.
bool	espMatchParam(HttpConn conn, cchar var, cchar *value)
	Match a request parameter with an expected value.
int	espOpen(MprModule *module)
	ESP initialization entry point.
EdiGrid*	espReadTable(HttpConn conn, cchar tableName)
	Read a table from the current database.
ssize	espReceive(HttpConn conn, char buf, ssize size)
	Read receive body content.
void	espRedirect(HttpConn conn, int status, cchar target)
	Redirect the client.
void	espRedirectBack(HttpConn *conn)
	Redirect the client back to the referrer.
void	espRemoveCookie(HttpConn conn, cchar name)
	Remove a cookie.
int	espRemoveHeader(HttpConn conn, cchar key)
	Remove a header from the transmission.
void	espRemoveSessionVar(HttpConn conn, cchar name)
	Remove a session state variable.
ssize	espRender(HttpConn conn, cchar fmt, ...)
	Render a formatted string.
ssize	espRenderBlock(HttpConn conn, cchar buf, ssize size)
	Render a block of data to the client.
ssize	espRenderCached(HttpConn *conn)
	Render cached content.
ssize	espRenderConfig(HttpConn *conn)
	Render the client configuration string in JSON.
void	espRenderDocument(HttpConn conn, cchar path)
	Render an ESP document.
ssize	espRenderError(HttpConn conn, int status, cchar fmt, ...)
	Render an error message back to the client and finalize the request.
ssize	espRenderFeedback(HttpConn conn, cchar types)
	Render feedback messages.
ssize	espRenderFile(HttpConn conn, cchar path)
	Render the contents of a file back to the client.
ssize	espRenderSafe(HttpConn conn, cchar fmt, ...)
	Render a formatted string after HTML escaping.
ssize	espRenderSafeString(HttpConn conn, cchar s)
	Render a safe string of data to the client.
ssize	espRenderString(HttpConn conn, cchar s)
	Render a string of data to the client.
ssize	espRenderVar(HttpConn conn, cchar name)
	Render the value of a request variable to the client.
bool	espRenderView(HttpConn conn, cchar view, int flags)
	Render an ESP view page to the client.
EspRoute*	espRoute(HttpRoute *route, bool create)
	Return the corresponding EspRoute for the given Route.
int	espSaveConfig(HttpRoute *route)
	Save the in-memory ESP pak.json configuration to the default location for the ESP application defined by the specified route.
ssize	espSendGrid(HttpConn conn, EdiGrid grid, int flags)
	Send a database grid as a JSON string.
ssize	espSendRec(HttpConn conn, EdiRec rec, int flags)
	Send a database record as a JSON string.
ssize	espSendResult(HttpConn *conn, bool success)
	Send a JSON response result.
bool	espSetAutoFinalizing(HttpConn *conn, bool on)
	Enable auto-finalizing for this request.
int	espSetConfig(HttpRoute route, cchar key, cchar *value)
	Set a configuration value to the ESP pak.json.
void	espSetConn(HttpConn *conn)
	Set the current request connection.
void	espSetContentLength(HttpConn *conn, MprOff length)
	Define a content length header in the transmission.
void	espSetContentType(HttpConn conn, cchar mimeType)
	Set the transmission (response) content mime type.
void	espSetCookie(HttpConn conn, cchar name, cchar value, cchar path, cchar *domain, MprTicks lifespan, bool isSecure)
	Set a cookie in the transmission.
void	espSetCurrentSession(HttpConn *conn)
	Set this authenticated session as the current session.
void	espSetData(HttpConn conn, void data)
	Set a private data reference for the current request.
void	espSetFeedback(HttpConn conn, cchar type, cchar *fmt, ...)
	Set a feedback message.
void	espSetFeedbackv(HttpConn conn, cchar type, cchar *fmt, va_list args)
	Send a feedback message.
EdiGrid*	espSetGrid(HttpConn conn, EdiGrid grid)
	Set the current database grid.
void	espSetHeader(HttpConn conn, cchar key, cchar *fmt, ...)
	Set a transmission header.
void	espSetHeaderString(HttpConn conn, cchar key, cchar *value)
	Set a simple key/value transmission header.
void	espSetIntParam(HttpConn conn, cchar var, int value)
	Set an integer request parameter value.
void	espSetNotifier(HttpConn *conn, HttpNotifier notifier)
	Define a notifier callback for this connection.
void	espSetParam(HttpConn conn, cchar var, cchar *value)
	Set a request parameter value.
EdiRec*	espSetRec(HttpConn conn, EdiRec rec)
	Set the current database record.
void	espSetStatus(HttpConn *conn, int status)
	Set a Http response status.
void	espShowRequest(HttpConn *conn)
	Show request details.
int	espStaticInitialize(EspModuleEntry entry, cchar appName, cchar routeName)
	Initialize a static library ESP module.
bool	espTestConfig(HttpRoute route, cchar key, cchar *desired)
	Test if a configuration property from the ESP pak.json has a desired value.
void	espUpdateCache(HttpConn conn, cchar uri, cchar *data, int lifesecs)
	Update the cached content for a request.
bool	espUpdateRec(HttpConn conn, EdiRec rec)
	Write a record to the database.
cchar*	espUri(HttpConn conn, cchar target)
	Create a URI.
bool	feedback(cchar type, cchar fmt, ...)
	Set a feedback message.
void	finalize()
	Finalize the response.
void	flush()
	Flush transmit data.
HttpAuth*	getAuth()
	Get the auth object for the current route.
MprList*	getColumns(EdiRec *rec)
	Get a list of column names.
cchar*	getConfig(cchar *field)
	Get a field from the application pak.json configuration.
HttpConn*	getConn()
	Get the connection object.
MprOff	getContentLength()
	Get the receive body content length.
cchar*	getContentType()
	Get the receive body content type.
cchar*	getCookies()
	Get the request cookies.
void*	getData()
	Get the private data reference for the current request set via setData
Edi*	getDatabase()
	Get the current database instance.
MprDispatcher*	getDispatcher()
	Get the connection dispatcher object.
cchar*	getDocuments()
	Get the default document root directory for the request route.
EspRoute*	getEspRoute()
	Get the extended route EspRoute structure.
cchar*	getFeedback(cchar *type)
	Get a feedback message defined via feedback
cchar*	getField(EdiRec rec, cchar field)
	Get a field from the current database record.
cchar*	getFieldError(cchar *field)
	Test if a field in the current record has input validation errors.
EdiGrid*	getGrid()
	Get the current database grid.
cchar*	getHeader(cchar *key)
	Get an rx http header.
cchar*	getMethod()
	Get the HTTP method.
cchar*	getPath()
	Get the request URI path string.
cchar*	getQuery()
	Get the HTTP URI query string.
EdiRec*	getRec()
	Get the current database record.
cchar*	getReferrer()
	Get the referring URI.
EspReq*	getReq()
	Get the ESP request object.
HttpRoute*	getRoute()
	Get the HttpRoute object for the current route.
cchar*	getSecurityToken()
	Get the security token.
cchar*	getSessionID()
	Get the session state ID.
cchar*	getSessionVar(cchar *name)
	Get a session state variable.
MprList*	getUploads()
	Get the uploaded files.
cchar*	getUri()
	Get the request URI string.
bool	hasGrid()
	Test if a current grid has been defined.
bool	hasRec()
	Test if a current record has been defined and save to the database.
void	input(cchar field, cchar options)
	Render an input field as part of a form.
void	inputSecurityToken()
	Render an input field with a hidden XSRF security token.
bool	isEof()
	Test if the receive input stream is at end-of-file.
bool	isFinalized()
	Test if a http request is finalized.
bool	isSecure()
	Test if the connection is using SSL and is secure.
MprHash*	makeHash(cchar *fmt, ...)
	Make a hash table container of property values.
MprJson*	makeJson(cchar *fmt, ...)
	Make a JSON object container of property values.
EdiRec*	makeRec(cchar *content)
	Make a record.
cchar*	makeUri(cchar *target)
	Create a URI.
cchar*	md5(cchar *str)
	Get an MD5 checksum.
bool	modeIs(cchar *check)
	Test the the application mode.
cchar*	nonce()
	Generate a onetime random string.
cchar*	param(cchar *name)
	Get a request parameter.
MprJson*	params()
	Get the request parameter hash table.
EdiRec*	readRec(cchar tableName, cchar key)
	Read the identified record.
EdiRec*	readRecByKey(cchar tableName, cchar key)
	Read a record identified by key value.
EdiRec*	readRecWhere(cchar tableName, cchar fieldName, cchar operation, cchar value)
	Read one record.
EdiGrid*	readTable(cchar *tableName)
	Read all the records in table from the database.
EdiGrid*	readWhere(cchar tableName, cchar fieldName, cchar operation, cchar value)
	Read matching records.
ssize	receive(char *buf, ssize size)
	Read receive body content.
void	redirect(cchar *target)
	Redirect the client.
void	redirectBack()
	Redirect the client back to the referrer.
void	removeCookie(cchar *name)
	Remove a cookie.
bool	removeRec(cchar tableName, cchar key)
	Remove a record from a database table.
void	removeSessionVar(cchar *name)
	Remove a session state variable.
ssize	render(cchar *fmt, ...)
	Render a formatted string.
ssize	renderCached()
	Render cached content.
ssize	renderConfig()
	Render the pak.json.
void	renderError(int status, cchar *fmt, ...)
	Render an error message back to the client and finalize the request.
void	renderFeedback(cchar *types)
	Render feedback messages.
ssize	renderFile(cchar *path)
	Render a file back to the client.
ssize	renderSafe(cchar *fmt, ...)
	Render a formatted string after HTML escaping.
ssize	renderString(cchar *s)
	Render a string of data to the client.
ssize	renderVar(cchar *name)
	Render the value of a request variable to the client.
void	renderView(cchar *view)
	Render an ESP page to the client.
int	runCmd(cchar command, char input, char output, char error, MprTicks timeout, int flags)
	Run a command.
void	scripts(cchar *patterns)
	Render scripts.
void	securityToken()
	Add the security token to the response.
ssize	sendGrid(EdiGrid *grid)
	Send a Edatabase grid as a JSON string.
ssize	sendRec(EdiRec *rec)
	Send a database record as a JSON string.
void	sendResult(bool status)
	Send a JSON response result.
cchar*	session(cchar *name)
	Get a session state variable.
void	setConn(HttpConn *conn)
	Set the current request connection.
void	setContentType(cchar *mimeType)
	Set the transmission (response) content mime type.
void	setCookie(cchar name, cchar value, cchar path, cchar domain, MprTicks lifespan, bool isSecure)
	Define a cookie header to send with the response.
void	setData(void *data)
	Set a private data reference for the current request.
EdiRec*	setField(EdiRec rec, cchar fieldName, cchar *value)
	Update a record field without writing to the database.
EdiRec*	setFields(EdiRec rec, MprJson data)
	Update record fields without writing to the database.
EdiGrid*	setGrid(EdiGrid *grid)
	Set the current database grid.
void	setHeader(cchar key, cchar fmt, ...)
	Set a transmission header.
void	setIntParam(cchar *name, int value)
	Set an integer request parameter value.
void	setNotifier(HttpNotifier notifier)
	Set a notifier callback for the connection.
void	setParam(cchar name, cchar value)
	Set a request parameter value.
EdiRec*	setRec(EdiRec *rec)
	Set the current database record.
void	setSessionVar(cchar name, cchar value)
	Set a session state variable.
void	setStatus(int status)
	Set a Http response status.
void	setTimeout(void proc, MprTicks timeout, void data)
	Create a timeout event.
void	showRequest()
	Show request details.
void	stylesheets(cchar *patterns)
	Render stylesheets.
void	updateCache(cchar uri, cchar data, int lifesecs)
	Update the cached content for a request.
bool	updateField(cchar tableName, cchar key, cchar fieldName, cchar value)
	Write a value to a database table field.
bool	updateFields(cchar tableName, MprJson data)
	Write field values to a database row.
bool	updateRec(EdiRec *rec)
	Write a record to the database.
bool	updateRecFromParams(cchar *table)
	Update a record from the request parameters.
cchar*	uri(cchar *target, ...)
	Create a URI link.

Typedefs

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

Defines

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

EspAbbrev

Abbreviated ESP API.

Description:: This is a short-form API that uses the current HttpConn connection object. These APIs are designed to be terse and highly readable. Consequently, they are not prefixed with "esp".

See Also:

API Stability:: Stable.

Fields:

cchar * absuri (cchar *target, ...)

Create an absolute URI with a scheme and host.

Parameters:

target	The URI target. See httpLink for details.
...	arguments to the formatted target string.

Returns:: A normalized, absolute Uri string containing scheme and host.

API Stability:: Evolving.

See Also:

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

Add a header to the transmission using a format string.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

void addParam (cchar *name, cchar *value)

Add a request parameter value if not already defined.

Parameters:

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

API Stability:: Evolving.

See Also:

bool canUser (cchar *abilities, bool warn)

Test if a user has the required abilities.

Parameters:

abilities	Comma separated list of abilities to test for. If null, then use the required abilities defined for the current request route.
warn	If true, warn the user via sendResult

Returns:: True if the user has all the required abilities.

API Stability:: Prototype.

See Also:

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:

tableName	Database table name.
data	Json 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:

table

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

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

Returns:: True if the request has been successful so far, i.e. there is not an error feedback message defined. Return false if there is an error feedback defined. This permits feedback to be chained as: sendResult(feedback("error", ...));.

API Stability:: Evolving.

See Also:

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:

rec	Database record.

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

API Stability:: Evolving.

See Also:

cchar * getConfig (cchar *field)

Get a field from the application pak.json configuration.

Parameters:

field

Property field name in pak.json. May contain dots.

Returns:: The field value. Returns "" if the field is not found.

API Stability:: Deprecated.

See Also:

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:

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

Returns:: Reference to private data.

API Stability:: Evolving.

See Also:

cchar * getField (EdiRec *rec, cchar *field)

Get a field from the current database record.

Parameters:

rec	Database record.
field	Field name to return.

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

API Stability:: Evolving.

See Also:

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:

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

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

API Stability:: Evolving.

See Also:

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:

name	Variable 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:

field	Name for the input field. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form current record. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
options	These are in JSON string form and are converted to attributes to pass to the input element noescape Boolean Do not HTML escape the text before rendering. ... Other options are converted and rendered as HTML attributes.

API Stability:: Evolving.

See Also:

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:

fmt	Printf 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:

fmt	Printf 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:

content

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

Returns:: An EdiRec instance.

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

API Stability:: Evolving.

See Also:

cchar * md5 (cchar *str)

Get an MD5 checksum.

Parameters:

str	String 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 "profile" property in the pak.json.

Parameters:

check

Mode to compare with the current application mode.

Returns:: True if the current app mode matches the check mode.

API Stability:: Prototype.

See Also:

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:

name	Name of the request parameter to retrieve.

Returns:: String containing the request parameter's value. Caller should not free. Returns NULL if the parameter is not defined.

API Stability:: Evolving.

See Also:

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:

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

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

API Stability:: Evolving.

See Also:

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:

tableName	Database table name.
key	Key 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:

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

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

API Stability:: Evolving.

See Also:

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:

tableName

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

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

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

API Stability:: Evolving.

See Also:

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:

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

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

API Stability:: Evolving.

See Also:

void redirect (cchar *target)

Redirect the client.

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

Parameters:

target

New target uri for the client.

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:

name	Cookie 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:

tableName	Database table name.
key	Key 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:

name	Variable 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:

fmt	Printf 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 pak.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:

status	Http status code.
fmt	Printf 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:

types

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

API Stability:: Evolving.

See Also:

ssize renderFile (cchar *path)

Render a file back to the client.

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

Parameters:

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

Returns:: A count of the bytes actually written.

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:

fmt	Printf 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:

s	String 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:

name	Form 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:

view	View name. The view name is interpreted relative to the matching route documents directory and may omit an ESP extension.

API Stability:: Evolving.

See Also:

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:

command	Command line and arguments to run.
input	Input data to pass to the command. Set to null if not required.
output	Pointer to accept command standard output response. Set to null if not required.
error	Pointer to accept command standard error response. Set to null if not required.
flags	MprCmd flags. Use MPR_CMD_DETACH to run in the background.
timeout	Time in milliseconds to wait for the command to complete and exit.

API Stability:: Prototype.

See Also:

void scripts (cchar *patterns)

Render scripts.

Description:: This renders script elements for all matching filenames on the server.

Parameters:

patterns

An enhanced glob-style expression pattern. The format is is a comma separated string of filename expressions. Each expression may contain the wildcard tokens: "*" which matches any filename portion, "**" which matches any filename portion in any subdirectory. An expression may be prefixed with "!" to exclude files of that expression.

API Stability:: Deprecated.

See Also:

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:

name	Variable 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:

conn	The 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:

mimeType

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

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

API Stability:: Evolving.

See Also:

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:

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

Returns:: The record instance if successful, otherwise NULL.

API Stability:: Evolving.

See Also:

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:

rec	Record to update.
data	Json 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:

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

API Stability:: Evolving.

See Also:

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:

name	Name of the request parameter to set.
value	Integer 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:

notifier

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

name	Name of the request parameter to set.
value	Value 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:

name	Variable name to set.
value	Value 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:

status

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

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

API Stability:: Evolving.

See Also:

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:

patterns

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:

uri	Request URI to cache for.
data	Data to cache.
lifesecs	Time 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:

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

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

API Stability:: Evolving.

See Also:

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:

tableName	Database table name.
data	Json object of fields to update.

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

API Stability:: Evolving.

See Also:

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:

rec	Record 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:

table

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

target

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

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

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

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

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

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

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

...

arguments to the formatted target string.

Returns:: A normalized Uri string.

API Stability:: Evolving.

Remarks:

Examples:

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

See Also:

EspParse

ESP page parser structure.

See Also:: Esp

EspReq

ESP request structure.

API Stability:: Internal.

See Also:: Esp

Fields:

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

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

Add a header to the transmission using a format string.

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

Parameters:

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

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

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:

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

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

API Stability:: Stable.

See Also:: Esp

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

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

Parameters:

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

API Stability:: Stable.

See Also:: Esp

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

Append a transmission header.

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

Parameters:

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

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:

conn	HttpConn connection object.
key	Http response header key.
value	Value 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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn connection object.

API Stability:: Stable.

See Also:: Esp

void espFlush (HttpConn *conn)

Flush transmit data.

Description:: This writes any buffered data.

Parameters:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn connection object.
name	Cookie name to retrieve.

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

API Stability:: Stable.

See Also:: Esp

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:

conn	HttpConn connection object.

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

API Stability:: Stable.

See Also:: Esp

void * espGetData (HttpConn *conn)

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

Parameters:

conn	HttpConn 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:

conn	HttpConn 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:

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

Returns:: Reference to the feedback message.

API Stability:: Evolving.

See Also:: Esp

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:

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

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

API Stability:: Stable.

See Also:: Esp

MprHash * espGetHeaderHash (HttpConn *conn)

Get the hash table of rx Http headers.

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

Parameters:

conn	HttpConn connection object.

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

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:

conn	HttpConn 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:

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

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

API Stability:: Evolving.

See Also:: Esp

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:

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

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

API Stability:: Stable.

See Also:: Esp

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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn connection object.

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

API Stability:: Stable.

See Also:: Esp

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:

route

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

conn	HttpConn connection object.
var	Name of the request parameter to retrieve.

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

API Stability:: Evolving.

See Also:: Esp

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:

conn	HttpConn connection object.
create	Set to true to create a new session if one does not already exist.

Returns:: The session state identifier string.

API Stability:: Evolving.

See Also:: Esp

int espGetStatus (HttpConn *conn)

Get the response status.

Parameters:

conn	HttpConn connection object.

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

API Stability:: Stable.

See Also:: Esp

char * espGetStatusMessage (HttpConn *conn)

Get the Http response status message.

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

Parameters:

conn	HttpConn connection object.

Returns:: A Http status message.

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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	HttpConn 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:

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

Returns:: "True" if the value matches.

API Stability:: Stable.

See Also:: Esp

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

Read a table from the current database.

Parameters:

conn	HttpConn connection object.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:: Esp

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:

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

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

API Stability:: Stable.

See Also:: Esp

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

Redirect the client.

Description:: Redirect the client to a new uri.

Parameters:

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

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:

conn	HttpConn connection object.

API Stability:: Stable.

See Also:: Esp

void espRemoveCookie (HttpConn *conn, cchar *name)

Remove a cookie.

Parameters:

conn	HttpConn connection object.
name	Cookie 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:

conn	HttpConn connection object.
key	Http response header key.

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

API Stability:: Stable.

See Also:: Esp

void espRemoveSessionVar (HttpConn *conn, cchar *name)

Remove a session state variable.

Parameters:

conn	HttpConn connection object.
name	Variable 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:

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

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

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

Render a block of data to the client.

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

Parameters:

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

Returns:: A count of the bytes actually written.

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:

conn	HttpConn 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:

conn	HttpConn 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:

conn	Http connection object.
path	Relative 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:

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

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderFile (HttpConn *conn, cchar *path)

Render the contents of a file back to the client.

Parameters:

conn	HttpConn connection object.
path	File path name.

Returns:: A count of the bytes actually written.

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:

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

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

ssize espRenderSafeString (HttpConn *conn, cchar *s)

Render a safe string of data to the client.

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

Parameters:

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

Returns:: A count of the bytes actually written.

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:

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

Returns:: A count of the bytes actually written.

API Stability:: Stable.

See Also:: Esp

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:

conn	HttpConn connection object.
name	Form 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:

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

Returns:: True if a vew can be rendered.

API Stability:: Evolving.

See Also:: Esp

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:

conn	HttpConn connection object.
grid	EDI grid.
flags	Reserved. 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:

conn	HttpConn connection object.
rec	EDI record.
flags	Reserved. 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:

conn	HttpConn connection object.
success	True 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:

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

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

API Stability:: Stable.

See Also:: Esp

void espSetConn (HttpConn *conn)

Set the current request connection.

Parameters:

conn	The 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:

conn	HttpConn connection object.
length	Numeric 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:

conn	HttpConn connection object.
mimeType	Mime 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:

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

API Stability:: Stable.

See Also:: Esp

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:

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

API Stability:: Stable.

See Also:: Esp

void espSetFeedbackv (HttpConn *conn, cchar *type, cchar *fmt, va_list args)

Send a feedback message.

Parameters:

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

API Stability:: Internal.

See Also:: Esp

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:

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

API Stability:: Stable.

See Also:: Esp

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

Set a simple key/value transmission header.

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

Parameters:

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

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:

conn	HttpConn connection object.
var	Name of the request parameter to set.
value	Value 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:

conn	HttpConn connection object created via httpCreateConn
notifier	Notifier 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:

conn	HttpConn connection object.
var	Name of the request parameter to set.
value	Value 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:

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

Returns:: The grid instance. This permits chaining.

API Stability:: Stable.

See Also:: Esp

void espSetStatus (HttpConn *conn, int status)

Set a Http response status.

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

Parameters:

conn	HttpConn connection object.
status	Http status code.

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:

conn	HttpConn 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:

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

API Stability:: Stable.

See Also:: Esp

bool espUpdateRec (HttpConn *conn, EdiRec *rec)

Write a record to the database.

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

Parameters:

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

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

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:

conn

HttpConn connection object.

target

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

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

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

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

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

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

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

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

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

API Stability:: Evolving.

See Also:: Esp

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:

target

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

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

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

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

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

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

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

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

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

API Stability:: Evolving.

See Also:: Esp

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:

grid

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

rec	EDI 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:

status

Request success status. Note: this is not the HTTP response status code.

API Stability:: Evolving.

See Also:: Esp

EspRoute

EspRoute extended route configuration.

See Also:: Esp

Fields:

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

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:: Evolving.

See Also:: Esp

void espAddPak (HttpRoute *route, cchar *name, cchar *version)

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

Parameters:

route	HttpRoute defining the ESP application.
name	Desired pak name. For example: "angular-mvc".
version	Pack version string.

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

API Stability:: Prototype.

See Also:: Esp

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

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

route	HttpRoute object.
uri	URI to cache. If the URI is set to "*" all URIs for that action are uniquely cached. If the request has POST data, the URI may include such post data in a sorted query format. E.g. {uri: /buy?item=scarf&quantity=1}.
lifesecs	Lifespan of cache items in seconds. If not set to positive integer, the lifesecs will default to the route lifespan.
flags	Cache control flags. Select ESP_CACHE_MANUAL to enable manual mode. In manual mode, cached content will not be automatically sent. Use httpWriteCached in the request handler to write previously cached content. Select ESP_CACHE_CLIENT to enable client-side caching. In this mode a "Cache-Control" Http header will be sent to the client with the caching "max-age". WARNING: the client will not send any request for this URI until the max-age timeout has expired. Select HTTP_CACHE_RESET to first reset existing caching configuration for this route. Select HTTP_CACHE_COMBINED, HTTP_CACHE_ONLY or HTTP_CACHE_UNIQUE to define the server-side caching mode. Only one of these three mode flags should be specified. If the HTTP_CACHE_COMBINED flag is set, the request params (query, post data and route parameters) will be ignored and all request for a given URI path will cache to the same cache record. Select HTTP_CACHE_UNIQUE to uniquely cache requests with different request parameters. The URIs specified in uris should not contain any request parameters. Select HTTP_CACHE_ONLY to cache only the exact URI with parameters specified in uris. The parameters must be in sorted www-urlencoded format. For example: /example.esp?hobby=sailing&name=john.

Returns:: A count of the bytes actually written.

API Stability:: Evolving.

See Also:: Esp

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

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

API Stability:: Stable.

See Also:: Esp

void espDefineBase (HttpRoute *route, EspProc baseProc)

Define a base function to invoke for all controller actions.

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

Parameters:

route	HttpRoute object.
baseProc	Function 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:

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	Http connection object.
source	ESP web page source pathname.
module	Output 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 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

bool espHasPak (HttpRoute *route, cchar *name)

Test if the ESP application includes the specified pak.

Description:: This tests the dependencies property specified pak.

Parameters:

route	HttpRoute defining the ESP application.
name	Desired pak name. For example: "angular-mvc".

Returns:: True if the specified pak is supported.

API Stability:: Prototype.

See Also:: Esp

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:: Prototype.

See Also:: Esp

int espLoadCompilerRules (HttpRoute *route)

Load the compiler rules from esp-compile.json.

Parameters:

route

HttpRoute object.

API Stability:: Prototype.

See Also:: Esp

int espLoadConfig (HttpRoute *route)

Configure an ESP application.

Description:: Load the esp.json and pak.json configuration files.

Parameters:

route

Parent route from which to inherit configuration.

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

API Stability:: Prototype.

See Also:: Esp

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:: Prototype.

Parameters:

route

See Also:: Esp

int espSaveConfig (HttpRoute *route)

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

Parameters:

route

HttpRoute 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 pak.json.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: Esp

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:: Evolving.

See Also:: Esp

Functions

EspRoute * espCreateRoute (HttpRoute *route)

Create an EspRoute object.

Parameters:

route

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

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

Returns:: Zero if the email is successfully sent.

API Stability:: Evolving.

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:

module

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

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

Returns:: Number of bytes written.

API Stability:: Deprecated.

void espSetData (HttpConn *conn, void *data)

Set a private data reference for the current request.

Parameters:

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

Returns:: Reference to private data.

API Stability:: Prototype.

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

conn	Http connection 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.