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) |
MaHttp * | maCreateHttp () |
MaServer * | maCreateServer (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 | |
|
) |
| | |
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 |
) |
|
- 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:
-
- 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:
-
- 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:
-
- Returns:
- A positive integer port number.
- Stability classification:
- Evolving.
- Library:
- libcapiModule
- See also:
- maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetFd
int maClientGetResponseCode |
( |
MaClient * |
cp |
) |
|
char * maClientGetResponseContent |
( |
MaClient * |
cp, |
|
|
int * |
contentLen | |
|
) |
| | |
char * maClientGetResponseHeader |
( |
MaClient * |
cp |
) |
|
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:
-
- 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 |
) |
|
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:
-
- 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 | |
|
) |
| | |
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 |
) |
|
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
- 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
- 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. |
- 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.
- Stability classification:
- Evolving.
- Library:
- libcapiModule
- See also:
- mprError
|
|