http/modules/capiModule.cpp File Reference


Detailed Description

C language interface module.


Functions

int maClientDoGetRequest (MaClient *cp, char *url)
int maClientDoHeadRequest (MaClient *cp, char *url)
int maClientDoOptionsRequest (MaClient *cp, char *url)
int maClientDoPostRequest (MaClient *cp, char *url, char *postData, int postLen)
int maClientDoTraceRequest (MaClient *cp, char *url)
int maClientGetFd (MaClient *cp)
char * maClientGetHeaderVar (MaClient *cp, char *key)
char * maClientGetHost (MaClient *cp)
int maClientGetPort (MaClient *cp)
int maClientGetResponseCode (MaClient *cp)
char * maClientGetResponseContent (MaClient *cp, int *contentLen)
char * maClientGetResponseHeader (MaClient *cp)
char * maClientGetResponseMessage (MaClient *cp)
void maClientLock (MaClient *cp)
void maClientResetAuth (MaClient *cp)
void maClientSetHost (MaClient *cp, char *host)
void maClientSetKeepAlive (MaClient *cp, int on)
void maClientSetPort (MaClient *cp, int port)
void maClientSetProxy (MaClient *cp, char *host, int port)
void maClientSetRetries (MaClient *cp, int count)
void maClientSetTimeout (MaClient *cp, int timeout)
void maClientUnlock (MaClient *cp)
int maConfigureServer (MaServer *server, char *configFile)
MaClient * maCreateClient ()
void maCreateEnvVars (MaRequest *rq, char *buf, int len)
MaHttpmaCreateHttp ()
MaServermaCreateServer (MaHttp *http, char *name, char *serverRoot)
int maDefineEsp (char *name, MaEspCb fn)
void maDeleteHttp (MaHttp *http)
void maDeleteServer (MaServer *server)
void maDestroyClient (MaClient *cp)
int maGetConfigErrorLine (MaServer *server)
char * maGetCookie (MaRequest *rq)
void maGetCrackedCookie (MaRequest *rq, char **name, char **value, char **path)
char * maGetVar (MaRequest *rq, MaEnvType objType, char *var, char *defaultValue)
void maRedirect (MaRequest *rq, int code, char *url)
void maRequestError (MaRequest *rq, int code, char *fmt,...)
void maSetCookie (MaRequest *rq, char *name, char *value, int lifetime, char *path, bool secure)
int maSetFileName (MaRequest *rq, char *fileName)
void maSetResponseCode (MaRequest *rq, int code)
void maSetVar (MaRequest *rq, MaEnvType objType, char *var, char *value)
int maStartServers (MaHttp *http)
void maStopServers (MaHttp *http)
int maWrite (MaRequest *rq, char *buf, int size)
int maWriteFmt (MaRequest *rq, char *fmt,...)
int maWriteStr (MaRequest *rq, char *s)
void mprAddLogFileListener ()
int mprCreateMpr (char *appName)
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 mprSetLogSpec (char *logSpec)
void mprSetSocketHwnd (HWND socketHwnd)
void mprSetSocketMessage (int msgId)
int mprStartMpr (int startFlags)
void mprStopMpr ()
void mprTerminate (int graceful)
void mprTrace (int level, char *fmt,...)

Function Documentation

int maClientDoGetRequest ( MaClient *  cp,
char *  url 
)

Synopsis:
Issue a HTTP GET request
Overview:
Issue a HTTP GET request for the given url and wait for a response.
Parameters:
cp Client object handle
url Server URL to get
Returns:
Returns zero if successful or else a non-zero error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoHeadRequest ( MaClient *  cp,
char *  url 
)

Synopsis:
Issue a HTTP HEAD request
Overview:
Issue a HTTP HEAD request for the given url and wait for a response. The HEAD request returns only the HTTP headers and no content body.
Parameters:
cp Client object handle
url Server URL to request the headers for.
Returns:
Returns zero if successful or else a non-zero error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoGetRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoOptionsRequest ( MaClient *  cp,
char *  url 
)

Synopsis:
Issue a HTTP OPTIONS request
Overview:
Issue a HTTP OPTIONS request for the given url and wait for a response. The OPTIONS request returns what HTTP methods are supported by the server.
Parameters:
cp Client object handle
url Server URL to request the options for.
Returns:
Returns zero if successful or else a non-zero error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoGetRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoPostRequest ( MaClient *  cp,
char *  url,
char *  postData,
int  postLen 
)

Synopsis:
Issue a HTTP POST request
Overview:
Issue a HTTP POST request for the given url and wait for a response. Post data may be supplied via the postData argument.
Parameters:
cp Client object handle.
url Server URL to post to.
postData Pointer to post data block
postLen Length of post data block
Returns:
Returns zero if successful or else a non-zero error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient, maClientDoGetRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoTraceRequest ( MaClient *  cp,
char *  url 
)

Synopsis:
Issue a HTTP TRACE request
Overview:
Issue a HTTP TRACE request for the given url and wait for a response.
Parameters:
cp Client object handle
url Server URL to request a trace of.
Returns:
Returns zero if successful or else a non-zero error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoGetRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

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

char * maClientGetHeaderVar ( MaClient *  cp,
char *  key 
)

Synopsis:
Get the value of a client HTTP response header
Overview:
HTTP requests have headers which detail information about the request itself.
Parameters:
cp Client object handle
key Lower case header value
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient

char * 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

char * 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

char * 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

char * 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 maClientSetHost ( MaClient *  cp,
char *  host 
)

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

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 maClientSetProxy ( MaClient *  cp,
char *  host,
int  port 
)

Synopsis:
Set the HTTP proxy.
Overview:
Set the HTTP proxy to use for subsequent client requests.
Parameters:
cp Client object handle
host HTTP proxy host name.
port HTTP proxy TCP/IP port number.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maCreateClient, maDestroyClient, maClientGetHost, maClientGetPort, maClientSetPort

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

int maConfigureServer ( MaServer server,
char *  configFile 
)

Synopsis:
configure the entire server from a configuration file.
Overview:
Servers are configured via an Apache-style configuration file. A server may listen on multiple ports and may contain multiple virtual hosts.
Parameters:
server Pointer to the MaServer object created via maCreateServer.
configFile Path of the configuration file.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
Library:
libcapiModule
Configure options:
Requires BLD_FEATURE_CONFIG_PARSE.
See also:
maDeleteHttp

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

MaServer * maCreateServer ( MaHttp http,
char *  name,
char *  serverRoot 
)

Synopsis:
Create a HTTP server.
Overview:
Creates a logical HTTP server that may consist of multiple virtual servers.
Parameters:
http Pointer to the MaHttp object created by maCreateHttp.
name Descriptive name to give to the server.
serverRoot Top level path of the directory containing the server.
Returns:
Pointer to the MaServer object
Stability classification:
Evolving.
Library:
libcapiModule
See also:

int maDefineEsp ( char *  name,
MaEspCb  fn 
)

Deprecated:
Deprecated in release 2.0. Use maEspDefineCMethod instead.
Synopsis:
Defines a C lanaguage ESP procedure
Overview:
This call links a C procedure to an ESP name. When a web page containing a call to the procedure, the ESP handler will ensure the nominated code is called.
Parameters:
name Name to use in the ESP web page for this ESP procedure.
fn C callback function to invoke.
Returns:
Zero if successful. Otherwise it returns an MPR error code.
Stability classification:
Deprecated.
Library:
libcapiModule
Configure options:
Requires BLD_FEATURE_LEGACY_API.
See also:
maEspDefineCMethod

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

char * 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

char * maGetVar ( MaRequest rq,
MaEnvType  objType,
char *  var,
char *  defaultValue 
)

Synopsis:
Return the value of the specified HTTP environment variable
Overview:
This call will query the value of HTTP environment variables. These variables are used by CGI, EGI and ESP handlers. ESP pages and EGI forms may access these variables.
Parameters:
rq Request object handle
objType Type of environment variable. Select from: MA_SERVER_OBJ MA_SESSION_OBJ MA_REQUEST_OBJ MA_HEADER_OBJ MA_COOKIE_OBJ MA_FILES_OBJ MA_FORM_OBJ MA_APPLICATION_OBJ MA_GLOBAL_OBJ MA_LOCAL_OBJ.
var Name of the variable to access.
defaultValue Default value to return if the variable is not defined.
Returns:
The value of the variable if it is defined. Otherwise the defaultValue is returned.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maSetVar

void maRedirect ( MaRequest rq,
int  code,
char *  url 
)

Synopsis:
Redirect the user's browser to a new location
Overview:
maRedirect will respond to the current request with a HTTP redirection (code 301). The redirection may be to another page with the current web, or it may be to a different server.
Parameters:
rq Request object handle
code HTTP redirection code
url URL representing the new location. May omit the "http://server/" prefix for redirections within the exiting web.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maRequestError

void maRequestError ( MaRequest rq,
int  code,
char *  fmt,
  ... 
)

Synopsis:
Return an error to the client (user's browser)
Overview:
If a handler encounters an error, it can call maRequestError to return the appropriate HTTP error code and message to the user's browser.
Parameters:
rq Request handle
code HTTP error code. E.g. 500 for an internal server error.
fmt Printf style format string followed by assocated arguments.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maWrite

void maSetCookie ( MaRequest rq,
char *  name,
char *  value,
int  lifetime,
char *  path,
bool  secure 
)

Synopsis:
Set a cookie to be defined in the client's browser
Overview:
This call will define a cookie which will be sent with the response to the client. Subsequent requests from the browser should then contain the cookie. It can be used to create and track user sessions.

eint maSetFileName ( MaRequest rq,
char *  fileName 
)

Synopsis:
Set the local file name for the document that satisfies this request.
Overview:
This call defines the local file name for a document which will be returned to the user's browser.
Parameters:
rq Request object handle.
fileName Path name in the local file system for the document.
Returns:
Returns zero if successful. Otherwise a negative MPR error code will be returned. On errors, maSetFileName will call requestError and will terminate the request.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maGetFileName

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:

void maSetVar ( MaRequest rq,
MaEnvType  objType,
char *  var,
char *  value 
)

Synopsis:
Set the value of a HTTP environment variable
Overview:
This call will define the value of an HTTP environment variable. These variables are used by CGI, EGI and ESP handlers. ESP pages and EGI forms may access these variables. The variable will be created if it does not exist. If it already exists, its value will be updated.
Parameters:
rq Request object handle.
objType Type of environment variable. Select from: MA_SERVER_OBJ MA_SESSION_OBJ MA_REQUEST_OBJ MA_HEADER_OBJ MA_COOKIE_OBJ MA_FILES_OBJ MA_FORM_OBJ MA_APPLICATION_OBJ MA_GLOBAL_OBJ MA_LOCAL_OBJ.
var Name of environment variable to set.
value Value to set.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maGetVar

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

int maWrite ( MaRequest rq,
char *  buf,
int  size 
)

Synopsis:
Write a block of data back to the user's browser.
Overview:
This call is the most efficient way to return data back to a user's browser.
Parameters:
rq Request object handle
buf Pointer to the data buffer to write
size Size of the buffer in bytes
Returns:
Number of bytes written. Should equal size. On errors, returns a negative MPR error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maWriteFmt, maWriteStr

int maWriteFmt ( MaRequest rq,
char *  fmt,
  ... 
)

Synopsis:
Write a formatted string back to the user's browser.
Overview:
Format a printf style string and write back to the browser.
Parameters:
rq Request object handle.
fmt Printf style format string followed by assocated arguments.
Returns:
Number of bytes written. On errors, returns a negative MPR error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maWrite, maWriteStr

int maWriteStr ( MaRequest rq,
char *  s 
)

Synopsis:
Write a string back to the user's browser.
Overview:
Write the string back to the browser.
Parameters:
rq Request object handle.
s Pointer to string to write.
Returns:
Number of bytes written. On errors, returns a negative MPR error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
maWrite, maWriteFmt

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 mprCreateMpr ( char *  appName  ) 

Synopsis:
Create an MPR instance for the application.
Overview:
To support AppWeb, an application needs the services of the Mbedthis Portable Runtime (MPR). This call activates the MPR and must be issued prior to any other AppWeb API call.
Parameters:
appName Name of the application. This is used for internal error reporting from AppWeb and the MPR.
Returns:
Zero if successful. Otherwise returns a negative MPR error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
mprDeleteMpr

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 mprSetLogSpec ( char *  logSpec  ) 

Synopsis:
Define the file to use for logging messages.
Overview:
This call specifies a log file specification to use with the LogFile listener. The logSpec parameter specifies the log file name and optionally specifies :
  • Log verbosity level
  • Maximum log file size
  • List of module names to log
Parameters:
logSpec Log file specification of the format:
        fileName[[,moduleName]...][:level][.maxSize]
Module names (if specified) are internal MPR names such as socket. This allows you to log trace from only designated modules. The level must be between 0 and 9 with 9 being the most verbose. A good normal level is 2. The maxSize specification is the size of the logfile in MB before rotating. When rotated, the old file will have a ".old" appended.
Returns:
Returns zero if successful. Otherwise returns a negative MPR error code.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
mprAddLogFileListener, mprLog, mprError

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

void mprTrace ( int  level,
char *  fmt,
  ... 
)

Synopsis:
Log a message to the MPR logging facility
Overview:
Log a message at the specified log level
Parameters:
level log level between 0 and 9, 9 being the most verbose level.
fmt Printf style format string. Variable number of arguments to
... Variable number of arguments for printf data
Returns:
Returns zero if successful. Otherwise a negative MPR error code.
Remarks:
mprLog is highly useful as a debugging aid when integrating or when developing new modules.
Stability classification:
Evolving.
Library:
libcapiModule
See also:
mprError

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