Mbedthis Portable Runtime C++ API

Detailed Description

The Mbedthis Portable Runtime (MPR).

The MPR provides a cross-platform embeddable set of management and communication services that form a portable run-time core. It provides management for logging, lists, memory, sockets, tasks, timers, threads. It also provides a foundation of safe routines for secure programming, that prevent help minimize buffer overflows and other security threats. The MPR APIs provide constants, structure and class definitions and can be used in both C and C++ programs.

Data Types

The Standard MPR types are: bool, char, uchar, short, ushort, int, uint, long, ulong, int64, uint64, float, double, MprStr

To differentiate between "C" strings that are dynamically allocated and plain C pointers, we use Str for dynamically allocated strings. In classes, Str means the class owns the storage for the string. When used for the return value or parameter of a method, it means the caller must free the memory using mprFree.

Memory Allocation

APIs that return dynamically allocated strings require the caller to pass a pointer to hold the allocated buffer as a parameter. APIs that require a user supplied buffer, always require a buffer maximum length parameter. APIs that return statically allocated strings will return them as a return value.

Warning:: Most of these APIs are not thread-safe. Be careful if you modify or delete the underlying data while accessing the resource from another thread.

Stability classification:: Evolving


Public Member Functions
void	addListener (MprLogListener *lp)
bool	getAsyncSelectMode ()
int	getIdleTime ()
bool	isExiting (void)
	Mpr (char *appName)
int	runTasks ()
int	runTimers ()
void	serviceEvents (bool loopOnce, int maxTimeout)
void	setAsyncSelectMode (bool on)
void	setHwnd (HWND appHwnd)
int	setLogSpec (char *spec)
void	setSocketHwnd (HWND socketHwnd)
void	setSocketMessage (int msgId)
int	start (int startFlags=0)
int	stop (bool immediateStop)
void	terminate (bool graceful=1)
	~Mpr ()

Constructor & Destructor Documentation

Mpr::Mpr

(

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:: ~Mpr

Mpr::~Mpr

(

)

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:: Mpr

Member Function Documentation

Mpr::addListener

(

MprLogListener *

)

Synopsis:: Register a listener for MPR log messages

Overview:: Listeners may register for MPR error and trace messages. Each registered listener will be called for all messages.

Parameters:

lp	Log listener to add

Remarks:: The MPR logging mechanism handles both trace at various levels and error messages.

Stability classification:: Evolving.

Library:: libappWeb

Configure options:: Requires BLD_FEATURE_LOG.

See also:: mprError, mprLog

bool Mpr::getAsyncSelectMode

(

)

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:: setAsyncSelectMode

int Mpr::getIdleTime

(

)

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

bool Mpr::isExiting

(

void

)

Synopsis:: Determine if the application is exiting

Overview:: Returns TRUE if the application has been instructed to exit via Mpr::terminate. The applications 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 Mpr::runTasks

(

)

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 Mpr::runTimers

(

)

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

void Mpr::serviceEvents	(	bool	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 serviceEvents() as a prototype.

Stability classification:: Evolving.

Library:: libappWeb

See also:: Mpr, serviceIO

void Mpr::setAsyncSelectMode

(

bool

)

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:: getAsyncSelectMode

void Mpr::setHwnd

(

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:: setSocketHwnd, serviceIO

int Mpr::setLogSpec

(

char *

spec

)

Synopsis:: Define a log file specification

Overview:: Creates the default log file specification for the MPR to use when logging events. Typically this will be via the default MprLogToFile log listener.

Parameters:

spec

Log file specification of the format:

fileName[:level][[,moduleName[:level]]...][.maxSize]

The level argument defines a message verbosity level and 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". Module names (if specified) are internal MPR names such as socket. This allows you to log messages from only designated modules. Each module may define its own trace level.

Returns:: Returns zero if successful. Otherwise returns a negative MPR error code.

Stability classification:: Evolving.

Library:: libappWeb

Configure options:: Requires BLD_FEATURE_LOG.

See also:: MprLogListener, MprLogToFile, mprLog, mprError

void Mpr::setSocketHwnd

(

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:: setHwnd, serviceIO

void Mpr::setSocketMessage

(

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:: setHwnd, setSocketHwnd, serviceIO

int Mpr::start

(

int

startFlags = 0

)

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:: Mpr, stop

int Mpr::stop

(

bool

immediateStop

)

Synopsis:: Stop the MPR services

Overview:: Applications should call stop before exiting to gracefully terminate MPR processing.

Stability classification:: Evolving.

Library:: libappWeb

See also:: Mpr, start

void Mpr::terminate

(

bool

graceful = 1

)

Synopsis:: Instruct the application to exit

Overview:: Calling terminate 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:: isExiting, serviceEvents

The documentation for this struct was generated from the following files:

http/capi.dox
mpr/mpr.h
mpr/mpr.cpp
mpr/mpr.dox
mpr/UNIX/daemon.cpp
mpr/UNIX/os.cpp
mpr/WIN/os.cpp

Mbedthis Portable Runtime C++ API

Detailed Description

Data Types

Memory Allocation

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

See Also