mpr/mpr.h File Reference

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.


Classes
struct	Mpr
	The Mbedthis Portable Runtime (MPR). More...
struct	MprArray
	Generic Array Structure. 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...
class	MprSelectService
	Manage system select() call and the set of I/O handles. More...
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

)

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

mpr/mpr.h File Reference

Detailed Description

Data Types

Memory Allocation

Classes

Defines

Functions

Define Documentation

Function Documentation

See Also