http/modules/capiModule.cpp File Reference
Detailed DescriptionC language interface module.
|
Functions
|
int |
maConfigureServer (MaServer *server, char *configFile)
|
void |
maCreateEnvVars (MaRequest *rq, char *buf, int len)
|
MaHttp *
|
maCreateHttp ()
|
MaServer *
|
maCreateServer (MaHttp *http, char *name, char *serverRoot)
|
int |
maDefineEgiForm (char *name, MaEgiCb fn)
|
int |
maDefineEsp (char *name, MaEspCb fn)
|
void |
maDeleteHttp (MaHttp *http)
|
void |
maDeleteServer (MaServer *server)
|
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 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
|
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
|
|
- 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 maDefineEgiForm |
( |
char * |
name, |
|
|
MaEgiCb
|
fn |
|
) |
|
|
|
- Deprecated:
- Deprecated in release 2.0. Use ESP instead.
- Synopsis:
- Defines a C language EGI form
- Overview:
- This call links a C procedure to an EGI name. When a URL referencing the form is invoked, the EGI handler will ensure the nominated code is called. E.g. The URL:
http:
Could be enabled by calling maDefineEgiForm("myForm", myFormProc); EGI is deprecated as ESP and customer handlers provide the same functionality more effectively.
- Parameters:
-
name |
Name to publish the form as. This appears in the URL. Names must therefore only contain valid URL characters. |
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
|
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
|
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
|
|
- 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:
-
- 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
|
|
- 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
|
|
- 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
|
|
- 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
|
|
- 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
|
|
- 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
|
|
- 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
|
|
|