Embedded Server Pages C API

Detailed Description

Embedded Server Pages (ESP) is a simple and powerful environment for creating dynamic HTML web pages. It is a portable and cross-platform and has been ported to run in several web servers. It is like a mini-PHP with a similar usage paradigm, but is much smaller and requires far fewer resources at run time.

ESP allows you to embed JavaScript statements, scripts and programs into HTML pages that are automatically run when the ESP page is accessed. The ESP engine and embedded scripting create the actual page the users sees "on the fly". ESP and the Embedded JavaScript (EJS) interpreter work very closely together to provide the ESP page creation environment.

JavaScript statements can use standard JavaScript features or you can enhance the JavaScript environment by publishing new JavaScript functions that can be called from with the ESP pages. ESP allows you to link C functions to their JavaScript namesake so that when an ESP page executes a JavaScript function call, the C function is seamlessly invoked with the appropriate arguments.

Read the ESP User Guide and the JavaScript Guide for more details.

Typedefs
typedef int(*	EspCFunction )(EspRequest *ep, int argc, struct MprVar **argv)
	Function signature for ESP function callback procedures. The maEspDefineCFunction call takes a function of this prototype to associate with a JavaScript function.
typedef void *	EspHandle
	Opaque handle usually used to store the web request handle.
typedef int(*	EspStringCFunction )(EspRequest *ep, int argc, char **argv)
	Function signature for ESP function callbacks that require string arguments. The maEspDefineStringCFunction call takes a function of this prototype to associate with a JavaScript function.
Functions
bool	espDestroyVar (MprVar *var)
MprVar *	espGetFirstProperty (MprVar *obj, int includeFlags)
MprVar *	espGetGlobalObject (EspRequest *ep)
MprVar *	espGetLocalObject (EspRequest *ep)
MprVar *	espGetNextProperty (MprVar *obj, MprVar *currentProperty, int includeFlags)
int	espGetPropertyCount (MprVar *obj, int includeFlags)
EspHandle	espGetRequestHandle (EspRequest *ep)
MprVar *	espGetResult (EspRequest *ep)
EjsId	espGetScriptHandle (EspRequest *ep)
void	espSetResponseCode (EspRequest *ep, int code)
void	espSetReturn (EspRequest *ep, MprVar value)

Typedef Documentation

typedef int(* EspCFunction)(EspRequest *ep, int argc, MprVar **argv)

Function signature for ESP function callback procedures. The maEspDefineCFunction call takes a function of this prototype to associate with a JavaScript function. Parameters: ep  ESP request handle. argc  Count of the number of arguments in argv argv  Array of string arguments Stability classification: Evolving Library: libespModule

typedef void * EspHandle

Opaque handle usually used to store the web request handle. Stability classification: Evolving Library: libespModule

typedef int(* EspStringCFunction)(EspRequest *ep, int argc, char **argv)

Function signature for ESP function callbacks that require string arguments. The maEspDefineStringCFunction call takes a function of this prototype to associate with a JavaScript function. Parameters: ep  ESP request handle. argc  Count of the number of arguments in argv argv  Array of string arguments Stability classification: Evolving Library: libespModule

Function Documentation

bool espDestroyVar (  MprVar *  obj  )

Synopsis: Destroy an ESP variable Overview: This call destroys an ESP variable and frees allocated storage. If the variable represents an object, the object's reference count will be decremented and if zero, the object will be destroyed. If the object has properties that represent other objects, these too will be destroyed recursively if their refererence counts are zero. mprDestroyVar can intelligently handle circular references between objects. mprDestroyVar intelligently destroys dynamicall allocated objects that have been created via mprDupVar and statically copied object that have been created using mprCreate or mprCopyVar. Parameters: obj  Pointer to an ESP variable to destroy Returns: Returns TRUE if they underlying data was freed. This will be false for objects, if there are other users of the object. Otherwise, for all other types, it will be TRUE. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espCreateObjVar, espDefineCFunction, espCreateProperty, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

MprVar* espGetFirstProperty (  MprVar *  obj, int  includeFlags )

Synopsis: Get the first property in from an object. Overview: To iterate over the properties in an object, espGetFirstProperty and espGetNextProperty are used. You can specify what object properties you wish to enumerate by setting the includeFlags mask. For example: /// MprVar *vp; /// vp = espGetFirstProperty(obj, MPR_ENUM_DATA); /// while (vp) { /// /* Processing each property here */ /// vp = espGetNextProperty(obj, vp); /// } /// Parameters: obj  The object in which to enumerate the properties. includeFlags  Bit mask that specifies what variables to enumerate. Or together bits from: MPR_ENUM_DATA to enumerate data properties and, MPR_ENUM_FUNCTIONS to enumerate functions. Returns: Returns a pointer to the property. Caller does not need to free. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espGetNextProperty, espGetProperty, espGetPropertyCount, espGetVar, espSetVar

MprVar* espGetGlobalObject (  EspRequest *  ep  )

Synopsis: Return a pointer to the JavaScript interpreter's global variables object Overview: ESP maintains a global variable object in which all global variables are defined as properties. You can access global variables directly by name or via "global.name". This is useful if there may be a local variable of the same name and you need to guarantee you are referencing the global variable. Parameters: ep  ESP request handle. Returns: Returns a pointer to the global object. The caller should not free the returned object. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espError, espGetLocalObject, espGetProperty, espGetVar, espGetStringVar, espGetResult, espSetProperty

MprVar* espGetLocalObject (  EspRequest *  ep  )

Synopsis: Return a pointer to the local variables object Overview: ESP maintains a local variable object in which all local variables are defined as properties. You can access local variables directly by name or via "local.name". Use the espGetProperty routine to read properties in the local object. Parameters: ep  ESP request handle. Returns: Returns a pointer to the local object. The caller should not free the returned object. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espError, espGetGlobalObject, espGetProperty, espGetVar, espGetStringVar, espGetResult, espSetProperty

MprVar* espGetNextProperty (  MprVar *  obj, MprVar *  currentProperty, int  includeFlags )

Synopsis: Get the next property when enumerating object properties. Overview: This call returns the next property in sequence. Use espGetFirstProperty to begin the enumeration. Parameters: obj  The object in which to enumerate the properties. currentProperty  The property last returned from espGetNextProperty or espGetFirstProperty. includeFlags  Bit mask that specifies what variables to enumerate. Or together bits from: MPR_ENUM_DATA to enumerate data properties and, MPR_ENUM_FUNCTIONS to enumerate functions. Returns: Returns a pointer to the property. Caller does not need to free. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espGetFirstProperty, espGetProperty, espGetPropertyCount, espGetVar, espSetVar

int espGetPropertyCount (  MprVar *  obj, int  includeFlags )

Synopsis: Get the count of properties in an object Overview: Returns the count of properties in an object. includeFlags determines the types of properties that are counted. Parameters: obj  The object in which to count the properties. includeFlags  Bit mask specifying what properties to count. MPR_ENUM_DATA means count data properties. MPR_ENUM_FUNCTION means count function properties. Returns: Returns the number selected properties in the object. Returns MPR_ERR_BAD_STATE if the object is not of type MPR_TYPE_OBJECT. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espGetFirstProperty, espGetNextProperty, espGetProperty, espGetVar espSetVar, espSetStringVar

EspHandle espGetRequestHandle (  EspRequest *  ep  )

Synopsis: Get the web server request handle. Overview: This call returns the web server request handle that describes the current web request. For Appweb this is an MaRequest* type and for WebServer it is a webs_t type. Parameters: ep  ESP request handle. Returns: Returns the web server request handle. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espDefineCFunction, espError, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWrite

MprVar* espGetResult (  EspRequest *  ep  )

Synopsis: Get the current ESP result. Overview: This call gets the result value of the last ESP expression or function executed. If you call espEvalScript, espEvalFile or espRunFunction, ESP will set the result to be the value of the last expression evaluated. If that is a function, the result will be the return value of the script. If it is a script, it will be the value of last expression evaluated. Parameters: ep  ESP request handle. Returns: Pointer to the MprVar describing the result. The caller does not need to free the variable. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espDefineCFunction, espError, espGetRequestHandle, espGetScriptHandle, espRedirect, espRunFunction, espSetHeader, espSetResponseCode, espSetReturn, espWrite

EjsId espGetScriptHandle (  EspRequest *  ep  )

Synopsis: Get the JavaScript instance handle. Overview: This call returns JavaScript instance handle that can be used with many EJS API calls. Parameters: ep  ESP request handle. Returns: Returns the JavaScript instance handle. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espDefineCFunction, espError, espGetRequestHandle, espGetResult, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWrite

void espSetResponseCode (  EspRequest *  ep, int  code )

Synopsis: Set the HTTP response code Overview: This call defines the HTTP status code output with the request response. This call should not normally be needed as espError will set the response code if an error occurs. If no error has occurred the web server will set the response code automatically to 200 which is a successful status code, See RFC 2616 for a complete list of HTTP status codes at http://www.w3.org/Protocols/rfc2616/rfc2616.html Parameters: ep  ESP request handle. code  HTTP status code Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetReturn, espWrite

void espSetReturn (  EspRequest *  ep, MprVar  value )

Synopsis: Set the ESP function return value. Overview: This call sets the return result value of an ESP function that has been bound to a JavaScript function via espDefineCMethod. The return value can be a primitive type such as an integer or string or it may be a complete object. See the MprVar and the variable constructors such as mprCreateStringVar and mprCreateIntegerVar for defining result values. If you have string return values, use the convenience routine espSetReturnString. Parameters: ep  ESP request handle. value  Return value. Library: libesp, libappweb Configure options: Requires BLD_FEATURE_ESP_MODULE. See also: espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espRunFunction, espSetHeader, espSetResponseCode, espWrite