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]sizethe number of bytes to allocate
[out]outthe allocated object
[in]datathe user data pointer registered by lwmsg_context_set_memory_functions()
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
typedef void(* LWMsgFreeFunction)(void *object, void *data)

A callback used to free allocated memory.

Parameters
[in,out]objectthe memory object to free
[in]datathe 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]objectthe original memory object
[in]old_sizethe size of the original memory object
[in]new_sizethe desired size
[out]new_objectthe reallocated object
[in]datathe user data pointer registered by lwmsg_context_set_memory_functions()
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout 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]levelthe level of message
[in]messagethe message
[in]namethe name of the function that logged the message
[in]filenamethe name of the source file where the message was logged
[in]linethe line number where the message was logged
[in]dataa 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

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
parentan optional parent context
contextthe created context
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout 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
contextthe 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]contextthe context
[in]alloca callback to allocate memory
[in]freea callback to free memory
[in]realloca callback to reallocate a memory block
[in]dataa 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]contextthe context
[out]alloca callback to allocate memory
[out]freea callback to free memory
[out]realloca callback to reallocate a memory block
[out]dataa 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]contextthe context
[in]logfnthe logging function
[in]dataa user data pointer that will be passed to the logging function