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	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)
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	espReadProperty (MprVar dest, MprVar prop)
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	espWriteProperty (MprVar prop, MprVar newValue)
int	espWritePropertyValue (MprVar *prop, MprVar newValue)
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.

See also:: espCreateObjVar, espCreateProperty, espGetProperty, espGetResult, espGetVar, espReadVar, espSetVar, mprCopyVar, mprDupVar

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.

See also:: 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.

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.

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.

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.

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.

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.

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.

See also:: espGetResult, espGetVar, espCopyVar, espSetVar, espWriteVar

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.

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.

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.

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.

See also:: espGetNextProperty, espGetProperty, espGetPropertyCount, espGetVar, espReadProperty, espSetVar, espWriteProperty

MprVar* espGetGlobalObject

(

EspRequest *

)

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.

See also:: espError, espGetLocalObject, espGetProperty, espGetVar, espGetStringVar, espGetResult, espSetProperty

MprVar* espGetLocalObject

(

EspRequest *

)

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.

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.

See also:: espGetFirstProperty, espGetProperty, espGetPropertyCount, espGetVar, espReadProperty, espSetVar, espWriteProperty

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.

See also:: espCreateProperty, espCreateObjVar, espDeleteProperty, espReadProperty, espReadVar, espSetProperty, espWriteProperty, 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.

See also:: espGetFirstProperty, espGetNextProperty, espGetProperty, espGetVar espReadProperty, espSetVar, espSetStringVar, espWriteProperty

EspHandle espGetRequestHandle

(

EspRequest *

)

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.

See also:: espDefineCFunction, espError, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWrite

MprVar* espGetResult

(

EspRequest *

)

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.

See also:: espDefineCFunction, espError, espGetRequestHandle, espGetScriptHandle, espRedirect, espRunFunction, espSetHeader, espSetResponseCode, espSetReturn, espWrite

EjsId espGetScriptHandle

(

EspRequest *

)

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.

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.

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 espReadProperty	(	MprVar *	dest,
		MprVar *	prop
	)

Synopsis:: Read a property's value.

Overview:: This call reads a property's value and stores a copy of its value in dest. It is assumed that the caller has obtained a property/// reference via espGetProperty or via espCreateProperty. The espReadProperty call reads the data and invokes any registered trigger routines.

No data objects or strings are copied when reading. Thus the caller does not need to call mprDestroyVar on the returned value.

Parameters:

dest	Pointer to a MprVar to hold the read value of the property.
prop	The object in which to delete the property.

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.

See also:: espCreateProperty, espCreateObjVar, espDeleteProperty, espGetProperty, espReadVar, espWriteProperty, espWriteVar mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar

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.

See also:: espCopyVar, espCreateObjVar, espCreateProperty, espGetProperty, espGetResult, espGetVar, espSetVar, mprReadProperty, mpr

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.

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.

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.

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.

See also:: espDefineCFunction, espCreateProperty, espGetProperty, espReadProperty, espReadVar, espWriteProperty, 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.

See also:: espDefineCFunction, espCreateProperty, espGetProperty, espReadProperty, espReadVar, espSetProperty, espWriteProperty, 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.

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.

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.

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.

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.

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:

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.

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.

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.

See also:: espDefineCFunction, espError, espGetRequestHandle, espGetResult, espGetScriptHandle, espRedirect, espSetHeader, espSetResponseCode, espSetReturn, espWrite

int espWriteProperty	(	MprVar *	prop,
		MprVar *	newValue
	)

Synopsis:: Update a property's value.

Overview:: This call updates a property's value and invokes any registered triggers. It is assumed that the caller has obtained a property reference via espGetProperty or via espCreateProperty.

Parameters:

prop	Pointer to the property to update.
newValue	Pointer to a MprVar value with which to update the property.

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

Library:: libesp, libappWeb

Configure options:: Requires BLD_FEATURE_ESP.

See also:: espDefineCFunction, espCreateProperty, espDeleteProperty, espGetProperty, espReadProperty, espReadVar, espSetProperty, espSetPropertyValue, espWritePropertyValue, espWriteVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

int espWritePropertyValue	(	MprVar *	prop,
		MprVar	newValue
	)

Synopsis:: Update a property's value.

Overview:: This call updates a property's value and invokes any registered triggers. It is assumed that the caller has obtained a property reference via espGetProperty or via espCreateProperty. This call is very similar to espWriteProperty except that the new value is passed by "value" and not by reference.

Parameters:

prop	Pointer to the property to update.
newValue	MprVar value with which to update the property.

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

Library:: libesp, libappWeb

Configure options:: Requires BLD_FEATURE_ESP.

See also:: espDefineCFunction, espCreateProperty, espDeleteProperty, espGetProperty, espReadProperty, espReadVar, espSetProperty, espSetPropertyValue, espWriteProperty, espWriteVar, mprCopyVar, mprCreateIntegerVar, mprCreateStringVar, mprDestroyVar,

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.

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.

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.

See also:: espGetResult, espGetVar, espCopyVar, espSetVar, espWriteVar

Embedded Server Pages C API

Detailed Description

Typedefs

Functions

Typedef Documentation

Function Documentation

See Also