/home/mob/svn/appWeb/1.2.3/http/modules/capiModule.cpp File Reference


Detailed Description

C language interface module.

#include "http/http.h"
#include "http/modules/espHandler.h"
#include "http/capi.h"


Functions

int mprCreateMpr (char *appName)
void mprDeleteMpr ()
int mprGetFds (fd_set *readInterest, fd_set *writeInterest, fd_set *exceptInterest, int *maxFd, int *lastGet)
int mprGetIdleTime ()
int mprIsExiting ()
int mprRunTasks ()
int mprRunTimers ()
void mprServiceIO (int readyFds, fd_set *readFds, fd_set *writeFds, fd_set *exceptFds)
int mprGetAsyncSelectMode ()
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 mprServiceEvents (int loopOnce, int maxTimeout)
void mprAddLogFileListener ()
void mprSetLogSpec (char *logSpec)
void mprTrace (int level, char *fmt,...)
void mprTerminate (int graceful)
MaHttpmaCreateHttp ()
void maDeleteHttp (MaHttp *http)
void maDeleteServer (MaServer *server)
MaServermaCreateServer (MaHttp *http, char *name, char *serverRoot)
int maConfigureServer (MaServer *server, char *configFile, int outputConfig)
int maGetConfigErrorLine (MaServer *server)
int maStartServers (MaHttp *http)
void maStopServers (MaHttp *http)
int maDefineEsp (char *name, MaEspCb fn)
void maRequestError (MaRequest *rq, int code, char *msg,...)
char * maGetFileName (MaRequest *rq)
char * maGetCookie (MaRequest *rq)
char * maGetVar (MaRequest *rq, char *var, char *defaultValue)
void maCreateEnvVars (MaRequest *rq, char *buf, int len)
void maRedirect (MaRequest *rq, int code, char *url)
int maSetFileName (MaRequest *rq, char *fileName)
void maSetVar (MaRequest *rq, char *var, char *value)
int maWrite (MaRequest *rq, char *buf, int nChars)
int maWriteFmt (MaRequest *rq, char *fmt,...)
int maWriteStr (MaRequest *rq, char *s)
void maSetResult (MaRequest *rq, char *s)

Function Documentation

int maConfigureServer MaServer server,
char *  configFile,
int  outputConfig
 

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.
outputConfig If TRUE, output the parsed configuration settings to the standard output (console).
Returns:
Returns zero if successful, otherwise a negative MPR error code.
Library:
libappWeb
See also:
maDeleteHttp

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

int maDefineEsp char *  name,
MaEspCb  fn
 

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

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:
libappWeb
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:
libappWeb
See also:
maCreateHttp, maCreateServer, maDeleteHttp

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:
libappWeb
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.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
maGetFileName

char* maGetFileName MaRequest rq  ) 
 

Synopsis:
Return the document file name to satisfy the current HTTP request.
Overview:
Certain URLs are mapped to corresponding documents in the file system. These may be HTML pages, CSS files or GIF/JPEG graphic files, among other file types. maGetFileName will return the local file system path to the document to return to the user. If the URL does not map to a local document, for example: EGI requests are served internally and do not map onto a local file name, then this call will not return meaningful data.
Parameters:
rq Request object handle
Returns:
Pointer to the local file name for the document. Returns empty string if the handler does not map the URL onto a local document.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
maSetFileName

char* maGetVar MaRequest rq,
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
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:
libappWeb
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:
libappWeb
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:
libappWeb
See also:
maWrite

int 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:
libappWeb
See also:
maGetFileName

void maSetResult MaRequest rq,
char *  s
 

Synopsis:
Set the result of an ESP procedure call.
Overview:
Set the result of an ESP procedure call. This value is returned from the ESP script call.
Parameters:
rq Request object handle.
s Pointer to string to use as the result.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
maWrite, maWriteFmt

void maSetVar MaRequest rq,
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.
var Name of environment variable to set.
value Value to set.
Stability Classification:
Evolving.
Library:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
See also:
mprDeleteMpr

void mprDeleteMpr  ) 
 

Synopsis:
Delete the MPR object
Overview:
This call will shutdown the MPR and terminate all MPR services. An application should call mprDeleteMpr before exiting.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
mprCreateMpr

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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
See also:
Mpr

int mprRunTasks  ) 
 

Returns:
Returns TRUE if any tasks were run.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
Mpr, mprRunTimers, mprGetIdleTime, mprServiceEvents, mprServiceIO

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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
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:
libappWeb
See also:
mprError

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