/home/mob/svn/appWeb/1.2.3/mpr/mpr.h File Reference


Detailed Description

Header for the Mbedthis Portable Runtime (MPR).

This header defines the MPR public inteface for the C and C++ MPR APIs. It includes constants, structure and class definitions, API documentation and some inline code. It can only be included by both C and C++ programs.

APIs that return dynamically allocated strings always take a buffer as a parameter. APIs that require a user supplied buffer, always take a maximum length. APIs that return statically allocated strings will return them as a return value. NOTE: most of these APIs are not thread-safe if you also modify the underlying value at the same time.

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

To differentiate between "C" strings that are 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.

#include "config.h"
#include "mprOs.h"


Classes

class  Mpr
 The Mbedthis Portable Runtime (MPR) internal state class. More...

class  MprLink
 Link pointer class for objects in a MprList. More...

class  MprList
 List head class. More...

class  MprLogListener
 Represent a listener for MPR log messages. More...

class  MprLogToFile
 Log MPR messages to a file. More...


Defines

#define MPR_MAX_PATH   256
#define MPR_MAX_FNAME   128
#define MPR_MAX_STRING   512
#define MPR_MAX_URL   256
#define MPR_BUFSIZE   512
#define MPR_ERR_BASE   (-200)
#define MPR_ERR_GENERAL   (MPR_ERR_BASE - 1)
#define MPR_ERR_ABORTED   (MPR_ERR_BASE - 2)
#define MPR_ERR_ALREADY_EXISTS   (MPR_ERR_BASE - 3)
#define MPR_ERR_BAD_ARGS   (MPR_ERR_BASE - 4)
#define MPR_ERR_BAD_FORMAT   (MPR_ERR_BASE - 5)
#define MPR_ERR_BAD_HANDLE   (MPR_ERR_BASE - 6)
#define MPR_ERR_BAD_STATE   (MPR_ERR_BASE - 7)
#define MPR_ERR_BAD_SYNTAX   (MPR_ERR_BASE - 8)
#define MPR_ERR_BAD_TYPE   (MPR_ERR_BASE - 9)
#define MPR_ERR_BAD_VALUE   (MPR_ERR_BASE - 10)
#define MPR_ERR_BUSY   (MPR_ERR_BASE - 11)
#define MPR_ERR_CANT_ACCESS   (MPR_ERR_BASE - 12)
#define MPR_ERR_CANT_COMPLETE   (MPR_ERR_BASE - 13)
#define MPR_ERR_CANT_CREATE   (MPR_ERR_BASE - 14)
#define MPR_ERR_CANT_INITIALIZE   (MPR_ERR_BASE - 15)
#define MPR_ERR_CANT_OPEN   (MPR_ERR_BASE - 16)
#define MPR_ERR_CANT_READ   (MPR_ERR_BASE - 17)
#define MPR_ERR_CANT_WRITE   (MPR_ERR_BASE - 18)
#define MPR_ERR_DELETED   (MPR_ERR_BASE - 19)
#define MPR_ERR_NETWORK   (MPR_ERR_BASE - 20)
#define MPR_ERR_NOT_FOUND   (MPR_ERR_BASE - 21)
#define MPR_ERR_NOT_INITIALIZED   (MPR_ERR_BASE - 22)
#define MPR_ERR_NOT_READY   (MPR_ERR_BASE - 23)
#define MPR_ERR_READ_ONLY   (MPR_ERR_BASE - 24)
#define MPR_ERR_TIMEOUT   (MPR_ERR_BASE - 25)
#define MPR_ERR_TOO_MANY   (MPR_ERR_BASE - 26)
#define MPR_ERR_WONT_FIT   (MPR_ERR_BASE - 27)
#define MPR_ERR_WOULD_BLOCK   (MPR_ERR_BASE - 28)
#define MPR_ERR_MAX   (MPR_ERR_BASE - 29)
#define MPR_FATAL   0
#define MPR_ERROR   1
#define MPR_WARN   2
#define MPR_CONFIG   2
#define MPR_INFO   3
#define MPR_DEBUG   4
#define MPR_VERBOSE   9
#define MPR_LOG_MASK   0xf
#define MPR_TRAP   0x10
#define MPR_LOG   0x20
#define MPR_USER   0x40
#define MPR_ALERT   0x80
#define MPR_TRACE   0x100

Functions

void mprLog (int level, MprLogModule *module, char *fmt,...)
int mprPrintf (char *fmt,...)
int mprStaticPrintf (char *fmt,...)
int mprFprintf (int fd, char *fmt,...)
void mprSetDebugMode (bool on)
void mprError (char *file, int line, int flags, char *fmt,...)
void mprSetMemHandler (MprMemProc cback)
int mprCreateMemHeap (char *userBuf, int initialSize, int limit)
char * mprStrdup (const char *str)
void * mprMalloc (uint size)
void mprFree (void *ptr)
void * mprRealloc (void *ptr, uint size)
void mprRequestMemStats (bool on)

Define Documentation

#define MPR_ALERT   0x80
 

Send a management alert.

#define MPR_BUFSIZE   512
 

Reasonable size for buffers.

#define MPR_CONFIG   2
 

Essential configuration settings.

#define MPR_DEBUG   4
 

Debug information.

#define MPR_ERR_ABORTED   (MPR_ERR_BASE - 2)
 

Error code.

#define MPR_ERR_ALREADY_EXISTS   (MPR_ERR_BASE - 3)
 

Error code.

#define MPR_ERR_BAD_ARGS   (MPR_ERR_BASE - 4)
 

Error code.

#define MPR_ERR_BAD_FORMAT   (MPR_ERR_BASE - 5)
 

Error code.

#define MPR_ERR_BAD_HANDLE   (MPR_ERR_BASE - 6)
 

Error code.

#define MPR_ERR_BAD_STATE   (MPR_ERR_BASE - 7)
 

Error code.

#define MPR_ERR_BAD_SYNTAX   (MPR_ERR_BASE - 8)
 

Error code.

#define MPR_ERR_BAD_TYPE   (MPR_ERR_BASE - 9)
 

Error code.

#define MPR_ERR_BAD_VALUE   (MPR_ERR_BASE - 10)
 

Error code.

#define MPR_ERR_BASE   (-200)
 

Standard MPR return and error codes

#define MPR_ERR_BUSY   (MPR_ERR_BASE - 11)
 

Error code.

#define MPR_ERR_CANT_ACCESS   (MPR_ERR_BASE - 12)
 

Error code.

#define MPR_ERR_CANT_COMPLETE   (MPR_ERR_BASE - 13)
 

Error code.

#define MPR_ERR_CANT_CREATE   (MPR_ERR_BASE - 14)
 

Error code.

#define MPR_ERR_CANT_INITIALIZE   (MPR_ERR_BASE - 15)
 

Error code.

#define MPR_ERR_CANT_OPEN   (MPR_ERR_BASE - 16)
 

Error code.

#define MPR_ERR_CANT_READ   (MPR_ERR_BASE - 17)
 

Error code.

#define MPR_ERR_CANT_WRITE   (MPR_ERR_BASE - 18)
 

Error code.

#define MPR_ERR_DELETED   (MPR_ERR_BASE - 19)
 

Error code.

#define MPR_ERR_GENERAL   (MPR_ERR_BASE - 1)
 

Error code.

#define MPR_ERR_MAX   (MPR_ERR_BASE - 29)
 

Error code.

#define MPR_ERR_NETWORK   (MPR_ERR_BASE - 20)
 

Error code.

#define MPR_ERR_NOT_FOUND   (MPR_ERR_BASE - 21)
 

Error code.

#define MPR_ERR_NOT_INITIALIZED   (MPR_ERR_BASE - 22)
 

Error code.

#define MPR_ERR_NOT_READY   (MPR_ERR_BASE - 23)
 

Error code.

#define MPR_ERR_READ_ONLY   (MPR_ERR_BASE - 24)
 

Error code.

#define MPR_ERR_TIMEOUT   (MPR_ERR_BASE - 25)
 

Error code.

#define MPR_ERR_TOO_MANY   (MPR_ERR_BASE - 26)
 

Error code.

#define MPR_ERR_WONT_FIT   (MPR_ERR_BASE - 27)
 

Error code.

#define MPR_ERR_WOULD_BLOCK   (MPR_ERR_BASE - 28)
 

Error code.

#define MPR_ERROR   1
 

Hard error.

#define MPR_FATAL   0
 

Fatal error. Cant continue.

#define MPR_INFO   3
 

Informational only.

#define MPR_LOG   0x20
 

Log the error in the O/S event log.

#define MPR_LOG_MASK   0xf
 

Level mask.

#define MPR_MAX_FNAME   128
 

Reasonable length of a file path name to use in most cases where you know the expected file name and it is certain to be less than this limit.

#define MPR_MAX_PATH   256
 

Maximum length of a file path name. Reduced from the system maximum to save memory space.

#define MPR_MAX_STRING   512
 

Maximum string size.

#define MPR_MAX_URL   256
 

Reasonable size of a URL.

#define MPR_TRACE   0x100
 

Trace.

#define MPR_TRAP   0x10
 

Assert error -- trap in debugger.

#define MPR_USER   0x40
 

Display to the user.

#define MPR_VERBOSE   9
 

Highest level of trace.

#define MPR_WARN   2
 

Soft warning.


Function Documentation

int mprCreateMemHeap char *  userBuf,
int  initialSize,
int  limit
 

Synopsis:
Initialize the memory heap.
Overview:
Initialize the memory heap. The Mbedthis malloc subsystem offers several benefits:
  • It can pre-allocate memory to ensure memory allocations do not fail
  • It can allocate memory out of a static user buffer so that no dynamic memory allocation calls will be made at run-time. Ideal for VxWorks which tends to fragment memory with high dynamic memory loads.
  • It can impose memory allocation limits so that other programs are not compromised.
  • A memory handler is called on memory allocation failures.
Parameters:
userBuf NULL to dynamically allocate memory from the operating system. Set to a valid buffer of length size and memory will be allocated out of that buffer. Ideal for embedded systems such as VxWorks to ensure memory allocations cannot fail.
initialSize Define the size of the supplied user buffer, or if userBuf is NULL, it defines the initial size of dynamic memory to allocate.
limit Specify the maximum amount of dynamic memory to allocate.
Returns:
Returns zero if successful. Otherwise a negative MPR error code.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
mprMalloc, mprFree

void mprError char *  file,
int  line,
int  flags,
char *  fmt,
... 
 

Synopsis:
Log an error message.
Overview:
Send an error message to the MPR debug logging subsystem. The message will be passed to any registered listeners (see addListener).
Parameters:
file File name of the source containing the error.
line Line number in the source containing the error.
flags Error flags. Possible values are:
  • MPR_TRAP Trap to the debugger.
  • MPR_LOG Log the message to the log file.
  • MPR_USER Log and display visibly to the user (if not headless).
  • MPR_ALERT Log and send an alert to the user (not implemented).
Parameters:
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:
mprError will log the message and invoke all registered MprLogListeners.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
MprLogListener, mprLog

int mprFprintf int  fd,
char *  fmt,
... 
 

Parameters:
fd File descriptor. Note: this is not a FILE pointer type.
fmt Printf style format string
Returns:
Returns the number of bytes written
Stability Classification:
Evolving.
Library:
libappWeb
See also:
mprPrintf, mprLog

void mprFree void *  ptr  ) 
 

Synopsis:
Safe replacement for free.
Overview:
mprFree should be used to free memory allocated by mprMalloc, mprRealloc or mprCalloc.
Parameters:
ptr Memory to free. If NULL, take no action.
Remarks:
mprFree can reduce the overall application code size by allowing the memory block ptr to be NULL.
See also:
mprMalloc, mprCalloc, mprRealloc

void mprLog int  level,
MprLogModule *  module,
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
module MprLogModule doing the logging.
... 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:
MprLogListener, mprError

void* mprMalloc uint  size  ) 
 

Synopsis:
Safe replacement for malloc.
Overview:
mprMalloc should be used as a replacement for malloc wherever possible. It uses a fast, embedded memory allocator that is more deterministic with regard to fragmentation.
Parameters:
size Size of the memory block to allocate.
Returns:
Returns a pointer to the allocated block. This routine will never return NULL if the block cannot be allocated. Rather the memory exhaustion handler specified by mprSetMemHandler will be called to allow global recovery.
See also:
mprFree, mprRealloc, mprCalloc, mprSetMemHandler

int mprPrintf char *  fmt,
... 
 

Synopsis:
Compact printf. This will use less memory than the standard printf
Overview:
Linking without printf and all its derivatives will save memory for applications that demand minimal footprint. The MPR can be build without using any printf routines.
Parameters:
fmt Printf style format string
Returns:
Returns the number of bytes written
Stability Classification:
Evolving.
Library:
libappWeb
See also:
MprLogListener, mprLog

void* mprRealloc void *  ptr,
uint  size
 

Synopsis:
Safe replacement for realloc
Overview:
mprRealloc should be used to reallocate memory blocks that have been allocated with mprMalloc or mprStrdup.
Parameters:
ptr Memory to reallocate. If NULL, call malloc.
size New size of the required memory block.
Returns:
Returns a pointer to the newly allocated memory block.
Remarks:
Do not mix calls to realloc and mprRealloc.

void mprRequestMemStats bool  on  ) 
 

Synopsis:
Output a memory statistics report to stdout on program exit.
Parameters:
on TRUE if memory statistics are required

void mprSetDebugMode bool  on  ) 
 

Turn on debug mode. Various timeouts and timers are disabled to make debugging easier.

void mprSetMemHandler MprMemProc  cback  ) 
 

Define a memory callback to be called if all available memory is exhausted.

int mprStaticPrintf char *  fmt,
... 
 

Synopsis:
Print a message to the applications standard output without allocating memory.
Overview:
Normal Printf routines may allocate dynamic memory when parsing the format string. mprStaticPrintf uses a static buffer and will never allocate dynamic memory. It is suitable for use by low-level handlers that must not error when doing output.
Parameters:
fmt Printf style format string
Returns:
Returns the number of bytes written
Remarks:
The maximum output is MPR_MAX_STRING - 1.
Stability Classification:
Evolving.
Library:
libappWeb
See also:
mprPrintf, mprLog

char* mprStrdup const char *  str  ) 
 

Synopsis:
Safe replacement for strdup
Overview:
mprStrdup() should be used as a replacement for strdup wherever possible. It allows the strdup to be copied to be NULL, in which case it will allocate an empty string.
Parameters:
str Pointer to string to duplicate. If str is NULL, allocate a new string containing only a trailing NULL character.
Returns:
Returns an allocated string including trailing null.
Remarks:
Memory allocated via mprStrdup() must be freed via mprFree().
See also:
mprFree, mprMalloc, mprRealloc, mprCalloc

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