Application contexts

Application contexts. More...

Typedefs
typedef struct LWMsgContext	LWMsgContext
	Application context. More...
typedef LWMsgStatus(*	LWMsgAllocFunction )(size_t size, void **out, void *data)
	Callback to allocate a memory object. More...
typedef void(*	LWMsgFreeFunction )(void *object, void *data)
	Callback to free a memory object. More...
typedef LWMsgStatus(*	LWMsgReallocFunction )(void *object, size_t old_size, size_t new_size, void **new_object, void *data)
	Callback to reallocate a memory object. More...
typedef LWMsgBool(*	LWMsgLogFunction )(LWMsgLogLevel level, const char *message, const char *function, const char *filename, unsigned int line, void *data)
	Logging callback. More...

Enumerations
enum	LWMsgLogLevel {   LWMSG_LOGLEVEL_ALWAYS,   LWMSG_LOGLEVEL_ERROR,   LWMSG_LOGLEVEL_WARNING,   LWMSG_LOGLEVEL_INFO,   LWMSG_LOGLEVEL_VERBOSE,   LWMSG_LOGLEVEL_DEBUG,   LWMSG_LOGLEVEL_TRACE }
	Log level. More...

Functions
LWMsgStatus	lwmsg_context_new (const LWMsgContext *parent, LWMsgContext **context)
	Create a new context. More...
void	lwmsg_context_delete (LWMsgContext *context)
	Delete a context. More...
void	lwmsg_context_set_memory_functions (LWMsgContext *context, LWMsgAllocFunction alloc, LWMsgFreeFunction free, LWMsgReallocFunction realloc, void *data)
	Set context memory management functions. More...
void	lwmsg_context_get_memory_functions (const LWMsgContext *context, LWMsgAllocFunction *alloc, LWMsgFreeFunction *free, LWMsgReallocFunction *realloc, void **data)
	Get context memory management functions. More...
void	lwmsg_context_set_log_function (LWMsgContext *context, LWMsgLogFunction logfn, void *data)
	Set log call function. More...

Detailed Description

The application context API allows you to customize the way lwmsg integrates with your application. You can override the default memory allocator or register a logging callback to receive logging messages from the library. Application contexts can be chained together in a hierarchy, with contexts lower in the hierarchy inheriting default settings from their parents.

Typedef Documentation

typedef struct LWMsgContext LWMsgContext

An opaque type which stores all application context information.

typedef LWMsgStatus(* LWMsgAllocFunction)(size_t size, void **out, void *data)

A callback used whenever memory that needs to be freed by the user is allocated – for example, when unmarshalling a data structure. The allocated space must initialized to zero. A request for zero bytes should not return NULL.

Parameters

[in]	size	the number of bytes to allocate
[out]	out	the allocated object
[in]	data	the user data pointer registered by lwmsg_context_set_memory_functions()

Return values

LWMSG_STATUS_SUCCESS	success
LWMSG_STATUS_MEMORY	out of memory

typedef void(* LWMsgFreeFunction)(void *object, void *data)

A callback used to free allocated memory.

Parameters

[in,out]	object	the memory object to free
[in]	data	the user data pointer registered by lwmsg_context_set_memory_functions()

typedef LWMsgStatus(* LWMsgReallocFunction)(void *object, size_t old_size, size_t new_size, void **new_object, void *data)

A callback used to reallocate a block of memory. If the reallocation grows the block, the additional space must be initialized to zero. If object is NULL, it should behave as a simple allocation with the same semantics as LWMsgAllocFunction.

Parameters

[in,out]	object	the original memory object
[in]	old_size	the size of the original memory object
[in]	new_size	the desired size
[out]	new_object	the reallocated object
[in]	data	the user data pointer registered by lwmsg_context_set_memory_functions()

Return values

LWMSG_STATUS_SUCCESS	success
LWMSG_STATUS_MEMORY	out of memory

typedef LWMsgBool(* LWMsgLogFunction)(LWMsgLogLevel level, const char *message, const char *function, const char *filename, unsigned int line, void *data)

A callback which is invoked by lwmsg when it has something to log. The function should indicate with its return value whether the message was actually logged (LWMSG_TRUE) or filtered (LWMSG_FALSE). If the message parameter is NULL, the function should not log anything but still return a value indicating whether it would have logged at the given log level. This mechanism is used to avoid expensive calculations to produce log messages that would be filtered out anyway.

Parameters

[in]	level	the level of message
[in]	message	the message
[in]	name	the name of the function that logged the message
[in]	filename	the name of the source file where the message was logged
[in]	line	the line number where the message was logged
[in]	data	a user data pointer registered with lwmsg_context_set_log_function().

Returns

LWMSG_TRUE if a message was or would be logged, LWMSG_FALSE otherwise

Enumeration Type Documentation

enum LWMsgLogLevel

Represents the severity of a log message

Enumerator
LWMSG_LOGLEVEL_ALWAYS	Message should always be logged
LWMSG_LOGLEVEL_ERROR	Error message
LWMSG_LOGLEVEL_WARNING	Warning message
LWMSG_LOGLEVEL_INFO	Informational message
LWMSG_LOGLEVEL_VERBOSE	Verbose message
LWMSG_LOGLEVEL_DEBUG	Debugging message
LWMSG_LOGLEVEL_TRACE	Trace message

Function Documentation

LWMsgStatus lwmsg_context_new	(	const LWMsgContext *	parent,
		LWMsgContext **	context
	)

Creates a new context with an optional parent. Options not explicitly set in the context will be inherited from the parent.

Parameters

parent	an optional parent context
context	the created context

Return values

LWMSG_STATUS_SUCCESS	success
LWMSG_STATUS_MEMORY	out of memory

void lwmsg_context_delete

(

LWMsgContext *

context

)

Deletes a context. It is the caller's responsibility to ensure that no other context, protocols, associations, etc. still reference the context.

Parameters

context

the context to delete

void lwmsg_context_set_memory_functions	(	LWMsgContext *	context,
		LWMsgAllocFunction	alloc,
		LWMsgFreeFunction	free,
		LWMsgReallocFunction	realloc,
		void *	data
	)

Sets the memory management callbacks associated with the context. If a function is set to null and a parent context is available, the function in the parent context will be used.

Parameters

[in,out]	context	the context
[in]	alloc	a callback to allocate memory
[in]	free	a callback to free memory
[in]	realloc	a callback to reallocate a memory block
[in]	data	a user data pointer which will be passed to the callbacks when they are invoked

void lwmsg_context_get_memory_functions	(	const LWMsgContext *	context,
		LWMsgAllocFunction *	alloc,
		LWMsgFreeFunction *	free,
		LWMsgReallocFunction *	realloc,
		void **	data
	)

Gets the memory management callbacks associated with the context. If a given function was not explicitly set, the default function provided by lwmsg will be returned.

Parameters

[in]	context	the context
[out]	alloc	a callback to allocate memory
[out]	free	a callback to free memory
[out]	realloc	a callback to reallocate a memory block
[out]	data	a user data pointer which should be passed to the callbacks when they are invoked

void lwmsg_context_set_log_function	(	LWMsgContext *	context,
		LWMsgLogFunction	logfn,
		void *	data
	)

Sets a callback function which will be called whenever lwmsg wishes to log a message.

Parameters

[in,out]	context	the context
[in]	logfn	the logging function
[in]	data	a user data pointer that will be passed to the logging function