APPWEB - ESP API Native API

Components

Edi	Database structure.
EdiField	EDI Record field structure.
EdiGrid	Grid structure.
EdiRec	Database record structure.
EdiService	Edi service control structure.
EspAbbrev	Abbreviated ESP Controls.
EspControl	Suite of high-level controls that generate dynamic HTML5.
EspParse	ESP page parser structure.
EspReq	ESP request structure.
EspRoute	EspRoute extended route configuration.

Functions

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

Typedefs

EdiProvider	Database provider interface.
EdiValidation	Validation structure.
EdiValidationProc	Field validation callback procedure.
Esp	Top level ESP structure.
EspAction	ESP Action.
EspModuleEntry	Entry point for a loadable ESP module.
EspProc	Procedure callback.
EspViewProc	View procedure callback.

Defines

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

Edi

Database structure.

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

Fields:

EdiMigration	back	Backward migration callback.
char *	errMsg	Last error message.
int	flags	Database flags.
EdiMigration	forw	Forward migration callback.
cchar *	path	Database path.
struct EdiProvider *	provider	Database provider.

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

Add a column to a table.

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Add an index to a table.

Parameters:

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

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

API Stability:: Evolving.

See Also:

int ediAddTable (Edi *edi, cchar *tableName)

Add a table to a database.

Parameters:

edi	Database handle.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:

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

Add a validation.

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

Parameters:

edi	Database handle.
name	Validation name. Select from: boolean to validate field data as "true" or "false" date to validate field data as a date or time. format to validate field data against a regular expression supplied in the "data" argument integer to validate field data as an integral value number to validate field data as a number. It may be an integer or floating point number. present to validate field data as not null. unique to validate field data as being unique in the database table.
tableName	Database table name.
columnName	Database column name.
data	Argument data for the validator. For example: the "format" validator requires a regular expression.

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

API Stability:: Evolving.

See Also:

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

Change a column schema definition.

Parameters:

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

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

API Stability:: Evolving.

See Also:

void ediClose (Edi *edi)

Close a database.

Parameters:

edi	Database handle.

API Stability:: Evolving.

See Also:

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

Create a bare grid.

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

Parameters:

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

Returns:: EdiGrid instance.

API Stability:: Evolving.

See Also:

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

Create a bare record.

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

Parameters:

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

Returns:: EdiGrid instance.

API Stability:: Evolving.

See Also:

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

Create a record.

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

Parameters:

edi	Database handle.
tableName	Database table name.

Returns:: Record instance.

API Stability:: Evolving.

See Also:

int ediDelete (Edi *edi, cchar *path)

Delete the database at the given path.

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Delete a row in a database table.

Parameters:

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

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

API Stability:: Evolving.

See Also:

cchar * ediFormatField (cchar *fmt, EdiField *fp)

Format a field value.

Parameters:

fmt	Printf style format string.
fp	Field whoes value will be formatted.

Returns:: Formatted value string.

API Stability:: Evolving.

See Also:

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

Get a list of column names.

Parameters:

edi	Database handle.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:

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

Get the column schema.

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Get and format a record field value.

Parameters:

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

Returns:: String value of the field.

API Stability:: Evolving.

See Also:

EdiField ediGetFieldSchema (EdiRec *rec, cchar *fieldName)

Get the record field schema.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

int ediGetFieldType (EdiRec *rec, cchar *fieldName)

Get the data type of a record field.

Parameters:

rec	Record to examine.
fieldName	Field to examine.

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

API Stability:: Evolving.

See Also:

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

Get a record field.

Parameters:

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

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

API Stability:: Evolving.

See Also:

MprList * ediGetGridColumns (EdiGrid *grid)

Get a list of grid column names.

Parameters:

grid	Database grid.

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

API Stability:: Evolving.

See Also:

MprList * ediGetRecErrors (EdiRec *rec)

Get record validation errors.

Parameters:

rec	Database record.

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

API Stability:: Evolving.

See Also:

MprList * ediGetTables (Edi *edi)

Get a list of database tables.

Parameters:

edi	Database handle.

Returns:: An MprList of table names in the database.

API Stability:: Evolving.

See Also:

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

Get table schema information.

Parameters:

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

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

API Stability:: Evolving.

See Also:

char * ediGetTypeString (int type)

Convert an EDI type to a string.

Parameters:

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

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

API Stability:: Evolving.

See Also:

EdiGrid * ediJoin (Edi *edi, ...)

Join grids.

Parameters:

edi	Database handle.
...	Null terminated list of data grids. These are instances of EdiGrid.

Returns:: A joined grid.

API Stability:: Evolving.

See Also:

int ediLoad (Edi *edi, cchar *path)

MOB - remove this API Load the database file.

Parameters:

edi	Database handle.
path	Database path name.

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

API Stability:: Evolving.

See Also:

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

Lookup a field by name.

Parameters:

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

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

API Stability:: Evolving.

See Also:

EdiProvider * ediLookupProvider (cchar *providerName)

Lookup an EDI provider name.

Parameters:

providerName

Name of the EDI provider.

Returns:: The EDI provider object.

API Stability:: Evolving.

See Also:

EdiGrid * ediMakeGrid (cchar *content)

Make a grid.

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

Parameters:

content

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

Returns:: An EdiGrid instance.

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

API Stability:: Evolving.

See Also:

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

Make a hash container of property values.

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

Parameters:

fmt	Printf style format string.
...	arguments.

Returns:: MprHash instance.

API Stability:: Evolving.

See Also:

EdiRec * ediMakeRec (cchar *content)

Make a record.

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

Parameters:

content

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

Returns:: An EdiRec instance.

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

API Stability:: Evolving.

See Also:

void ediManageEdiRec (EdiRec *rec, int flags)

Manage an EdiRec instance for garbage collection.

Parameters:

rec	Record instance.
flags	GC management flag.

API Stability:: Evolving.

See Also:

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

Open a database.

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

Parameters:

source	Database path name. If using the "mdb" provider with the EDI_LITERAL flag, then the source argument can be set to a literal JSON database content string.
provider	Database provider. Set to "mdb" for the Memory Database or "sqlite" for the SQLite provider.
flags	Set to: EDI_CREATE Create database if not present. EDI_AUTO_SAVE Auto-save database if modified in memory. This option is only supported by the "mdb" provider. EDI_NO_SAVE Prevent saving to disk. This option is only supported by the "mdb" provider. EDI_LITERAL Literal schema in ediOpen source parameter. This option is only supported by the "mdb" provider.

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

API Stability:: Evolving.

See Also:

int ediParseTypeString (cchar *type)

Parse an EDI type string.

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Run a query.

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

Parameters:

edi	Database handle.
cmd	Query command to execute.

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

API Stability:: Evolving.

See Also:

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

Read a field from the database and format the result.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Read one record.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Read a field from the database.

Description:: This reads a field from the database.

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Read a record.

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

Parameters:

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

Returns:: Record instance of EdiRec.

API Stability:: Evolving.

See Also:

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

Read a table.

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

Parameters:

edi	Database handle.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:

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

Read matching records.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Remove a table index.

Parameters:

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

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

API Stability:: Evolving.

See Also:

int ediRemoveTable (Edi *edi, cchar *tableName)

Remove a table from the database.

Parameters:

edi	Database handle.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:

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

Rename a column.

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Rename a table.

Parameters:

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

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

API Stability:: Evolving.

See Also:

int ediSave (Edi *edi)

Save in-memory database contents to disk.

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

Parameters:

edi	Database handle.

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

API Stability:: Evolving.

See Also:

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

Set a record field without writing to the database.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Set record fields without writing to the database.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

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

Write a value to a database table field.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

int ediUpdateRec (Edi *edi, EdiRec *rec)

Write a record to the database.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:

bool ediValidateRec (EdiRec *rec)

Validate a record.

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

Parameters:

rec	Record to validate.

Returns:: True if all field valiations pass.

API Stability:: Evolving.

See Also:

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

Remove a column from a table.

Parameters:

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

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

API Stability:: Evolving.

See Also:

EdiField

EDI Record field structure.

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

Fields:

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

EdiGrid

Grid structure.

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

Fields:

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

EdiGrid * ediPivotGrid (EdiGrid *grid, int flags)

Pivot a grid swapping rows for columns.

Parameters:

grid	Source grid.
flags	Control flags. Set to EDI_PIVOT_FIELD_NAMES to use field names as the first column of data.

Returns:: New pivoted grid.

API Stability:: Evolving.

See Also:

EdiRec

Database record structure.

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

Fields:

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

EdiService

Edi service control structure.

Fields:

void ediAddProvider (struct EdiProvider *provider)

Add a database provider.

Description:: This should only be called by database providers.

API Stability:: Evolving.

See Also:

EdiService * ediCreateService ()

Create the EDI service.

Returns:: EdiService object.

API Stability:: Evolving.

See Also:

void ediDefineMigration (struct Edi *edi, EdiMigration forw, EdiMigration back)

Define migration callbacks.

Parameters:

edi	Database handle.
forw	Forward migration callback. Of the form: int forw(Edi *edit); A successful return should be zero.
back	Backward migration callback. Of the form: int back(Edi *edit); A successful return should be zero.

API Stability:: Evolving.

See Also:

void ediDefineValidation (cchar *name, EdiValidationProc vfn)

Define a field validation procedure.

Parameters:

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

API Stability:: Evolving.

See Also:

EspAbbrev

Abbreviated ESP Controls.

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

API Stability:: Prototype.

See Also:: espAlert

API Stability:: Evolving.

Fields:

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

Add a header to the transmission using a format string.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

void alert (cchar *text, cchar *options)

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Render an HTML anchor link.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Render an HTML button to use inside a form.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Render an HTML button to use outside a form.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void chart (EdiGrid *grid, cchar *options)

Render a graphic chart.

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

Parameters:

grid

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

options

Extra options. See EspControl for a list of the standard options.

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

API Stability:: Evolving.

See Also:: espAlert

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

Render an input checkbox.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Create a record and initialize field values.

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

Parameters:

tableName	Database table name.
data	Hash of field values.

Returns:: EdRec instance.

API Stability:: Evolving.

See Also:: espAlert

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

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

void division (cchar *body, cchar *options)

Render an HTML division.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void dontAutoFinalize ()

Don't auto-finalize this request.

API Stability:: Evolving.

See Also:: espAlert

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

Render a dropdown selection list.

Parameters:

field	Record field name to provide the default value for the list. The field should be a property of the form current record. The field name is used to create the HTML input control name. If this call is used without a form control record, the actual data value should be supplied via the options.value property.
choices	Choices to select from. This is a EdiGrid object. For example: espDropdown(conn, "priority", makeGrid("[{ id: 0, low: 0}, { id: 1, med: 1}, {id: 2, high: 2}]"), 0) espDropdown(conn, "priority", makeGrid("[{low: 0}, {med: 1}, {high: 2}]"), 0) espDropdown(conn, "priority", makeGrid("[{'low'}, {'med'}, {'high'}]"), 0) espDropdown(conn, "priority", makeGrid("[0, 10, 100]"), 0).
options	Extra options. See EspControl for a list of the standard options.

API Stability:: Evolving.

See Also:: espAlert

void finalize ()

Finalize the response.

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

API Stability:: Evolving.

See Also:: espAlert

void flash (cchar *kinds, cchar *options)

Render flash notices.

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

Parameters:

kinds	Space separated list of flash messages types. Typical types are: "error", "inform", "warning".
options	Extra options. See EspControl for a list of the standard options. retain Number of seconds to retain the message. If <= 0, the message is retained until another message is displayed. Default is 0. MOB - this default implies it is displayed for zero seconds

API Stability:: Evolving.

See Also:: espAlert

void flush ()

Flush transmit data.

Description:: This writes any buffered data.

API Stability:: Evolving.

See Also:: espAlert

void form (void *record, cchar *options)

Render an HTML form.

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

Parameters:

record

Record to use by default to supply form field names and values. If NULL, use the default record.

options

Extra options. See EspControl for a list of the standard options.

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

API Stability:: Evolving.

See Also:: espAlert

MprList * getColumns (EdiRec *rec)

Get a list of column names.

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

HttpConn * getConn ()

Get the connection object.

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

Returns:: HttpConn connection instance object.

API Stability:: Evolving.

See Also:: espAlert

MprOff getContentLength ()

Get the receive body content length.

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

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

API Stability:: Evolving.

See Also:: espAlert

cchar * getContentType ()

Get the receive body content type.

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

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

API Stability:: Evolving.

See Also:: espAlert

cchar * getCookies ()

Get the request cookies.

Description:: Get the cookies defined in the current request.

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

API Stability:: Evolving.

See Also:: espAlert

Edi * getDatabase ()

Get the current database instance.

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

Returns:: Edi EDI database handle.

API Stability:: Evolving.

See Also:: espAlert

cchar * getDir ()

Get the default document root directory for the request route.

Returns:: A directory path name.

API Stability:: Evolving.

See Also:: espAlert

EspRoute * getEspRoute ()

Get the extended route EspRoute structure.

Returns:: EspRoute instance.

API Stability:: Evolving.

See Also:: espAlert

cchar * getField (cchar *field)

Get a field from the current database record.

Description:: The current grid is defined via setRec

Parameters:

field

Field name to return.

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

API Stability:: Evolving.

See Also:: espAlert

EdiGrid * getGrid ()

Get the current database grid.

Description:: The current grid is defined via setGrid

Returns:: EdiGrid instance.

API Stability:: Evolving.

See Also:: espAlert

cchar * getHeader (cchar *key)

Get an rx http header.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

cchar * getQuery ()

Get the HTTP URI query string.

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

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

API Stability:: Evolving.

See Also:: espAlert

EdiRec * getRec ()

Get the current database record.

Description:: The current record is defined via setRec

Returns:: EdiRec instance.

API Stability:: Evolving.

See Also:: espAlert

cchar * getReferrer ()

Get the referring URI.

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

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

API Stability:: Evolving.

See Also:: espAlert

cchar * getSessionVar (cchar *name)

Get a session state variable.

Description:: See also httpGetSessionVar and httpGetSessionObj for alternate ways to retrieve session data.

Parameters:

name	Variable name to get.

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

API Stability:: Evolving.

See Also:: espAlert

cchar * getTop ()

Get a relative URI to the top of the application.

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

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

API Stability:: Evolving.

See Also:: espAlert

MprHash * getUploads ()

Get the uploaded files.

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

Returns:: A hash of HttpUploadFile objects.

API Stability:: Evolving.

See Also:: espAlert

cchar * getUri ()

Get the request URI string.

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

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

API Stability:: Evolving.

See Also:: espAlert

bool hasGrid ()

Test if a current grid has been defined.

Description:: The current grid is defined via setRec

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

API Stability:: Evolving.

See Also:: espAlert

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

void icon (cchar *uri, cchar *options)

Render an HTML icon.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void image (cchar *uri, cchar *options)

Render an HTML image.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void inform (cchar *fmt, ...)

Set an informational flash notification message.

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

Parameters:

fmt	Printf style message format.

API Stability:: Evolving.

See Also:: espAlert

void input (cchar *field, cchar *options)

Render an input field as part of a form.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

bool isEof ()

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

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

API Stability:: Evolving.

See Also:: espAlert

bool isFinalized ()

Test if a http request is finalized.

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

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

API Stability:: Evolving.

See Also:: espAlert

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

void label (cchar *text, cchar *options)

Render a text label field.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Render a mail link.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

EdiGrid * makeGrid (cchar *content)

Make a grid.

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

Parameters:

content

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

Returns:: An EdiGrid instance.

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

API Stability:: Evolving.

See Also:: espAlert

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

Make a hash table container of property values.

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

Parameters:

fmt	Printf style format string.
...	arguments.

Returns:: MprHash instance.

API Stability:: Evolving.

See Also:: espAlert

EdiRec * makeRec (cchar *content)

Make a record.

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

Parameters:

content

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

Returns:: An EdiRec instance.

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

API Stability:: Evolving.

See Also:: espAlert

void notice (cchar *fmt, ...)

Set an error flash notification message.

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

Parameters:

fmt	Printf style message format.

API Stability:: Evolving.

See Also:: espAlert

cchar * param (cchar *name)

Get a request parameter.

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

Parameters:

name	Name of the request parameter to retrieve.

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

API Stability:: Evolving.

See Also:: espAlert

MprHash * params ()

Get the request parameter hash table.

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

Returns:: MprHash instance containing the request parameters.

API Stability:: Evolving.

See Also:: espAlert

bool pmatch (cchar *key)

Match the request parameter against a field of the same name in the current record.

Returns:: True if the param matches the field.

API Stability:: Prototype.

See Also:: espAlert

void progress (cchar *progress, cchar *options)

Emit a progress bar.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Render a radio button.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

EdiRec * readRec (cchar *tableName)

Read the identified record.

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

Parameters:

tableName

Database table name.

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

API Stability:: Evolving.

See Also:: espAlert

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

Read a record identified by key value.

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

Parameters:

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

Returns:: Record instance of EdiRec.

API Stability:: Evolving.

See Also:: espAlert

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

Read matching records.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

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

Read one record.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

EdiGrid * readTable (cchar *tableName)

Read all the records in table from the database.

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

Parameters:

tableName

Database table name.

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

API Stability:: Evolving.

See Also:: espAlert

ssize receive (char *buf, ssize size)

Read receive body content.

Description:: Read body content from the client.

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

void redirect (cchar *target)

Redirect the client.

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

Parameters:

target

New target uri for the client.

API Stability:: Evolving.

See Also:: espAlert

void redirectBack ()

Redirect the client back to the referrer.

Description:: Redirect the client to the referring URI.

API Stability:: Evolving.

See Also:: espAlert

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

Control the refresh of web page dynamic elements.

Parameters:

on	URI to invoke when turning "on" refresh.
off	URI to invoke when turning "off" refresh.
options	Extra options. See EspControl for a list of the standard options. minified Set to "ture" to select a minified (compressed) version of the script.

API Stability:: Evolving.

See Also:: espAlert

bool removeRec (cchar *tableName, cchar *key)

Remove a record from a database table.

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

Parameters:

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

Returns:: Record instance of EdiRec.

API Stability:: Evolving.

See Also:: espAlert

ssize render (cchar *fmt, ...)

Render a formatted string.

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

Parameters:

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

Returns:: A count of the bytes actually written.

API Stability:: Evolving.

See Also:: espAlert

ssize renderCached ()

Render cached content.

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

Returns:: A count of the bytes actually written.

API Stability:: Evolving.

See Also:: espAlert

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

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

The output is Html escaped for security

Parameters:

status	Http status code.
fmt	Printf style message format.

Returns:: A count of the bytes actually written.

API Stability:: Evolving.

See Also:: espAlert

ssize renderFile (cchar *path)

Render a file back to the client.

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

Parameters:

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

Returns:: A count of the bytes actually written.

API Stability:: Evolving.

See Also:: espAlert

ssize renderSafe (cchar *fmt, ...)

Render a formatted string after HTML escaping.

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

Parameters:

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

Returns:: A count of the bytes actually written.

API Stability:: Evolving.

See Also:: espAlert

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

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

void renderView (cchar *view)

Render a view template to the client.

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

Parameters:

view	view name.

API Stability:: Evolving.

See Also:: espAlert

void script (cchar *uri, cchar *options)

Render a script link.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void securityToken ()

Generate a security token.

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

API Stability:: Evolving.

See Also:: espAlert

void setConn (HttpConn *conn)

Set the current request connection.

Parameters:

conn	The HttpConn connection object to define.

API Stability:: Evolving.

See Also:: espAlert

void setContentType (cchar *mimeType)

Set the transmission (response) content mime type.

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

Parameters:

mimeType

Mime type string.

API Stability:: Evolving.

See Also:: espAlert

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. (MOB units?).
isSecure	Boolean Set to "true" if the cookie only applies for SSL based connections.

API Stability:: Evolving.

See Also:: espAlert

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

Update a record field without writing to the database.

Description:: This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use 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:: espAlert

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

Update record fields without writing to the database.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

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

Set a flash notification message.

Description:: Flash messages persist for only one request and are a convenient way to pass state information or feedback messages to the next request. Flash messages use the session state store, but persist only for one request. This routine calls espSetFlash

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

EdiGrid * setGrid (EdiGrid *grid)

Set the current database grid.

Returns:: The grid instance. This permits chaining.

API Stability:: Evolving.

See Also:: espAlert

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

Set a transmission header.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

void setParam (cchar *name, cchar *value)

Set a request parameter value.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

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

void setStatus (int status)

Set a Http response status.

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

Parameters:

status

Http status code.

API Stability:: Evolving.

See Also:: espAlert

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

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

void stylesheet (cchar *uri, cchar *options)

Render a stylesheet link.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void table (EdiGrid *grid, cchar *options)

Render a table.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

void tabs (EdiRec *rec, cchar *options)

Render a tab control.

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

Parameters:

rec	Tab data for the control. Tab data is a single object where the tab text is the property key and the target to invoke is the property value.
options	Optional extra options. See EspControl for a list of the standard options. click Set to "true" to invoke the selected pane via a foreground click. remote Set to "true" to invoke the selected pane via a background click. toggle Set to "true" to show the selected pane and hide other panes.

API Stability:: Evolving.

See Also:: espAlert

void text (cchar *field, cchar *options)

Render a text input field as part of a form.

Parameters:

field

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

options

Optional extra options. See EspControl for a list of the standard options.

cols Number number of text columns
rows Number number of text rows
password Boolean The data to display is a password and should be obfuscated.

API Stability:: Evolving.

See Also:: espAlert

void tree (EdiGrid *grid, cchar *options)

Render a tree control.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Update the cached content for a request.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Write a value to a database table field.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

bool updateFields (cchar *tableName, MprHash *data)

Write field values to a database row.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: espAlert

bool updateRec (EdiRec *rec)

Write a record to the database.

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

Parameters:

rec	Record to write to the database.

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

API Stability:: Evolving.

See Also:: espAlert

cchar * uri (cchar *target)

Create a URI.

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

Parameters:

target

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

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

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

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

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

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

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

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

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

API Stability:: Evolving.

See Also:: espAlert

EspControl

Suite of high-level controls that generate dynamic HTML5.

Description:

There are two forms of the ESP control APIs. The "full" form and the "abbreviated" form. The "full" form API takes a HttpConn request connection object as the first parameter and the function names are prefixed with "esp". The "abbreviated" form APIs are shorter and more convenient. They do not have a connection argument and determine the request connection using Thread-Local storage. They do not have any function prefix. Ocassionally, an ESP control name may clash with a function name in another library. If this happens, rename the ESP function in the esp-app.h header.

ESP Controls are grouped into two families: input form controls and general output controls. Input controls are typically located inside a form/endform control pair that defines a current database record from which data will be utilized. Output controls can be used anywhere on a page outside a form/endform group.

Input controls are generally of the form: function(field, options) where field is the name of the property in the current record that contains the data to display. The options is an object hash that controls and modifies how the control will render. The options hash is a JSON string, which is interpreted as a set of property values.

Various controls have custom options, but most share the following common set of option properties:

action String Action to invoke. This can be a URI string or a Controller/Action pair of the form @Controller/action. If only the controller is provided (@Controller/), the "list" action assumed.
apply String Client JQuery selector identifying the element to apply the remote update. Typically "div.ID" where ID is the DOM ID for the element.
background String Background color. This is a CSS RGB color specification. For example "FF0000" for red.
click (Boolean|Uri|String) URI to invoke if the control is clicked.
color String Foreground color. This is a CSS RGB color specification. For example "FF0000" for red.
confirm String Message to prompt the user to request confirmation before submitting a form or request.
controller Controller owning the action to invoke when clicked. Defaults to the current controller.
data-* All data-* names are passed through to the HTML unmodified.
domid String Client-side DOM-ID to use for the control
effects String Transition effects to apply when updating a control. Select from: "fadein", "fadeout", "highlight".
escape Boolean Escape the text before rendering. This converts HTML reserved tags and delimiters into an encoded form.
height (Number|String) Height of the control. Can be a number of pixels or a percentage string. Defaults to unlimited.
key Array List of fields to set as the key values to uniquely identify the clicked or edited element. The key will be rendered as a "data-key" HTML attribute and will be passed to the receiving controller when the entry is clicked or edited. Each entry of the key option can be a simple string field name or it can be an Object with a single property, where the property name is a simple string field name and the property value is the mapped field name to use as the actual key name. This supports using custom key names. NOTE: this option cannot be used if using cell clicks or edits. In that case, set click/edit to a callback function and explicitly construct the required URI and parameters.
keyFormat String Define how the keys will be handled for click and edit URIs. Set to one of the set: ["params", "path", "query"]. Default is "path". Set to "query" to add the key/value pairs to the request URI. Each pair is separated using "&" and the key and value are formatted as "key=value". Set to "params" to add the key/value pair to the request body parameters. Set to "path" to add the key values in order to the request URI. Each value is separated using "/". This provides "pretty" URIs that can be easily tokenized by router templates. If you require more complex key management, set click or edit to a callback function and format the URI and params manually.
id Number Numeric database ID for the record that originated the data for the view element.
method String HTTP method to invoke.
pass String attributes to pass through unaltered to the client
params Request parameters to include with a click or remote request
period Number Period in milliseconds to invoke the refresh URI to update the control data. If period is zero (or undefined), then refresh will be done using a perisistent connection.
query URI query string to add to click URIs.
rel String HTML rel attribute. Can be used to generate "rel=nofollow" on links.
remote (String|URI|Object) Perform the request in the background without changing the browser location.
refresh (String|URI|Object) URI to invoke in the background to refresh the control's data every period. milliseconds. If period is undefined or zero, a persistent connection may be used to refresh data. The refresh option may use the "\@Controller/action" form.
size (Number|String) Size of the element.
style String CSS Style to use for the element.
value Object Override value to display if used without a form control record.
width (Number|String) Width of the control. Can be a number of pixels or a percentage string. Defaults to unlimited. Dynamic Data

API Stability:: Prototype.

See Also:: espAlert, espAnchor

Fields:

int

dummy

Unused.

void endform ()

Signify the end of an HTML form.

Description:: This emits a HTML closing form tag.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAnchor

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

Render an HTML anchor link.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert

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

Render an HTML button to use inside a form.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an HTML button to use outside a form.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a graphic chart.

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

Parameters:

conn	Http connection object.
grid	Data to display. The data is a grid of data. Use ediMakeGrid or ediReadGrid.
options	Extra options. See EspControl for a list of the standard options. columns Object hash of column entries. Each column entry is (in turn) an object hash of options. If unset, all columns are displayed using defaults. kind String Type of chart. Select from: piechart, table, linechart, annotatedtimeline, guage, map, motionchart, areachart, intensitymap, imageareachart, barchart, imagebarchart, bioheatmap, columnchart, linechart, imagelinechart, imagepiechart, scatterchart (and more).

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an input checkbox.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an HTML division.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a selection list.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

void espEndform (HttpConn *conn)

Signify the end of an HTML form.

Description:: This emits a HTML closing form tag.

Parameters:

conn	Http connection object.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render flash messages.

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

Parameters:

conn	Http connection object.
kinds	Space separated list of flash messages types. Typical types are: "error", "inform", "warning".
options	Extra options. See EspControl for a list of the standard options. retain Number of seconds to retain the message. If <= 0, the message is retained until another message is displayed. Default is 0.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an HTML form.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an HTML icon.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an HTML image.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render an input field as part of a form.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a text label field.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a mail link.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Emit a progress bar.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a radio button.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Control the refresh of web page dynamic elements.

Parameters:

conn	Http connection object.
on	URI to invoke when turning "on" refresh.
off	URI to invoke when turning "off" refresh.
options	Extra options. See EspControl for a list of the standard options. minified Set to "true" to select a minified (compressed) version of the script.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a script link.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

void espSecurityToken (HttpConn *conn)

Generate a security token.

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

Parameters:

conn	Http connection object.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a stylesheet link.

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a table.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a tab control.

Parameters:

conn	Http connection object.
rec	Tab data for the control. Tab data is be be a single object where the tab text is the property key and the target to invoke is the property value.
options	Extra options. See EspControl for a list of the standard options. click Set to "true" to invoke the selected pane via a foreground click. remote Set to "true" to invoke the selected pane via a background click. toggle Set to "true" to show the selected pane and hide other panes.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a text input field as part of a form.

Parameters:

conn	Http connection object.
field	Name for the input text field. This defines the HTML element name and provides the source of the initial value to display. The field should be a property of the form control record. It can be a simple property of the record or it can have multiple parts, such as: field.field.field. If this call is used without a form control record, the actual data value should be supplied via the options.value property. If the cols or rows option is defined, then a textarea HTML element will be used for multiline input.
options	Extra options. See EspControl for a list of the standard options. cols Number number of text columns rows Number number of text rows password Boolean The data to display is a password and should be obfuscated.

API Stability:: Evolving.

See Also:: espAlert, espAnchor

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

Render a tree control.

Parameters:

conn	Http connection object.

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

Parameters:

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

API Stability:: Evolving.

See Also:: espAlert, espAnchor

EspParse

ESP page parser structure.

See Also:: Esp

EspReq

ESP request structure.

API Stability:: Internal.

See Also:: Esp

Fields:

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

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

Read a record identified by the key value.

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

Parameters:

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

Returns:: Record instance of EdiRec.

API Stability:: Evolving.

See Also:: Esp

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

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

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

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

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

See Also:: Esp

bool espCheckSecurityToken (HttpConn *conn)

Check a security token.

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

Parameters:

conn	Http connection object.

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

API Stability:: Evolving.

See Also:: Esp

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

Create a record and initialize field values.

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

Parameters:

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

Returns:: EdRec instance.

API Stability:: Evolving.

See Also:: Esp

void espFinalize (HttpConn *conn)

Finalize processing of the http request.

Description:: Finalize the response by writing buffered HTTP data and 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:: Evolving.

See Also:: Esp

void espFlush (HttpConn *conn)

Flush transmit data.

Description:: This writes any buffered data.

Parameters:

conn	HttpConn connection object.

API Stability:: Evolving.

See Also:: Esp

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

Get a list of column names.

Parameters:

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

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

API Stability:: Evolving.

See Also:: Esp

HttpConn * espGetConn ()

Get the current request connection.

Returns:: The HttpConn connection object.

API Stability:: Evolving.

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

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

See Also:: Esp

cchar * espGetCookies (HttpConn *conn)

Get the request cookies.

Description:: Get the cookies defined in the current request.

Parameters:

conn	HttpConn connection object.

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

API Stability:: Evolving.

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

See Also:: Esp

cchar * espGetDir (HttpConn *conn)

Get the default document root directory for the request route.

Parameters:

conn	HttpConn connection object.

Returns:: A directory path name.

API Stability:: Evolving.

See Also:: Esp

EspRoute * espGetEspRoute (HttpConn *conn)

Get the current extended route information.

Returns:: EspRoute instance.

API Stability:: Evolving.

See Also:: Esp

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

Get a flash message.

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

Parameters:

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

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

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

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

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

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

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

See Also:: Esp

MprHash * espGetParams (HttpConn *conn)

Get the request parameter hash table.

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

Parameters:

conn	HttpConn connection object.

Returns:: MprHash instance containing the request parameters.

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

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 espGetTop

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

See Also:: Esp

Edi * espGetRouteDatabase (EspRoute *eroute)

Get the default database defined on a route.

Parameters:

eroute

EspRoute object.

Returns:: Database instance object.

API Stability:: Evolving.

See Also:: Esp

cchar * espGetSecurityToken (HttpConn *conn)

Get a unique security token.

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

Parameters:

conn	HttpConn connection object.

Returns:: The security token string.

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

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

See Also:: Esp

char * espGetTop (HttpConn *conn)

Get a relative URI to the top of the application.

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

Parameters:

conn	HttpConn connection object.

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

API Stability:: Evolving.

See Also:: Esp

MprHash * espGetUploads (HttpConn *conn)

Get the uploaded files.

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

Parameters:

conn	HttpConn connection object.

Returns:: A hash of HttpUploadFile objects.

API Stability:: Evolving.

See Also:: Esp

cchar * espGetUri (HttpConn *conn)

Get the request URI string.

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

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

API Stability:: Evolving.

See Also:: Esp

bool espHasGrid (HttpConn *conn)

Test if a current grid has been defined.

Description:: The current grid is defined via setRec

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

API Stability:: Evolving.

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

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

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

See Also:: Esp

EdiGrid * espMakeGrid (cchar *content)

Make a grid.

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

Parameters:

content

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

Returns:: An EdiGrid instance.

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

API Stability:: Evolving.

See Also:: Esp

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

Make a hash table container of property values.

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

Parameters:

fmt	Printf style format string.
...	arguments.

Returns:: MprHash instance.

API Stability:: Evolving.

See Also:: Esp

EdiRec * espMakeRec (cchar *content)

Make a record.

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

Parameters:

content

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

Returns:: An EdiRec instance.

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

API Stability:: Evolving.

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

See Also:: Esp

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

Read all the records in table from the database.

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

Parameters:

conn	HttpConn connection object.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:: Esp

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

Read the identified record.

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

Parameters:

conn	HttpConn connection object.
tableName	Database table name.

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

API Stability:: Evolving.

See Also:: Esp

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

Read matching records.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: Esp

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

Read one record.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: Esp

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

Read receive body content.

Description:: Read body content from the client.

Parameters:

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

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

API Stability:: Evolving.

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

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

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

See Also:: Esp

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

Remove a record from a database table.

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

Parameters:

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

Returns:: Record instance of EdiRec.

API Stability:: Evolving.

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

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

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

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

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

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

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

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

See Also:: Esp

void espRenderView (HttpConn *conn, cchar *name)

Render a view template to the client.

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

Parameters:

conn	Http connection object.
name	view name.

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

See Also:: Esp

void espSetConn (HttpConn *conn)

Set the current request connection.

Parameters:

conn	The HttpConn connection object to define.

API Stability:: Evolving.

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

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

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. Some browsers will accept cookies without the initial ".", but the spec: (RFC 2109) requires it.
lifespan	Duration for the cookie to persist in msec.
isSecure	Set to "true" if the cookie only applies for SSL based connections.

API Stability:: Evolving.

See Also:: Esp

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

Update a record field without writing to the database.

Description:: This routine updates the record object with the given value. The record will not be written to the database. To write to the database, use 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:: Esp

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

Update record fields without writing to the database.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: Esp

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

Send a flash message.

Parameters:

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

API Stability:: Evolving.

See Also:: Esp

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

Send a flash message.

Parameters:

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

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

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

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

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

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

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

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

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

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

See Also:: Esp

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

Write a value to a database table field.

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

Parameters:

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

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

API Stability:: Evolving.

See Also:: Esp

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

Write field values to a database row.

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

Parameters:

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

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

API Stability:: Evolving.

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

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

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

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

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

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

EspRoute

EspRoute extended route configuration.

See Also:: Esp

Fields:

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

int espBindProc (HttpRoute *route, cchar *pattern, void *actionProc)

Define an action for a URI pattern.

Description:: This defines an action routine for the route that is responsible for the given URI pattern.

Parameters:

route	HttpRoute object.
pattern	URI pattern to use to find the releavant route.
actionProc	EspProc callback procedure to invoke when the action is requested.

API Stability:: Evolving.

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	EspRoute object.
page	ESP web page script.
path	Pathname for the ESP web page. This is used to process include directives which are resolved relative to this path.
cacheName	MD5 cache name. Not a full path.
layout	Default layout page.
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 (HttpConn *conn, cchar *source, cchar *module, cchar *cacheName, int isView)

Compile a view or controller.

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

Parameters:

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

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

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

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 (EspRoute *eroute, cchar *command, cchar *source, cchar *module)

Expand a compile or link command template.

Description:

This expands a command template and replaces "${tokens}" with their equivalent value. The supported tokens are:

ARCH - Build architecture (i386, x86_64)
CC - Compiler pathname
DEBUG - Compiler debug options (-g, -Zi, -Od)
INC - Include directory (out/inc)
LIB - Library directory (out/lib, out/bin)
LIBS - Required libraries directory (mod_esp, libappweb)
OBJ - Name of compiled source (out/lib/view-MD5.o)
OUT - Output module (view_MD5.dylib)
SHLIB - Shared library extension (.lib, .so)
SHOBJ - Shared object extension (.dll, .so)
SRC - Path to source code for view or controller (already templated)
TMP - System temporary directory
WINSDK - Path to the Windows SDK
VS - Path to Visual Studio

Parameters:

eroute	Esp route 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

Functions

void espInitHtmlOptions (Esp *esp)

Add HTLM internal options to the Esp.options hash.

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 cchar*(* EdiValidationProc)(struct EdiValidation *vp, struct EdiRec *rec, cchar *fieldName, cchar *value).

Field validation callback procedure.

Parameters:

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

API Stability:: Evolving.

See Also:

typedef EspProc EspAction.

ESP Action.

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

API Stability:: Evolving.

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)(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

EdiProvider

Database provider interface.

Fields:

EdiValidation

Validation structure.

API Stability:: Evolving.

Fields:

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

Esp

Top level ESP structure.

Fields:

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

See Also

Quick Nav

APPWEB - ESP API Native API

Components

Functions

Typedefs

Defines

Edi

EdiField

EdiGrid

EdiRec

EdiService

EspAbbrev

EspControl

EspParse

EspReq

EspRoute

Functions

Typedefs