/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
|
Reasonable size for buffers.
|
|
Essential configuration settings.
|
#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_BASE (-200)
|
|
|
Standard MPR return and error codes |
#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_GENERAL (MPR_ERR_BASE - 1)
|
|
#define MPR_ERR_MAX (MPR_ERR_BASE - 29)
|
|
#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)
|
|
|
Fatal error. Cant continue.
|
|
Log the error in the O/S event log.
|
#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. |
|
Maximum length of a file path name. Reduced from the system maximum to save memory space. |
#define MPR_MAX_STRING 512
|
|
|
Reasonable size of a URL.
|
|
Assert error -- trap in debugger.
|
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
|
|
|