Embedded Server Pages C API


Detailed Description

Embedded Server Pages (ESP).

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

int espCopyVar (EspRequest *ep, char *var, MprVar *value, int copyDepth)
MprVar espCreateArrayVar (char *name, int size)
MprVar espCreateObjVar (char *name, int hashSize)
MprVar * espCreateProperty (MprVar *obj, char *property, MprVar *newValue)
MprVar * espCreatePropertyValue (MprVar *obj, char *property, MprVar newValue)
void espDefineCFunction (EspRequest *ep, char *functionName, EspCFunction fn, void *thisPtr)
void espDefineFunction (EspRequest *ep, char *functionName, char *args, char *body)
void espDefineStringCFunction (EspRequest *ep, char *functionName, EspStringCFunction fn, void *thisPtr)
int espDeleteProperty (MprVar *obj, char *property)
int espDeleteVar (EspRequest *ep, char *var)
bool espDestroyVar (MprVar *var)
void espError (EspRequest *ep, char *fmt,...)
int espEvalFile (EspRequest *ep, char *path, MprVar *result, char **emsg)
int espEvalScript (EspRequest *ep, char *script, MprVar *result, char **emsg)
MprVar * espGetFirstProperty (MprVar *obj, int includeFlags)
MprVar * espGetGlobalObject (EspRequest *ep)
MprVar * espGetLocalObject (EspRequest *ep)
MprVar * espGetNextProperty (MprVar *obj, MprVar *currentProperty, int includeFlags)
MprVar * espGetProperty (MprVar *obj, char *property, MprVar *value)
int espGetPropertyCount (MprVar *obj, int includeFlags)
EspHandle espGetRequestHandle (EspRequest *ep)
MprVar * espGetResult (EspRequest *ep)
EjsId espGetScriptHandle (EspRequest *ep)
char * espGetStringVar (EspRequest *ep, EspEnvType oType, char *var, char *defaultValue)
int espGetVar (EspRequest *ep, EspEnvType oType, char *var, MprVar *value)
int espReadVar (EspRequest *ep, char *var, MprVar *value)
void espRedirect (EspRequest *ep, int code, char *url)
int espRunFunction (EspRequest *ep, MprVar *obj, char *functionName, MprArray *args)
void espSetHeader (EspRequest *ep, char *header, bool allowMultiple)
MprVar * espSetProperty (MprVar *obj, char *property, MprVar *newValue)
MprVar * espSetPropertyValue (MprVar *obj, char *property, MprVar newValue)
void espSetResponseCode (EspRequest *ep, int code)
void espSetReturn (EspRequest *ep, MprVar value)
void espSetReturnString (EspRequest *ep, char *str)
void espSetStringVar (EspRequest *ep, EspEnvType oType, char *var, char *value)
void espSetVar (EspRequest *ep, EspEnvType oType, char *var, MprVar value)
int espUnsetVar (EspRequest *ep, EspEnvType oType, char *var)
int espWrite (EspRequest *ep, char *buf, int size)
int espWriteFmt (EspRequest *ep, char *fmt,...)
int espWriteVar (EspRequest *ep, char *var, MprVar *value)
int espWriteVarValue (EspRequest *ep, char *var, 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

int espCopyVar ( EspRequest *  ep,
char *  var,
MprVar *  value,
int  copyDepth 
)

Synopsis:
Copy a JavaScript variable
Overview:
This function copies a variable. Variables contain primitive types such as integers or floating point numbers. They may also contain strings or references to objects. When an object is copied, certain fields such as the object name are always duplicated and so when the the copied variable is no longer needed, it must be destroyed via mprDestroyVar to release the allocated storeage.

Parameters:
ep ESP request handle.
var Name of the variable to copy. Variable names may be fully qualified object.property refererence. I.e. they may contain "." or "[]". However, array indexes inside "[]" must be constant. If you require variable access with expresssion array indexes, use espEvalScript and define your script to just be the array reference.
value Pointer to a MprValue to contain the copied variable.
copyDepth Flags to specify how to copy the data inside the variable. If copyDepth is MPR_DEEP_COPY, the all data fields are completely copies. If the source variable is an object, then all its properties will also be copied. If these properties are themselves objects, they will also be copied recursively.

If copyDepth is MPR_SHALLOW_COPY, objects will not be copied. Rather the object's reference count will be incremented. Objects use reference counts to assist the garbage collection mechanism. When the reference count is zero, the object is discarded. For MPR_SHALLOW_COPY, string data will still be copied.

If copyDepth is 0 or MPR_NO_COPY, then no objects or strings are copied. Only primitive data and the string or object reference is copied. Object reference counts are not changed. Use care when using MPR_NO_COPY particularly when running multithreaded.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espCreateObjVar, espCreateProperty, espGetProperty, espGetResult, espGetVar, espReadVar, espSetVar, mprCopyVar, mprDupVar

MprVar espCreateArrayVar ( char *  name,
int  size 
)

Synopsis:
Create a ESP array variable
Overview:
This call create an array variable with the standard ESP/EJS array properties and methods. Embedded JavaScript array objects are created with the toString and toValue methods defined. Once created, the underlying array will have a reference count of 1. To destroy the array, call espDestroyVar which will decrement the reference count and will destroy the array if no-one is still using it (ie. ref count == 0).
Parameters:
name Name of the variable. This name is not used for access and is primarily used for debugging.
size Initial size of the array.
Returns:
Returns the created array object. If a memory allocation failure occurs, the returned object will have a type set to MPR_TYPE_UNDEFINED.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espCreateObjVar, espDefineCFunction, espCreateProperty, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

MprVar espCreateObjVar ( char *  name,
int  hashSize 
)

Synopsis:
Create a ESP object variable
Overview:
This call create an object variable with the standard ESP/EJS properties and methods. Embedded JavaScript objects are created with the toString and toValue methods defined. Once created, the underlying object will have a reference count of 1. To destroy the object, call mprDestroyVar which will decrement the reference count and will destroy the object if no-one is still using the object (ie. ref count == 0).
Parameters:
name Name of the variable. This name is not used for access and is primarily used for debugging.
hashSize Size of the objects property index hash table. Objects index their properties using hash tables. If an object or array has many properties or elements, performance can be enhanced by specifying a larger hash table size. Specify zero to accept the default hash table size.
Returns:
Returns the created object. If a memory allocation failure occurs, the returned object will have a type set to MPR_TYPE_UNDEFINED.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espCreateArrayVar, espDefineCFunction, espCreateProperty, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

MprVar* espCreateProperty ( MprVar *  obj,
char *  property,
MprVar *  newValue 
)

Synopsis:
Create a property in the nominated object.
Overview:
This call creates and initializes a property in an object. The property must not already exist.
Parameters:
obj The object in which to create the property.
property Name of the property. This must be a simple JavaScript identifier without "." or "[]" characters.
newValue Pointer to a MprVar with which to initialize the property.
Returns:
Returns a pointer to the created property.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espCreateObjVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar

MprVar* espCreatePropertyValue ( MprVar *  obj,
char *  property,
MprVar  newValue 
)

Synopsis:
Create a property in the nominated object.
Overview:
This call creates and initializes a property in an object. The property must not already exist. This routine is very similar to espCreateProperty except that the new value is passed by "value" rather than by reference.
Parameters:
obj The object in which to create the property.
property Name of the property. This must be a simple JavaScript identifier without "." or "[]" characters.
newValue Value to with which to initialize the property.
Returns:
Returns a pointer to the new property.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espCreateObjVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar

void espDefineCFunction ( EspRequest *  ep,
char *  functionName,
EspCFunction  fn,
void *  thisPtr 
)

Synopsis:
Define a C language function to invoke when the named JavaScript function is called.
Overview:
This call binds a C function with a JavaScript function name. Whenever the JavaScript function is called, the associated C function will be invoked with the supplied arguments.
Parameters:
ep ESP request handle.
functionName JavaScript function name to associate with this C function.
fn C function to be invoked.
thisPtr If using C++ the thisPtr argument can be set to an object that will contain a function to be invoked. The fn argument must still be set to a C language wrapper which then invokes the C++ function contained in the object pointed to by thisPtr.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineFunction, espDefineStringCFunction

void espDefineFunction ( EspRequest *  ep,
char *  functionName,
char *  args,
char *  body 
)

Synopsis:
Define a JavaScript function.
Overview:
This call defines a JavaScript function by supplying a JavaScript script body and a formal argument list.
Parameters:
ep ESP request handle.
functionName JavaScript function name for this function.
args Formal parameters for the function.
body JavaScript body of the function.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espDefineStringCFunction

void espDefineStringCFunction ( EspRequest *  ep,
char *  functionName,
EspStringCFunction  fn,
void *  thisPtr 
)

Synopsis:
Define a C language function with string arguments to invoke when the named JavaScript function is called.
Overview:
This call binds a C function with a JavaScript function name. Whenever the JavaScript function is called, the given arguments are converted to strings and the associated C function is be invoked. For functions that only ever require string arguments, this is the preferred way of binding to JavaScript function names.
Parameters:
ep ESP request handle.
functionName JavaScript function name to associate with this C function.
fn C function to be invoked.
thisPtr If using C++ the thisPtr argument can be set to an object that will contain a function to be invoked. The fn argument must still be set to a C language wrapper which then invokes the C++ function contained in the object pointed to by thisPtr.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineFunction, espDefineCFunction

int espDeleteProperty ( MprVar *  obj,
char *  property 
)

Synopsis:
Delete the property in the specified object.
Overview:
This call deletes a property from an object.
Parameters:
obj The object in which to delete the property.
property Name of the property to delete. This must be a simple JavaScript identifier without "." or "[]" characters.
Returns:
Returns zero if sucssessful. Otherwise a negative MPR error code.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espCreateProperty, espCreateObjVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar

int espDeleteVar ( EspRequest *  ep,
char *  var 
)

Synopsis:
Delete the named variable
Overview:
This function deletes the named variable. Variables contain primitive types such as integers or floating point numbers. They may also contain strings or references to objects.
Parameters:
ep ESP request handle.
var Name of the variable to copy. Variable names may be fully qualified object.property refererence. I.e. they may contain "." or "[]". However, array indexes inside "[]" must be constant. If you require variable access with expresssion array indexes, use espEvalScript and define your script to just be the array reference.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espGetResult, espGetVar, espCopyVar, espSetVar, espWriteVar

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,

void espError ( EspRequest *  ep,
char *  fmt,
  ... 
)

Synopsis:
Abort the ESP request and respond with an error
Overview:
This call aborts the current ESP request. If ESP is configured to send errors to the user's browser, the formatted error messsage will be sent to the browser. If configured to log error messages, the error is logged. Note: that error messages are automatically HTML encoded to prevent cross-site scripting errors.
Parameters:
ep ESP request handle.
fmt Printf style format string
... Variable arguments for the format string
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWrite

int espEvalFile ( EspRequest *  ep,
char *  path,
MprVar *  result,
char **  emsg 
)

Synopsis:
Evaluate a file script
Overview:
This call reads and evaluates the script specified by the path argument. The value of the last expression evaluated is returned in result. If the script encounters an error, processing is aborted and emsg is set to a descriptive error message. If an error occurs the caller must free the message by calling mprFree(emsg).
Parameters:
ep ESP request handle.
path File pathname containing the name of the script file.
result Pointer to a MprVar variable that will contain a pointer to the result. The caller does not need to free the result.
emsg Pointer to a location to hold an error message if errors occurs.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineFunction, espDefineCFunction, espDefineStringCFunction, espRunFunction, espEvalScript

int espEvalScript ( EspRequest *  ep,
char *  script,
MprVar *  result,
char **  emsg 
)

Synopsis:
Evaluate a script
Overview:
This call evaluates the supplied ESP/JavaScript script. The value of the last expression evaluated is returned in result. If the script encounters an error, processing is aborted and emsg is set to a descriptive error message. If an error occurs the caller must free the message by calling mprFree(emsg).
Parameters:
ep ESP request handle.
script Buffer containing the script.
result Pointer to a MprVar variable that will contain a pointer to the result. The caller does not need to free the result.
emsg Pointer to a location to hold an error message if errors occurs.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineFunction, espDefineCFunction, espDefineStringCFunction, espRunFunction, espEvalFile

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

MprVar* espGetProperty ( MprVar *  obj,
char *  property,
MprVar *  value 
)

Synopsis:
Get a property
Overview:
This call returns a pointer to a property and optionally sets the value argument to the property's value. If value is not NULL and it points to a MprVar variable, espGetProperty will copy the property's value into value. This routine can be used to test if a property exists. If the referenced property is an object, this call will not affect the reference count. This call invokes READ triggers that have been defined on the property.
Parameters:
obj The object in which to get the property.
property Name of the property to access.
value Optional pointer to a MprVar to accept a copy of the data. The caller does not need to destroy the value via mprDestroyVar.
Returns:
Returns a pointer to the property variable. Returns zero if the property cannot be found.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espCreateProperty, espCreateObjVar, espDeleteProperty, espReadVar, espSetProperty, espWriteVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar

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

char* espGetStringVar ( EspRequest *  ep,
EspEnvType  oType,
char *  var,
char *  defaultValue 
)

Synopsis:
Get the string value of a standard ESP array.
Overview:
This call returns the value of a string variable from one of the standard ESP variables arrays: application, server[], session[], request[], headers[], cookies[], files[], form[], application[], global[], and local[]. This call indexes into one of these object arrays to retrieve a specific variable setting and return a pointer to its string value.
if the variable is not defined, the supplied defaultValue is returned.
Parameters:
ep ESP request handle.
oType Object index. Must be one of: ESP_SERVER_OBJ, ESP_SESSION_OBJ, ESP_REQUEST_OBJ, ESP_HEADERS_OBJ, ESP_COOKIES, ESP_FILES, ESP_FORM_OBJ, ESP_APPLICATION_OBJ, ESP_GLOBAL_OBJ, ESP_LOCAL_OBJ
var Name of the variable to access. For example:
        espGetStringVar(ep, ESP_HEADERS_OBJ, "Content-Type", &value);

will retrieve the Content-Type HTTP header from the headers[] object.

Parameters:
defaultValue Default value to return if the variable is not found.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espError, espGetProperty, espGetResult, espGetVar, espSetProperty, espSetVar, espSetStringVar, espWrite

int espGetVar ( EspRequest *  ep,
EspEnvType  oType,
char *  var,
MprVar *  value 
)

Synopsis:
Get the value of a standard ESP variable.
Overview:
ESP defines standard object variables that describe the request details. These include: application, server[], session[], request[], headers[], cookies[], files[], form[], application[], global[], and

int espReadVar ( EspRequest *  ep,
char *  var,
MprVar *  value 
)

Synopsis:
Read a variables value
Overview:
This function reads a variable without copying the data. Variables contain primitive types such as integers or floating point numbers. They may also contain strings or references to objects. This call returns a structure copy of the data. If the variable contains a string or object, then the string/object pointer will be copied and the return value will have a reference into the ESP object store.
Warning:
Take care when using this function, especially when multithreaded as it returns pointers into the ESP object store. If possible, use the espGetVar function if possible.
Parameters:
ep ESP request handle.
var Name of the variable to copy. Variable names may be fully qualified object.property refererence. I.e. they may contain "." or "[]". However, array indexes inside "[]" must be constant. If you require variable access with expresssion array indexes, use espEvalScript and define your script to just be the array reference.
value Pointer to a MprValue to contain the variable data.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espCopyVar, espCreateObjVar, espCreateProperty, espGetProperty, espGetResult, espGetVar, espSetVar

void espRedirect ( EspRequest *  ep,
int  code,
char *  url 
)

Synopsis:
Redirect the client browser to a new location.
Overview:
This call redirects the client's browser to a new URL. It responds to the current HTTP request from the client with a HTTP redirection response. The redirection may be to another page within the current web, or it may be to a different server. This call will set the "Location" HTTP header and the HTTP response code. As ESP bufferes output data, you may issue this call after calling espWrite. In this case, any written data will be discarded. If you wish to discontinue processing the remainder of the ESP script, you should call espSetExitStatus.
Parameters:
ep ESP request handle.
code HTTP response code. Set to zero to use the default code of 302 which is the HTTP response code for a temporary redirection.
url URL to redirect to.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espSetHeader, espSetResponseCode, espSetReturn, espWrite

int espRunFunction ( EspRequest *  ep,
MprVar *  obj,
char *  functionName,
MprArray args 
)

Synopsis:
Run a function.
Overview:
This call runs the named function that has been previously defined using espDefineFunction, espDefineCFunction or espDefineStringCFunction. NOTE: the target function may thus be a pure JavaScript function or it may be a C function bound to a JavaScript function name.
Parameters:
ep ESP request handle.
obj If the function is to be run as an object method, then obj should be set to the relevant object. Otherwise, set obj to NULL.
functionName JavaScript function name to associate with this C function.
args Array of arguments to pass to the function. This array must be created using mprCreateArray.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineFunction, espDefineCFunction, espDefineStringCFunction, espEvalFile, espEvalScript, espGetResult

void espSetHeader ( EspRequest *  ep,
char *  header,
bool  allowMultiple 
)

Synopsis:
Set a HTTP response header
Overview:
This call defines a HTTP response header. The value argument should contain a string of the format "keyword: value". If a header has already been defined and allowMultiple is false, the header will be overwritten. If allowMultiple is true, the new header will be appended to the response headers and the existing header will also be output. NOTE: case does not matter in the header keyword.
Parameters:
ep ESP request handle.
header Header string
allowMultiple If false, overwrite existing headers with the same keyword. If true, all headers are output.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espError, espGetResult, espGetRequestHandle, espGetScriptHandle, espRedirect, espSetResponseCode, espSetReturn, espWrite

MprVar* espSetProperty ( MprVar *  obj,
char *  property,
MprVar *  newValue 
)

Synopsis:
Update a property in the nominated object.
Overview:
This call updates a property's value. If it does not exist, the property is first created.
Parameters:
obj The object in which to update the property.
property Name of the variable. This name is not used for access and is primarily used for debugging.
newValue Pointer to a MprVar with which to initialize the property.
Returns:
Returns the created property. If a memory allocation failure occurs, the returned object will have a type set to MPR_TYPE_UNDEFINED.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espCreateProperty, espGetProperty, espReadVar, espWriteVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

MprVar* espSetPropertyValue ( MprVar *  obj,
char *  property,
MprVar  newValue 
)

Synopsis:
Update a property in the nominated object.
Overview:
This call updates a property's value. If it does not exist, the property is first created.
Parameters:
obj The object in which to update the property.
property Name of the variable. This name is not used for access and is primarily used for debugging.
newValue MprVar value with which to initialize the property.
Returns:
Returns the created property. If a memory allocation failure occurs, the returned object will have a type set to MPR_TYPE_UNDEFINED.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espCreateProperty, espGetProperty, espReadVar, espSetProperty, espWriteVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

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

void espSetReturnString ( EspRequest *  ep,
char *  str 
)

Synopsis:
Set the ESP function return value to a string value.
Overview:
This call sets the return result value of an ESP function that has been bound to a JavaScript function via espDefineCMethod. This call converts the supplied string to an ESP variable. If you need to return types other than a string, use espSetReturn.
Parameters:
ep ESP request handle.
str Return string value.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espRunFunction, espSetHeader, espSetResponseCode, espSetReturn, espWrite

void espSetStringVar ( EspRequest *  ep,
EspEnvType  oType,
char *  var,
char *  value 
)

Synopsis:
Set a string variable value in a standard ESP array.
Overview:
This call creates or updates the value of a string variable in one of the standard ESP variables arrays: application, server[], session[], request[], headers[], cookies[], files[], form[], application[], global[], and local[]. This call indexes into one of these object arrays to set a specific variable setting. If the variable does not already exist, it is created. Otherwise its value is updated.
Parameters:
ep ESP request handle.
oType Object index. Must be one of: ESP_SERVER_OBJ, ESP_SESSION_OBJ, ESP_REQUEST_OBJ, ESP_HEADERS_OBJ, ESP_COOKIES, ESP_FILES, ESP_FORM_OBJ, ESP_APPLICATION_OBJ, ESP_GLOBAL_OBJ, ESP_LOCAL_OBJ
var Name of the variable to set. For example:
    espSetStringVar(ep, ESP_SESSION_OBJ, "name", "Peter Hale");

Parameters:
value String value to use in setting the variable.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espError, espGetResult, espGetVar, espGetStringVar, espGetResult, espReadVar, espSetVar, espWrite, espWriteVar

void espSetVar ( EspRequest *  ep,
EspEnvType  oType,
char *  var,
MprVar  value 
)

Synopsis:
Set a variable value in a standard ESP array.
Overview:
This call creates or updates the value of a variable in one of the standard ESP variables arrays: application, server[], session[], request[], headers[], cookies[], files[], form[], application[], global[], and local[]. This call indexes into one of these object arrays to set a specific variable setting. If the variable does not already exist, it is created. Otherwise its value is updated.
Parameters:
ep ESP request handle.
oType Object index. Must be one of: ESP_SERVER_OBJ, ESP_SESSION_OBJ, ESP_REQUEST_OBJ, ESP_HEADERS_OBJ, ESP_COOKIES, ESP_FILES, ESP_FORM_OBJ, ESP_APPLICATION_OBJ, ESP_GLOBAL_OBJ, ESP_LOCAL_OBJ
var Name of the variable to set. For example:
            espSetVar(ep, ESP_SESSION_OBJ, "name", 
                mprCreateStringVar("Peter Hale", 0));

Parameters:
value Instance of a MprVar type describing the value to set.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espError, espGetResult, espGetVar, espGetStringVar, espGetResult, espReadVar, espSetStringVar, espWrite, espWriteVar

int espUnsetVar ( EspRequest *  ep,
EspEnvType  oType,
char *  var 
)

Synopsis:
Unset a string variable value in a standard ESP array.
Overview:
This call removes a string variable in one of the standard ESP variables arrays: application, server[], session[], request[], headers[], cookies[], files[], form[], application[], global[], and local[]. This call indexes into one of these object arrays to remove the specified variable setting.
Parameters:
ep ESP request handle.
oType Object index. Must be one of: ESP_SERVER_OBJ, ESP_SESSION_OBJ, ESP_REQUEST_OBJ, ESP_HEADERS_OBJ, ESP_COOKIES, ESP_FILES, ESP_FORM_OBJ, ESP_APPLICATION_OBJ, ESP_GLOBAL_OBJ, ESP_LOCAL_OBJ
var Name of the variable to set. For delete:
    espSetStringVar(ep, ESP_SESSION_OBJ, "priority");
Returns:
Returns zero for success, otherwise a negative MPR error code.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espError, espGetResult, espGetVar, espGetStringVar, espGetResult, espSetVar, espWrite

int espWrite ( EspRequest *  ep,
char *  buf,
int  size 
)

Synopsis:
Write response data back to the client's browser.
Overview:
This call writes the block of data in buf back to the client's browser. The data is buffered up to a configurable limit. If the maximum ESP buffer limit is exceeded, the data will be written to the client as required after first writing all previously buffered data included any HTTP headers.
Parameters:
ep ESP request handle.
buf Pointer to a buffer containing the data to be written.
size Length of the data buffer.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWriteFmt

int espWriteFmt ( EspRequest *  ep,
char *  fmt,
  ... 
)

Synopsis:
Write formatted response data back to the client's browser.
Overview:
This call formats a string and then writes it to the client's browser. The data is buffered up to a configurable limit. If the maximum ESP buffer limit is exceeded, the data will be written to the client as required after first writing all previously buffered data included any HTTP headers.
Parameters:
ep ESP request handle.
fmt Printf style format string
... Format string arguments
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWrite

int espWriteVar ( EspRequest *  ep,
char *  var,
MprVar *  value 
)

Synopsis:
Write a variables value
Overview:
This function updates a variable's value in the ESP object store. Variables contain primitive types such as integers or floating point numbers. They may also contain strings or references to objects. This call will do a "shallow" copy of the supplied variable. It will copy strings and primitive types. However, it will not copy objects. Rather, it will increment the supplied object's reference counter.
If the variable does not already exist, this function will return an error. If you need to create a property, use espCreateProperty. If possible, use the espSetVar function which will create or update a variable as required.
Parameters:
ep ESP request handle.
var Name of the variable to copy. Variable names may be fully qualified object.property refererence. I.e. they may contain "." or "[]". However, array indexes inside "[]" must be constant. If you require variable access with expresssion array indexes, use espEvalScript and define your script to just be the array reference.
value Pointer to a MprValue containing the data to write.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espGetResult, espGetVar, espCopyVar, espSetVar, espWriteVarValue

int espWriteVarValue ( EspRequest *  ep,
char *  var,
MprVar  value 
)

Synopsis:
Write a variables value
Overview:
This function is similar to espWriteVar but is passed its value to be written by "value". It is useful when writing variables created by using the MprVar constructors. For example:
    espWriteVarValue(ep, "application.hitRate", mprCreateIntegerVar(i + 1));

Variables contain primitive types such as integers or floating point numbers. They may also contain strings or references to objects. This call will do a "shallow" copy of the supplied variable. It will copy strings and primitive types. However, it will not copy objects. Rather, it will increment the supplied object's reference counter.

If the variable does not already exist, this function will return an error. If you need to create a property, use espCreateProperty. If possible, use the espSetVar function which will create or update a variable as required.

Parameters:
ep ESP request handle.
var Name of the variable to copy. Variable names may be fully qualified object.property refererence. I.e. they may contain "." or "[]". However, array indexes inside "[]" must be constant. If you require variable access with expresssion array indexes, use espEvalScript and define your script to just be the array reference.
value MprValue containing the data to write.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
Library:
libesp, libappweb
Configure options:
Requires BLD_FEATURE_ESP_MODULE.
See also:
espGetResult, espGetVar, espCopyVar, espSetVar, espWriteVar

© Mbedthis Software LLC, 2003-2006. All rights reserved. Mbedthis is a trademark of Mbedthis Software LLC.