Appweb HTTP Server C API

Detailed Description

Overview:

See capi.dox for additional documentation.

Typedefs
typedef void(*	MaEgiCb )(MaRequest *rq, cchar *script, cchar *uri, cchar *query, cchar *postData, int postLen)
typedef int(*	MaEspCb )(MaRequest *rq, int argc, char **argv)
Functions
int	maClientGetFd (MaClient *cp)
cchar *	maClientGetHost (MaClient *cp)
int	maClientGetPort (MaClient *cp)
int	maClientGetResponseCode (MaClient *cp)
cchar *	maClientGetResponseContent (MaClient *cp, int *contentLen)
cchar *	maClientGetResponseHeader (MaClient *cp)
cchar *	maClientGetResponseMessage (MaClient *cp)
void	maClientLock (MaClient *cp)
void	maClientResetAuth (MaClient *cp)
void	maClientSetKeepAlive (MaClient *cp, int on)
void	maClientSetPort (MaClient *cp, int num)
void	maClientSetRetries (MaClient *cp, int count)
void	maClientSetTimeout (MaClient *cp, int timeout)
void	maClientUnlock (MaClient *cp)
MaClient *	maCreateClient ()
void	maCreateEnvVars (MaRequest *rq, char *buf, int len)
MaHttp *	maCreateHttp ()
void	maDeleteHttp (MaHttp *http)
void	maDeleteServer (MaServer *server)
void	maDestroyClient (MaClient *cp)
int	maGetConfigErrorLine (MaServer *server)
cchar *	maGetCookie (MaRequest *rq)
void	maGetCrackedCookie (MaRequest *rq, char **name, char **value, char **path)
void	maSetResponseCode (MaRequest *rq, int code)
int	maStartServers (MaHttp *http)
void	maStopServers (MaHttp *http)
void	mprAddLogFileListener ()
int	mprGetAsyncSelectMode ()
int	mprGetFds (fd_set *readInterest, fd_set *writeInterest, fd_set *exceptInterest, int *maxFd, int *lastGet)
int	mprGetIdleTime ()
int	mprIsExiting ()
int	mprRunTasks ()
int	mprRunTimers ()
void	mprServiceEvents (int loopOnce, int maxTimeout)
void	mprServiceIO (int readyFds, fd_set *readFds, fd_set *writeFds, fd_set *exceptFds)
void	mprServiceWinIO (int sock, int winMask)
void	mprSetAsyncSelectMode (int on)
void	mprSetHwnd (HWND appHwnd)
void	mprSetSocketHwnd (HWND socketHwnd)
void	mprSetSocketMessage (int msgId)
int	mprStartMpr (int startFlags)
void	mprStopMpr ()
void	mprTerminate (int graceful)

Typedef Documentation

typedef void(* MaEgiCb)(MaRequest *rq, char *script, char *uri, char *query, char *postData, int postLen)

Synopsis: Callback function prototype for EGI forms. Overview: The Embedded Gateway Interface is an in-memory replacement for CGI. The MaEgiCb callback function will be called when the designated URL is posted to. Library: libcapiModule See also: MaEspCb

typedef int(* MaEspCb)(MaRequest *rq, int argc, char **argv)

char *query, char *postData, int postLen); Deprecated: Deprecated in release 2.0. Use EspCMethod instead. Synopsis: Callback function prototype for ESP procedures. Overview: Embedded Server Pages will call procedure callbacks when the corresponding scripting function is encountered in an ESP page. This interface is deprecated. Use the maEspDefineCMethod instead. Library: libcapiModule Configure options: Requires BLD_FEATURE_LEGACY_API. See also: EspCMethod, maEspDefineCMethod

Function Documentation

int maClientGetFd (  MaClient *  cp  )

Synopsis: Get the underlying socket file handle Overview: Return the O/S socket file handle for a connection. This call should only be issued and the socket handle only be used when the underlying socket is open. Parameters: cp  Client object handle Returns: Returns a socket handle. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort

cchar* maClientGetHost (  MaClient *  cp  )

Synopsis: Return the underlying host name for the client connection Overview: The default host can be set via maClientSetHost. This call returns the default host. Parameters: cp  Client object handle Returns: Returns a pointer to the default host string. The caller should not modify or free the returned string. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetFd, maCreateClientGetPort

int maClientGetPort (  MaClient *  cp  )

Synopsis: Get the underlying socket port number Overview: This call returns the TCP/IP port number of the server for this client request. Parameters: cp  Client object handle Returns: A positive integer port number. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetFd

int maClientGetResponseCode (  MaClient *  cp  )

Synopsis: Return the response HTTP code. Overview: Return the HTTP response code for a completed client request. This call should only be issued after calling maClientDoGetRequest or one of the other DoXxxRequest APIs. Parameters: cp  Client object handle Returns: Returns the HTTP response code. 200 normally means success. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientDoGetRequest, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

cchar* maClientGetResponseContent (  MaClient *  cp, int *  contentLen )

Synopsis: Get the response content Overview: Return the HTTP response data for a completed client request. This call should only be issued after calling maClientDoRequest or or one of the other DoXxxRequest APIs. Parameters: cp  Client object handle contentLen  Pointer to an integer to hold the length of the content buffer. Returns: Returns a pointer to the response content buffer. The caller should not free or modify the content data. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientDoGetRequest, maClientGetResponseHeader, maClientGetResponseMessage

cchar* maClientGetResponseHeader (  MaClient *  cp  )

Synopsis: Get the HTTP response header set Overview: Return the HTTP response header buffer. Parameters: cp  Client object handle Returns: Returns a pointer to a string representing the HTTP response headers. Each header will be terminated by "\r\n" or "\n". The last header will have an additional null character appended. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientDoGetRequest, maClientGetResponseMessage

cchar* maClientGetResponseMessage (  MaClient *  cp  )

Synopsis: Get the response error message. Overview: If the client request fails, the maClientGetResponseMessage API will return a text message describing the error. Parameters: cp  Client object handle Returns: Returns a pointer to the error message. The caller should not free or modify the error message. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientDoGetRequest

void maClientLock (  MaClient *  cp  )

Synopsis: Lock the client request object Overview: Lock the client so that it will be thread-safe. Parameters: cp  Client object handle Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort, maClientUnlock

void maClientResetAuth (  MaClient *  cp  )

Synopsis: Reset the authorization defaults defined for the client. Overview: This call will reset any settings defined via the maClientSetAuth API. Parameters: cp  Client object handle Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientSetAuth

void maClientSetKeepAlive (  MaClient *  cp, int  on )

Synopsis: Enable or disable the use of Keep-Alive by the client. Overview: Keep-Alive enables the client to reuse a network connection for subsequent requests. This results in a significant performance boost. Parameters: cp  Client object handle on  Set to non-zero to enable Keep-Alive. Stability classification: Evolving. Library: libcapiModule See also: maClientSetTimeout, maClientSetRetries, maCreateClient, maDestroyClient

void maClientSetPort (  MaClient *  cp, int  port )

Synopsis: Set the default port Overview: Set the default port to use for subsequent client requests. If a client URL does not contain a port portion, the default port is used. It defaults to port 80. Parameters: cp  Client object handle. port  Default port number. Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort

void maClientSetRetries (  MaClient *  cp, int  count )

Synopsis: Set the number of times the client will retry a request. Overview: Sometimes the client must retry a request. For example, the server may close a Keep-Alive socket connection just as the client is issuing another request. Parameters: cp  Client object handle count  Retry count. Stability classification: Evolving. Library: libcapiModule See also: maClientSetTimeout, maCreateClient, maDestroyClient

void maClientSetTimeout (  MaClient *  cp, int  timeout )

Synopsis: Set the client request timeout Overview: The client request will wait for the server to respond. The timeout period is the maximum time the client will be idle waiting for the server to respond with data. Parameters: cp  Client object handle timeout  Timeout in milliseconds. Stability classification: Evolving. Library: libcapiModule See also: maClientSetRetries, maCreateClient, maDestroyClient

void maClientUnlock (  MaClient *  cp  )

Synopsis: Unlock the client request object Overview: Unlock the client so that it will be thread-safe. Parameters: cp  Client object handle Stability classification: Evolving. Library: libcapiModule See also: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort, maClientUnlock

MaClient* maCreateClient (   )

Synopsis: Create a client object Overview: Creates a client object to use for a HTTP client request session Returns: A pointer to the MaClient object. Must call maDestroyClient to free. Stability classification: Evolving. Library: libcapiModule See also: maDestroyClient

void maCreateEnvVars (  MaRequest *  rq, char *  buf, int  len )

Synopsis: Decode a buffer and create environment variables. Overview: This call will URL decode the buffer and create Appweb environment variables for each keyword. Parameters: rq  Request handle buf  Buffer to decode into environment variables. Does not need to be null terminated. len  Length of buffer. Stability classification: Evolving. Library: libcapiModule See also: maDeleteHttp

MaHttp* maCreateHttp (   )

Synopsis: Create the application's HTTP object Overview: One MaHttp object is needed per application to manage all servers. Returns: Pointer to the MaHttp object. Stability classification: Evolving. Library: libcapiModule See also: maDeleteHttp

void maDeleteHttp (  MaHttp *  http  )

Synopsis: Delete the MaHttp object Overview: Before exiting an application, maDeleteHttp should be called to delete the MaHttp object. Parameters: http  MaHttp application object returned from maCreateHttp. Stability classification: Evolving. Library: libcapiModule See also: maCreateHttp, maCreateServer, maDeleteServer

void maDeleteServer (  MaServer *  server  )

Synopsis: Delete the MaServer object Overview: Before exiting an application, maDeleteServer should be called to delete the maServer object. Parameters: server  MaServer object returned from maCreateServer Stability classification: Evolving. Library: libcapiModule See also: maCreateHttp, maCreateServer, maDeleteHttp

void maDestroyClient (  MaClient *  cp  )

Synopsis: Destroy a client object Overview: Destroy and release all resources associated with a client object. Parameters: cp  Pointer to client object created via maCreateClient Stability classification: Evolving. Library: libcapiModule See also: maCreateClient

int maGetConfigErrorLine (  MaServer *  server  )

Synopsis: Return the current configuration file line number Overview: If a error is encountered when parsing the configuration file, maGetConfigErrorLine will return the current line number for error reporting purposes. Parameters: server  MaServer object returned from maCreateServer. Returns: The current line number (origin 1). Stability classification: Evolving. Library: libcapiModule See also: maConfigureServer

cchar* maGetCookie (  MaRequest *  rq  )

Synopsis: Return the request cookie. Overview: A client request may optionally include a HTTP cookie. This request returns a pointer to the cookie string. Parameters: rq  Request object handle Returns: Pointer to the cookie for the current request. Configure options: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION Stability classification: Evolving. Library: libcapiModule See also: maGetFileName, maGetCrackedCookie, maSetCookie

void maGetCrackedCookie (  MaRequest *  rq, char **  name, char **  value, char **  path )

Synopsis: Parse the request cookie. Overview: Parse the cookie and return the cookie's name, value and path. Parameters: rq  Request object handle name  Pointer to store allocated cookie's name. Caller must free. value  Pointer to store allocated cookie's value. Caller must free. path  Pointer to store allocated cookie's path. Caller must free. Configure options: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION Stability classification: Evolving. Library: libcapiModule See also: maGetCookie, maSetCookie

void maSetResponseCode (  MaRequest *  rq, int  code )

Synopsis: Set the HTTP request response code Overview: MOB Parameters: rq  Request object handle code  Numeric HTTP response code Library: libcapiModule See also:

int maStartServers (  MaHttp *  http  )

Synopsis: Activate HTTP servers. Synopsis: Start all the logical servers corresponding to the supplied MaHttp object. Once stared, the default server an any virtual servers will be activated and begin responding to HTTP requests. Parameters: http  MaHttp object created via maCreateHttp. Returns: Zero if successful, otherwise a MPR error code is returned. Stability classification: Evolving. Library: libcapiModule See also: maStopServers

void maStopServers (  MaHttp *  http  )

Synopsis: Deactivate HTTP servers Overview: Stop all the logical servers corresponding to the supplied MaHttp object. The servers will cease serving new requests immediately. Existing requests will continue to be processed by the handlers. Parameters: http  MaHttp object created via maCreateHttp Stability classification: Evolving. Library: libcapiModule See also: maStartServers

void mprAddLogFileListener (   )

Synopsis: Add a log listener that logs messages to a file. Overview: The MPR logging service permits multiple listeners to be registered to receive log messages. The LogFile listenener logs messages to the file specified by mprSetLogSpec. Stability classification: Evolving. Library: libcapiModule See also: mprSetLogSpec.

int mprGetAsyncSelectMode (   )

Synopsis: Return the current async select mode Overview: Return TRUE if the application is using windows async message select rather than the Unix select mechanism. Returns: TRUE if using async select. Stability classification: Evolving. Library: libcapiModule See also: mprSetAsyncSelectMode

int mprGetFds (  fd_set *  readInterest, fd_set *  writeInterest, fd_set *  exceptInterest, int *  maxFd, int *  lastGet )

Synopsis: Get the select file masks for all MPR file and sockets. Overview: The getFds call set the select I/O masks for all files and sockets in use by the MPR. Application event loops should call getFds and then OR in their own file descriptors before calling select using the masks. getFds will only modify the masks if the I/O interests of underlying file descriptors have changed. This means that getFds may not modify the masks if nothing much has changed. It is imperative that you not clear the masks between calls to getFds. Consequently, you should copy or save the masks before using them in select -- as select will modify the masks. If you want to force getFds to rebuild the masks, zero the value pointed to by the lastGet parameter. Parameters: readInterest  fd_set read interest mask writeInterest  fd_set write interest mask exceptInterest  Not used maxFd  Number of the highest file descriptor plus 1. This value is used by select. lastGet  Pointer to a timestamp integer used by getFds to manage when getFds was last run. The value pointed to should be initialized to -1. Returns: Returns TRUE if the masks were modified. Stability classification: Evolving. Library: libcapiModule See also: Mpr, mprGetIdleTime, mprRunTasks, mprRunTimers, mprServiceEvents

int mprGetIdleTime (   )

Synopsis: Return the time to wait till the next timer or event is due. Overview: Application event loops should call getIdleTime to determine how long they should sleep waiting for the next event to occur. Returns: Returns the number of milli-seconds till the next timer is due. Stability classification: Evolving. Library: libcapiModule See also: Mpr, runTimers

int mprIsExiting (   )

Synopsis: Determine if the application is exiting Overview: Returns TRUE if the application has been instructed to exit via mprTerminate. The application's main event loop should call isExiting whenever an event is detected. If isExiting returns TRUE, the application should gracefully exit. Returns: Returns TRUE if the application should exit. Stability classification: Evolving. Library: libcapiModule See also: Mpr

int mprRunTasks (   )

Synopsis: Execute all runable tasks Overview: If an application is running single-threaded, a call to runTasks will cause all queued Tasks to run. If multi-threaded, this call will have no effect. Application event loops should call runTasks before sleeping to ensure all tasks have had a chance to

int mprRunTimers (   )

Synopsis: Check timers and run all due timers. Overview: The runTimers method should be called by event loops to call any timers that are due. Returns: Returns TRUE if any timers were run. Stability classification: Evolving. Library: libcapiModule See also: Mpr, mprRunTasks, mprGetIdleTime, mprServiceEvents, mprServiceIO

void mprServiceEvents (  int  loopOnce, int  maxTimeout )

Synopsis: Service pending I/O events Overview: The MPR includes a unified I/O event service which efficiently processes I/O and invokes handlers for the underlying socket or file descriptors (on Unix). The MPR Socket layer will automatically integrate with the event mechanism so that I/O will cause the socket callback handlers to be invoked. mprServiceEvents is the primary mechanism to wait for I/O events and to cause them to be serviced. When called in multi-threaded applications, it will use a thread pool to continually service events until the application is instructed to exit via mprTerminate. When used in single-threaded applications, it is usually used within a larger custom event loop in the application. Parameters: loopOnce  Determines if mprServiceEvents will service only the current events or if it continue to service future events. maxTimeout  If loopOnce is TRUE, maxTimeout specifies the time to wait current events or if it continue to service future events. Remarks: Callers have several options when integrating the MPR and products using the MPR. You can: run a dedicated thread servicing events call serviceEvents from your own event loop create your own routine to service events using mprServiceEvents() as a prototype. Stability classification: Evolving. Library: libcapiModule See also: Mpr, mprServiceIO

void mprServiceIO (  int  readyFds, fd_set *  readFds, fd_set *  writeFds, fd_set *  exceptFds )

Synopsis: Service any pending I/O events Overview: serviceIO will analyse the provided select masks and will call all registered select handlers if an I/O event has occurred for that handler. MprSocket automatically creates select handlers on Unix and so the socket handlers will be also invoked if an I/O event occurs. This routine call be called on Windows, but the native windows message mechanism will provide higher throughput. Parameters: readyFds  Number of file descriptors with I/O events readFds  Read select mask writeFds  Write select mask exceptFds  Exception select mask Stability classification: Evolving. Library: libcapiModule See also: Mpr, mprGetIdleTime, mprRunTasks, mprRunTimers, mprGetFds, mprServiceEvents

void mprServiceWinIO (  int  sock, int  winMask )

Synopsis: Service any pending I/O events for a given socket (Windows) Overview: serviceIO service the I/O event specified in winMask for the given socket. Parameters: sock  Socket descriptor winMask  Windows Message I/O mask Stability classification: Evolving. Library: libcapiModule Scope: Windows See also: Mpr, mprGetIdleTime, mprRunTasks, mprRunTimers, mprGetFds, mprServiceEvents

void mprSetAsyncSelectMode (  int  on  )

Synopsis: Set the current async select mode Overview: Determine if the application is using windows async message select rather than the Unix select mechanism. Parameters: on  If TRUE, enable async select mechanism. Stability classification: Evolving. Library: libcapiModule See also: mprGetAsyncSelectMode

void mprSetHwnd (  HWND  appHwnd  )

Synopsis: Set the Window handle for the application Overview: Define the window handle for the application that the MPR and Appweb will use. Parameters: appHwnd  Application window handle Stability classification: Evolving. Library: libcapiModule Scope: Windows See also: mprSetSocketHwnd, mprServiceIO

void mprSetSocketHwnd (  HWND  socketHwnd  )

Synopsis: Set the socket handle for the application Overview: Define the window handle to use for socket events. Parameters: socketHwnd  Socket window handle Stability classification: Evolving. Library: libcapiModule Scope: Windows See also: mprSetHwnd, mprServiceIO

void mprSetSocketMessage (  int  msgId  )

Synopsis: Set the windows message type to use for socket messages Overview: Define the message type that the MPR will use in response to socket I/O events. Parameters: msgId  Windows message type. Stability classification: Evolving. Library: libcapiModule Scope: Windows See also: mprSetHwnd, mprSetSocketHwnd, mprServiceIO

int mprStartMpr (  int  startFlags  )

Synopsis: Starts the MPR services Overview: After creating the MPR object via mprCreateMpr, this call will fully initialize the MPR and to start all services. These services include thread services, the thread pool, timer services, select handlers and command execution services. Parameters: startFlags  Or the following flags: MPR_SERVICE_THREAD to create a service thread to run select. The thread will call mprServiceEvents to process I/O events. MPR_KILLABLE to create a pid file to support killing running MPRs. Returns: Returns zero if successful, otherwise returns a negative MPR error code. Stability classification: Evolving. Library: libcapiModule See also: mprCreateMpr, mprStopMpr

void mprStopMpr (   )

Synopsis: Stop the MPR services Overview: Applications should call mprStopMpr before exiting to gracefully terminate MPR processing. Stability classification: Evolving. Library: libcapiModule See also: mprCreateMpr, mprStartMpr

void mprTerminate (  int  graceful  )

Synopsis: Instruct the application to exit Overview: Calling mprTerminate will cause the MPR event loop to exit. When called with the graceful parameter set to TRUE, mprTerminate will set the isExiting flag and take no further action. The MPR event loop or the applications event loop will check this flag by calling mprIsExiting to determine if the application should exit. If graceful is FALSE, mprTerminate will call exit for an immediate application termination. Parameters: graceful  If FALSE, call exit and terminate the application immediately. If TRUE, set the MPR isExiting flag. Stability classification: Evolving. Library: libcapiModule See also: mprIsExiting, mprServiceEvents