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:

int		flags	Database flags.
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.

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.

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.

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.

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.

See Also:

void ediClose (Edi *edi)

Close a database.

Parameters:

edi	Database handle.

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.

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.

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.

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.

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.

See Also:

cchar * ediFormatField (cchar *fmt, EdiField value)

Format a field value.

Parameters:

fmt	Printf style format string.
value	Field value.

Returns:: Formatted value string.

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.

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.

See Also:

cchar * ediGetField (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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

See Also:

EdiGrid * ediMakeGrid (cchar *content)

Make a grid.

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' }, \
]");.

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.

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' }");.

See Also:

void ediManageEdiRec (EdiRec *rec, int flags)

Manage an EdiRec instance for garbage collection.

Parameters:

rec	Record instance.
flags	GC management flag.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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	nrecords	Number of records in grid.
EdiRec *	records[MPR_FLEX]	Grid records.
cchar *	tableName	Base table name for grid.

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[MPR_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.

See Also:

EdiService * ediCreateService ()

Create the EDI service.

Returns:: EdiService object.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

See Also:: espAlert

void 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. This routine calls $espCreateSession.

See Also:: espAlert

void destroySession ()

Destroy a session state object.

Description:

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.

See Also:: espAlert

void dontAutoFinalize ()

Don't auto-finalize this request.

See Also:: espAlert

void dropdown (cchar *field, cchar *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 JSON style set of properties. For example: espDropdown(conn, "priority", "{ low: 0, med: 1, high: 2 }", NULL).
options	Extra options. See $EspControl for a list of the standard options.

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.

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

See Also:: espAlert

void flush ()

Flush transmit data.

Description:: This writes any buffered data.

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.

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.

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.

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.

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.

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.

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.

See Also:: espAlert

cchar * getDir ()

Get the default document root directory for the request route.

Returns:: A directory path name.

See Also:: espAlert

EspRoute * getEspRoute ()

Get the extended route EspRoute structure.

Returns:: EspRoute instance.

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.

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.

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 $home.

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

See Also:: espAlert

cchar * getSessionVar (cchar *name)

Get a session state variable.

Description:: See also $espGetSessionVar and $espGetSessionObj for alternate ways to retrieve session data.

Parameters:

name	Variable name to get.

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

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.

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.

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.

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.

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.

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. This routine calls $espInform.

Parameters:

fmt	Printf style message format.

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.

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.

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.

See Also:: espAlert

bool isSecure ()

Test if the connection is using SSL and is secure.

Returns:: "true" if the connection is using SSL.

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.

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.

See Also:: espAlert

EdiGrid * makeGrid (cchar *content)

Make a grid.

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' }, \
]");.

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.

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' }");.

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.

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.

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.

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.

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: espRadio(conn, "priority", "{ low: 0, med: 1, high: 2, }", NULL).
options	Extra options. See $EspControl for a list of the standard options.

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.

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.

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.

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.

See Also:: espAlert

void redirectBack ()

Redirect the client back to the referrer.

Description:: Redirect the client to the referring URI.

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.

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.

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.

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.

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.

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.

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.

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.

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.

See Also:: espAlert

void setConn (HttpConn *conn)

Set the current request connection.

Parameters:

conn	The HttpConn connection object to define.

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.

See Also:: espAlert

void setCookie (cchar *name, cchar *value, cchar *path, cchar *domain, MprTime 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.

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 $writeRec.

Parameters:

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

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

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 $ediWriteRec.

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.

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. The $inform, $error and $warn convenience methods invoke $notice. This routine calls $espSetFlash.

Parameters:

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

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.

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.

See Also:: espAlert

void setSessionVar (cchar *name, cchar *value)

Set a session state variable.

Description:: See also $espSetSessionVar and $espSetSessionObj for alternate ways to set session data.

Parameters:

name	Variable name to set.
value	Value to set.

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.

See Also:: espAlert

void setTimeout (void *proc, MprTime 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.

See Also:: espAlert

void showRequest ()

Show request details.

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

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.

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 ediCreateGrid or ediReadGrid.
options	Extra options. See $EspControl for a list of the standard options.
options	Optional extra options. See $View 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 (Array\|Object) The columns list is anobject 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.

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 $View 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.

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 $View 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.

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 $View for a list of the standard options.

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.

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.

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.

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.

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);.

See Also:: espAlert

EspControl

There are two groups of ESP Control APIs.

API Stability:: Prototype.

See Also:: espAlert

Fields:

void endform ()

Signify the end of an HTML form.

Description:: This emits a HTML closing form tag.

See Also:: espAlert

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.

See Also:

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.

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.

See Also:: espAlert

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.

See Also:: espAlert

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 ediCreateGrid 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).

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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

Render a dropdown 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 JSON style set of properties. For example: espDropdown(conn, "priority", "{ low: 0, med: 1, high: 2 }", NULL).
options	Extra options. See $EspControl for a list of the standard options.

See Also:: espAlert

void espEndform (HttpConn *conn)

Signify the end of an HTML form.

Description:: This emits a HTML closing form tag.

Parameters:

conn	Http connection object.

See Also:: espAlert

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. MOB - this default implies it is displayed for zero seconds

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

void espRadio (HttpConn *conn, cchar *field, void *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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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.

See Also:: espAlert

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 ediCreateGrid or ediReadGrid.
options	Extra options. See $EspControl for a list of the standard options.
options	Optional extra options. See $View 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 (Array\|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.

See Also:: espAlert

void espTabs (HttpConn *conn, 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:

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	Optional extra options. See $View 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.

See Also:: espAlert

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	Optional extra options. See $View 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.

See Also:: espAlert

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	Optional extra options. See $View for a list of the standard options.

See Also:: espAlert

EspParse

ESP page parser structure.

See Also:

Fields:

char *	data	Input data to parse.
int	lineNumber	Line number for error reporting.
char *	next	Next character in input.
MprBuf *	token	Storage buffer for token.

EspReq

ESP request.

See Also:

Fields:

EspAction *	action	Action to invoke.
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.
EspSession *	session	Session data object.
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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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

See Also:

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.

See Also:

void espFinalize (HttpConn *conn)

Finalize transmission of the http request.

Description:: Finalize writing HTTP 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.

See Also:

void espFlush (HttpConn *conn)

Flush transmit data.

Description:: This writes any buffered data.

Parameters:

conn	HttpConn connection object.

See Also:

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.

See Also:

HttpConn * espGetConn ()

Get the current request connection.

Returns:: The HttpConn connection object.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

cchar * espGetDir (HttpConn *conn)

Get the default document root directory for the request route.

Parameters:

conn	HttpConn connection object.

Returns:: A directory path name.

See Also:

EspRoute * espGetEspRoute (HttpConn *conn)

Get the current extended route information.

Returns:: EspRoute instance.

See Also:

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

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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 $espGetHome.

Parameters:

conn	HttpConn connection object.

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

See Also:

Edi * espGetRouteDatabase (HttpRoute *route)

Get the default database defined on a route.

Parameters:

route

HttpRoute object.

Returns:: Database instance object.

See Also:

int espGetStatus (HttpConn *conn)

Get the response status.

Parameters:

conn	HttpConn connection object.

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

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

bool espIsFinalized (HttpConn *conn)

Test if a http request is 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.

See Also:

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.

See Also:

EdiGrid * espMakeGrid (cchar *content)

Make a grid.

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' }, \
]");.

See Also:

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.

See Also:

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' }");.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

void espRedirectBack (HttpConn *conn)

Redirect the client back to the referrer.

Description:: Redirect the client to the referring URI.

Parameters:

conn	HttpConn connection object.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

ssize espRenderParam (HttpConn *conn, cchar *name)

Render the value of a request parameter to the client.

Description:: This writes the value of a request parameter after HTML escaping its value.

Parameters:

conn	HttpConn connection object.
name	Form variable name.

Returns:: A count of the bytes actually written.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

void espSetConn (HttpConn *conn)

Set the current request connection.

Parameters:

conn	The HttpConn connection object to define.

See Also:

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.

See Also:

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.

See Also:

void espSetCookie (HttpConn *conn, cchar *name, cchar *value, cchar *path, cchar *domain, MprTime 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.

See Also:

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 $writeRec.

Parameters:

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

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

See Also:

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 $ediWriteRec.

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.

See Also:

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.

See Also:

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.

See Also:

EdiGrid * espSetGrid (HttpConn *conn, EdiGrid *grid)

Set the current database grid.

Returns:: The grid instance. This permits chaining.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

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.

See Also:

cchar * espUri (HttpConn *conn, cchar *target)

Create a URI.

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

Parameters:

conn

HttpConn connection object.

target

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

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

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

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

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

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

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

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

Example:: EspUri(conn, "http://example.com/index.html", 0);
espUri(conn, "/path/to/index.html", 0);
espUri(conn, "../images/splash.png", 0);
espUri(conn, "~/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);.

See Also:

cchar * getMethod ()

Get the HTTP method.

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

Returns:: The HttpConn.rx.method property.

See Also:

EspRoute

EspRoute extended route configuration.

See Also:

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.
MprList *	env	Environment for compiler.
int	keepSource	Preserve generated source.
char *	layoutsDir	Directory for layouts.
MprTime	lifespan	Default cache lifespan.
char *	link	Link template.
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.

char * espBuildScript (HttpRoute *route, cchar *page, cchar *path, cchar *cacheName, cchar *layout, char **err)

Convert an ESP web page into compilable 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.
err	Output parameter to hold any relevant error message.

Returns:: C language code string for the web page.

See Also:

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.

See Also:

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.

See Also:

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	Route 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.

See Also:

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	Route object.
baseProc	Function to call just prior to invoking a controller action.

See Also:

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.

See Also:

char * espExpandCommand (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:

command	Http connection object.
source	ESP web page source pathname.
module	Output module pathname.

Returns:: An expanded command line.

See Also:

EspSession

ESP session state object.

See Also:

Fields:

MprCache *	cache	Cache store reference.
char *	id	Session ID key.
MprTime	lifespan	Session inactivity timeout (msecs).

EspSession * espAllocSession (HttpConn *conn, cchar *id, MprTime lifespan)

Allocate a new session state object.

Description:

Parameters:

conn	Http connection object.
id	Unique session state ID.
lifespan	Session lifespan in ticks.

Returns:: A session state object.

See Also:

EspSession * espCreateSession (HttpConn *conn)

Create a session object.

Description:: This call creates a session object if one does not already exist. Session state stores persist across individual HTTP requests.

Parameters:

conn	Http connection object.

Returns:: A session state object.

See Also:

void espDestroySession (EspSession *sp)

Destroy a session state object.

Description:

Parameters:

sp	Session state object allocated with espAllocSession

See Also:

EspSession * espGetSession (HttpConn *conn, int create)

Get a session state object.

Description:

Parameters:

conn	Http connection object.
create	Set to "true" to create a session state object if one does not already exist for this client.

Returns:: A session state object.

See Also:

char * espGetSessionID (HttpConn *conn)

Get the session ID.

Description:

Parameters:

conn	Http connection object.

Returns:: The session ID string.

See Also:

MprHash * espGetSessionObj (HttpConn *conn, cchar *key)

Get an object from the session state store.

Description:: Retrieve an object from the session state store by deserializing all properties.

Parameters:

conn	Http connection object.
key	Session state key.

See Also:

cchar * espGetSessionVar (HttpConn *conn, cchar *name, cchar *defaultValue)

Get a session state variable.

Description:

Parameters:

conn	Http connection object.
name	Variable name to get.
defaultValue	If the variable does not exist, return the defaultValue.

Returns:: The variable value or defaultValue if it does not exist.

See Also:

int espSetSessionObj (HttpConn *conn, cchar *key, MprHash *value)

Set an object into the session state store.

Description:: Store an object in the session state store by serializing all properties.

Parameters:

conn	Http connection object.
key	Session state key.
value	Object to serialize.

See Also:

int espSetSessionVar (HttpConn *conn, cchar *name, cchar *value)

Set a session variable.

Description:

Parameters:

conn	Http connection object.
name	Variable name to set.
value	Variable value to use.

Returns:: A session state object.

See Also:

EdiGrid * espGetGrid (HttpConn *conn)

Get the current database grid.

Description:: The current grid is defined via $setGrid.

Returns:: EdiGrid instance.

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.

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.

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.

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.

EdiGrid * getGrid ()

Get the current database grid.

Description:: The current grid is defined via $setGrid.

Returns:: EdiGrid instance.

EdiRec * getRec ()

Get the current database record.

Description:: The current record is defined via $setRec.

Returns:: EdiRec instance.

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.

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.

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.

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.

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.

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.

EdiGrid * setGrid (EdiGrid *grid)

Set the current database grid.

Returns:: The grid instance. This permits chaining.

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.

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

Procedure callback.

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.

See Also:

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

View procedure callback.

Parameters:

conn	Http connection object.

See Also:

EdiProvider

Database provider interface.

Fields:

EdiValidation

Validation structure.

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.
MprCache *	sessionCache	Session state cache.
MprHash *	views	Table of views.

EspAction

ESP Action.

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

Fields:

EspProc

actionProc

Action procedure to run to respond to the request.

See Also:

#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_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_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.

APPWEB - ESP API Native API

Components

Functions

Typedefs

Defines

Edi

EdiField

EdiGrid

EdiRec

EdiService

EspAbbrev

EspControl

EspParse

EspReq

EspRoute

EspSession

Functions

Typedefs