Mbedthis Home |  Documentation Home |  Administration |  Programmers Reference
AppWeb Documentation > Programmers Reference > Files > mpr.h

Mbedthis Portable Runtime C API

Detailed Description

Mbedthis Portable Runtime (MPR) API.

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.


Defines
#define  MPR_BUFSIZE   512
  Reasonable size for buffers.
#define  MPR_CONFIG   2
  Configuration settings trace level.
#define  MPR_DEBUG   4
  Debug information trace level.
#define  MPR_ERR_ABORTED   (MPR_ERR_BASE - 2)
  Action aborted.
#define  MPR_ERR_ALREADY_EXISTS   (MPR_ERR_BASE - 3)
  Item already exists.
#define  MPR_ERR_BAD_ARGS   (MPR_ERR_BASE - 4)
  Bad arguments or paramaeters.
#define  MPR_ERR_BAD_FORMAT   (MPR_ERR_BASE - 5)
  Bad input format.
#define  MPR_ERR_BAD_STATE   (MPR_ERR_BASE - 7)
  Module is in a bad state.
#define  MPR_ERR_BAD_SYNTAX   (MPR_ERR_BASE - 8)
  Input has bad syntax.
#define  MPR_ERR_BASE   (-200)
  Base error code.
#define  MPR_ERR_CANT_ACCESS   (MPR_ERR_BASE - 12)
  Can't access the file or resource.
#define  MPR_ERR_CANT_CREATE   (MPR_ERR_BASE - 14)
  Can't create the file or resource.
#define  MPR_ERR_CANT_OPEN   (MPR_ERR_BASE - 16)
  Can't open the file or resource.
#define  MPR_ERR_CANT_READ   (MPR_ERR_BASE - 17)
  Can't read from the file or resource.
#define  MPR_ERR_CANT_WRITE   (MPR_ERR_BASE - 18)
  Can't write to the file or resource.
#define  MPR_ERR_GENERAL   (MPR_ERR_BASE - 1)
  General error.
#define  MPR_ERR_NOT_INITIALIZED   (MPR_ERR_BASE - 22)
  Module or resource is not initialized.
#define  MPR_ERR_NOT_INITIALIZED   (MPR_ERR_BASE - 22)
  Module or resource is not initialized.
#define  MPR_ERROR   1
  Hard error trace level.
#define  MPR_FATAL   0
  Fatal error trace level. Cant continue.
#define  MPR_INFO   3
  Informational trace only.
#define  MPR_LOG   0x20
  Log to the O/S event log mprError flag.
#define  MPR_LOG_MASK   0xf
  Level mask.
#define  MPR_MAX_FNAME   128
  Reasonable size of a file name.

#define  MPR_MAX_PATH   256
  Reasonable max path name.

#define  MPR_MAX_URL   256
  Reasonable size of a URL.
#define  MPR_USER   0x40
  Display to the user mprError flag.
#define  MPR_VERBOSE   9
  Highest level of trace.
#define  MPR_WARN   2
  Soft warning trace level.

Functions
int  mprAddToArray (MprArray *array, void *item)
MprArray *  mprCreateArray ()
int  mprCreateMemHeap (char *userBuf, int initialSize, int limit)
void  mprDestroyArray (MprArray *array)
void  mprError (char *file, int line, int flags, char *fmt,...)
int  mprFprintf (int fd, char *fmt,...)
void  mprFree (void *ptr)
char *  mprGetCurrentThreadName ()
void  mprLog (int level, MprLogModule *module, char *fmt,...)
void *  mprMalloc (uint size)
int  mprPrintf (char *fmt,...)
void *  mprRealloc (void *ptr, uint size)
int  mprRemoveFromArray (MprArray *array, int index)
void  mprSetDebugMode (bool on)
int  mprStaticPrintf (char *fmt,...)
char *  mprStrdup (const char *str)

Define Documentation

#define MPR_MAX_FNAME   128
 

Reasonable size of a file name.

Reasonable length of a file name used by the product. Use where you know the expected file name and it is certain to be less than this limit.

#define MPR_MAX_PATH   256
 

Reasonable max path name.

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

Function Documentation

int mprAddToArray (  MprArray *  array,
void *  item
) 
 

Synopsis:
Add an item to an array
Overview:
Add the specified item to the array. The array must have been previously created via mprCreateArray. The array will grow as required to store the item.
Parameters:
array  Array pointer returned from mprCreateArray.
item  Pointer to item to store.
Returns:
Returns a positive integer array index for the inserted item. If the item cannot be inserted due to a memory allocation failure, -1 is returned.
Stability classification:
Evolving.
Library:
libappWeb
See also:
mprCreateArray, mprDestroyArray, mprRemoveFromArray

MprArray* mprCreateArray (   ) 
 

Synopsis:
Create an array
Overview:
Creates an empty array. MprArray's can store generic pointers and automatically grow as required when items are added to the array. Callers should invoke mprDestoryArray when finished with the array to release allocated storage.
Returns:
Returns a pointer to the array.
Stability classification:
Evolving.
Library:
libappWeb
See also:
mprAddToArray, mprDestroyArray, mprRemoveFromArray

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 mprDestroyArray (  MprArray *  array  ) 
 

Synopsis:
Destroy an array
Overview:
Destroys an array previously created via mprCreateArray. The array does not have to be empty prior to invoking this function.
Returns:
Returns a pointer to the array.
Stability classification:
Evolving.
Library:
libappWeb
See also:
mprAddToArray, mprCreateArray, mprRemoveFromArray

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).
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,
... 
) 
 

Synopsis:
Print a formatted message to a file descriptor
Overview:
This is a replacement for fprintf as part of the safe string MPR library. It minimizes memory use and uses a file descriptor instead

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

char* mprGetCurrentThreadName (   ) 
 

Synopsis:
Get the current thread name.
Overview:
Return a descriptive name for the current thread.
Returns:
Returns a pointer to the current threads name. Callers should not free this string.
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 wraps the standard malloc or if BLD_FEATURE_MALLOC is enabled, it will replace malloc with a fast, deterministic embedded memory allocator that is more deterministic with regard to

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.

int mprRemoveFromArray (  MprArray *  array,
int  index
) 
 

Synopsis:
Remove the nominated
Overview:
Removes the element specified by index, from the array. The array index is provided by mprAddToArray.
Returns:
Returns the number of remaining elements in the array. Returns zero when the array is empty.
Stability classification:
Evolving.
Library:
libappWeb
See also:
mprAddToArray, mprCreateArray, mprDestroyArray

void mprSetDebugMode (  bool  on  ) 
 

Synopsis:
Turn on debug mode.
Overview:
Debug mode disables timeouts and timers. This makes debugging much easier.
Parameters:
on  TRUE to disable debugging.
Stability classification:
Evolving.
Library:
libappWeb

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

See Also

API Overview
C++ API
C API
JavaScript API
Class List
File List

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