Data model

Data marshaling and manipulation. More...

Typedefs

typedef struct LWMsgDataContext LWMsgDataContext
 Data context. More...
 

Functions

LWMsgStatus lwmsg_data_context_new (const LWMsgContext *context, LWMsgDataContext **dcontext)
 Create a data context. More...
 
void lwmsg_data_context_delete (LWMsgDataContext *context)
 Delete a data context. More...
 
void lwmsg_data_context_set_byte_order (LWMsgDataContext *context, LWMsgByteOrder order)
 Set byte order. More...
 
LWMsgByteOrder lwmsg_data_context_get_byte_order (LWMsgDataContext *context)
 Get Byte order. More...
 
const LWMsgContextlwmsg_data_context_get_context (LWMsgDataContext *context)
 Get context. More...
 
LWMsgStatus lwmsg_data_free_graph (LWMsgDataContext *context, LWMsgTypeSpec *type, void *root)
 Free in-memory data graph. More...
 
LWMsgStatus lwmsg_data_destroy_graph (LWMsgDataContext *context, LWMsgTypeSpec *type, void *root)
 Destroy in-memory data graph. More...
 
void lwmsg_data_free_graph_cleanup (const LWMsgContext *context, LWMsgTypeSpec *type, void *root)
 Free in-memory data graph (guaranteed success) More...
 
void lwmsg_data_destroy_graph_cleanup (const LWMsgContext *context, LWMsgTypeSpec *type, void *root)
 Destroy in-memory data graph (guaranteed success) More...
 
LWMsgStatus lwmsg_data_marshal (LWMsgDataContext *context, LWMsgTypeSpec *type, void *object, LWMsgBuffer *buffer)
 Marshal a data structure. More...
 
LWMsgStatus lwmsg_data_marshal_flat (LWMsgDataContext *context, LWMsgTypeSpec *type, void *object, void *buffer, size_t length)
 Marshal a data structure into a simple buffer. More...
 
LWMsgStatus lwmsg_data_marshal_flat_alloc (LWMsgDataContext *context, LWMsgTypeSpec *type, void *object, void **buffer, size_t *length)
 Marshal a data structure while allocating a buffer. More...
 
LWMsgStatus lwmsg_data_unmarshal (LWMsgDataContext *context, LWMsgTypeSpec *type, LWMsgBuffer *buffer, void **out)
 Unmarshal a data structure. More...
 
LWMsgStatus lwmsg_data_unmarshal_into (LWMsgDataContext *context, LWMsgTypeSpec *type, LWMsgBuffer *buffer, void *object, size_t size)
 Unmarshal a data structure into pre-allocated memory. More...
 
LWMsgStatus lwmsg_data_unmarshal_flat (LWMsgDataContext *context, LWMsgTypeSpec *type, const void *buffer, size_t length, void **out)
 Unmarshal a data structure from a simple buffer. More...
 
LWMsgStatus lwmsg_data_print_graph_alloc (LWMsgDataContext *context, LWMsgTypeSpec *type, void *root, char **result)
 Print textual representation of a data graph to a string. More...
 
LWMsgStatus lwmsg_data_alloc_memory (LWMsgDataContext *context, size_t size, void **object)
 Allocate memory block. More...
 
void lwmsg_data_free_memory (LWMsgDataContext *context, void *object)
 Free memory block. More...
 

Detailed Description

The LWMsg data model allows ordinary C data structures to be converted to and from flat octet-stream representations. Before data structures can be processed, a type specification must be constructed which describes the layout and relationships of the structure fields. For details, see Types.

The top level object passed to or returned by marshaller operations must always be a pointer. As a convenience, certain top-level type specifications will automatically be promoted to pointers to accomodate this restriction:

All operations take a data context which controls tunable parameters of the data model:

In the event of an error, the data context can be queried for a human-readable diagnostic message. The data context may also reference an LWMsg context.

Typedef Documentation

An opqaue data context which facilitates all data model operations.

Function Documentation

LWMsgStatus lwmsg_data_context_new ( const LWMsgContext context,
LWMsgDataContext **  dcontext 
)

Creates a new data context with an optional context. Data operations which return allocated memory (e.g. lwmsg_data_unmarshal()) will use the context's memory management functions.

Parameters
[in]contextan optional context
[out]dcontextthe created data context
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
void lwmsg_data_context_delete ( LWMsgDataContext context)

Deletes the specified data context.

Parameters
[in,out]contextthe data context
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
void lwmsg_data_context_set_byte_order ( LWMsgDataContext context,
LWMsgByteOrder  order 
)

Sets the byte order which will be used for atomic data elements in subsequent marshal and unmarshal operations using the specified data context.

The default byte order is network byte order (big endian). This is the preferred order for data destined for long-term storage or transmission over a network.

Parameters
[out]contextthe data context
[in]orderthe data order
LWMsgByteOrder lwmsg_data_context_get_byte_order ( LWMsgDataContext context)

Gets the byte order which will be used for subsequent marshal and unmarshal operations on the specified data context.

Parameters
[in]contextthe data context
Returns
the current byte order
const LWMsgContext* lwmsg_data_context_get_context ( LWMsgDataContext context)

Gets the context which was given to lwmsg_data_context_new() when the specified data context was created.

Parameters
[in]contextthe data context
Returns
the context, or NULL if no context was given at creation time
LWMsgStatus lwmsg_data_free_graph ( LWMsgDataContext context,
LWMsgTypeSpec type,
void *  root 
)

Recursively frees the data graph rooted at root whose type is specified by type. Each contiguous memory object will be freed using the context given to lwmsg_data_context_new() when the specified data context was created.

The most common application of this function is to free the entire data graph allocated by a prior unmarshal operation, such as lwmsg_data_unmarshal().

Because the root of the data graph is always specified by a generic pointer, type is subject to pointer promotion.

Parameters
[in,out]contextthe data context
[in]typethe type of the root node of the graph
[in,out]rootthe root of the graph
LWMsgStatus lwmsg_data_destroy_graph ( LWMsgDataContext context,
LWMsgTypeSpec type,
void *  root 
)

Recursively destroys the data graph rooted at root whose type is specified by type. In contrast to lwmsg_data_free_graph(), the top-level structure is not freed. Every child memory object will be freed using the context given to lwmsg_data_context_new() when the specified data context was created.

Parameters
[in,out]contextthe data context
[in]typethe type of the root node of the graph
[in,out]rootthe root of the graph
void lwmsg_data_free_graph_cleanup ( const LWMsgContext context,
LWMsgTypeSpec type,
void *  root 
)

Like lwmsg_data_free_graph(), but guarantees success:

  • Does not require an LWMsgDataContext to be allocated (which could itself fail). Instead, an optional LWMsgContext can be passed in to specify the memory manager.
  • Does not return an error
Warning
This function has undefined behavior if the passed data graph is malformed.
Parameters
[in]contextan optional context
[in]typethe type of the root node of the graph
[in,out]rootthe root of the graph
void lwmsg_data_destroy_graph_cleanup ( const LWMsgContext context,
LWMsgTypeSpec type,
void *  root 
)

Like lwmsg_data_destroy_graph(), but guarantees success in the same way as lwmsg_data_free_graph_cleanup().

Warning
This function has undefined behavior if the passed data graph is malformed.
Parameters
[in]contextan optional context
[in]typethe type of the root node of the graph
[in,out]rootthe root of the graph
LWMsgStatus lwmsg_data_marshal ( LWMsgDataContext context,
LWMsgTypeSpec type,
void *  object,
LWMsgBuffer buffer 
)

Converts a data structure of the specified type to a flat, serialized form, storing the result in the provided marshalling buffer.

Parameters
[in,out]contextthe data context
[in]typethe type specification which describes the type of the data
[in]objectthe root of the data to marshal
[in,out]bufferthe marshalling buffer into which the result will be stored
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMSG_STATUS_OVERFLOWan arithmetic overflow occured while converting an integer to its marshalled form
LWMSG_STATUS_UNDERFLOWan arithmetic underflow occured while converting an integer to its marshalled form
...the provided context and buffer may raise implementation-specific errors
LWMsgStatus lwmsg_data_marshal_flat ( LWMsgDataContext context,
LWMsgTypeSpec type,
void *  object,
void *  buffer,
size_t  length 
)

Converts a data structure of the specified type to a flat, serialized form, storing the result in the provided simple buffer.

Parameters
[in,out]contextthe data context
[in]typethe type specification which describes the type of the data
[in]objectthe root of the data to marshal
[out]bufferthe buffer into which the result will be stored
[in]lengththe size of the buffer in bytes
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMSG_STATUS_OVERFLOWan arithmetic overflow occured while converting an integer to its marshalled form
LWMSG_STATUS_UNDERFLOWan arithmetic underflow occured while converting an integer to its marshalled form
LWMSG_STATUS_EOFthe buffer was not large enough to hold the entire serialized representation
LWMsgStatus lwmsg_data_marshal_flat_alloc ( LWMsgDataContext context,
LWMsgTypeSpec type,
void *  object,
void **  buffer,
size_t *  length 
)

Converts a data structure of the specified type to a flat, serialized form, automatically allocating sufficient space for the result. The buffer is allocated using the memory management functions in context passed to lwmsg_data_context_new().

Parameters
[in,out]contextthe data context
[in]typethe type specification which describes the type of the data
[in]objectthe root of the data to marshal
[out]bufferthe allocated buffer containing the serialized representation
[out]lengththe length of the buffer
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMSG_STATUS_OVERFLOWan arithmetic overflow occured while converting an integer to its marshalled form
LWMSG_STATUS_UNDERFLOWan arithmetic underflow occured while converting an integer to its marshalled form
LWMsgStatus lwmsg_data_unmarshal ( LWMsgDataContext context,
LWMsgTypeSpec type,
LWMsgBuffer buffer,
void **  out 
)

Converts a serialized data structure to its unmarshalled form, allocating memory as necessary to form the object graph.

Parameters
[in,out]contextthe data context
[in]typethe type specification which describes the type of the data
[in,out]bufferthe marshalling buffer from which data will be read
[out]outthe resulting unmarshalled object
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMSG_STATUS_OVERFLOWan arithmetic overflow occured while converting an integer to its unmarshalled form
LWMSG_STATUS_UNDERFLOWan arithmetic underflow occured while converting an integer to its unmarshalled form
...the provided context and buffer may raise implementation-specific errors
LWMsgStatus lwmsg_data_unmarshal_into ( LWMsgDataContext context,
LWMsgTypeSpec type,
LWMsgBuffer buffer,
void *  object,
size_t  size 
)

Converts a serialized data structure to its unmarshalled form without allocating memory for the top-level structure – instead, the caller must provide sufficient space for it. Memory for embedded pointers will still be allocated automatically as in lwmsg_data_unmarshal().

Parameters
[in,out]contextthe data context
[in]typethe type specification which describes the type of the data
[in,out]bufferthe marshalling buffer from which data will be read
[out]objectthe memory object into which the unmarshalled data will be written
[in]sizethe size of object in bytes
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMSG_STATUS_OVERFLOWan arithmetic overflow occured while converting an integer to its unmarshalled form
LWMSG_STATUS_UNDERFLOWan arithmetic underflow occured while converting an integer to its unmarshalled form
LWMSG_STATUS_BUFFER_TOO_SMALLobject was too small to contain the unmarshalled structure
...the provided context and buffer may raise implementation-specific errors
LWMsgStatus lwmsg_data_unmarshal_flat ( LWMsgDataContext context,
LWMsgTypeSpec type,
const void *  buffer,
size_t  length,
void **  out 
)

Converts a serialized data structure to its unmarshalled form, allocating memory as necessary to form the object graph. The serialized form is read from a simple buffer rather than a full LWMsgBuffer.

Parameters
[in,out]contextthe data context
[in]typethe type specification which describes the type of the data
[in]bufferthe simple buffer from which data will be read
[in]lengththe length of the buffer in bytes
[out]outthe resulting unmarshalled object
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMSG_STATUS_OVERFLOWan arithmetic overflow occured while converting an integer to its unmarshalled form
LWMSG_STATUS_UNDERFLOWan arithmetic underflow occured while converting an integer to its unmarshalled form
LWMsgStatus lwmsg_data_print_graph_alloc ( LWMsgDataContext context,
LWMsgTypeSpec type,
void *  root,
char **  result 
)

Prints a human-readable textual representation of a data graph, automatically allocating and returning a C string containing the result. The string will be allocated using the context passed to lwmsg_data_context_new() when creating the data context.

Parameters
[in,out]contextthe data context
[in]typea type specification which describes the graph root
[in]rootthe root of the data graph
[out]resultthe resulting string
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe provided data did not conform in some way to the provided type information
LWMsgStatus lwmsg_data_alloc_memory ( LWMsgDataContext context,
size_t  size,
void **  object 
)

Allocates a block of memory using the data context's memory manager. This is the same memory manager used when reconstructing an object graph during unmarshalling.

Parameters
[in]contextthe data context
[in]sizethe number of bytes to allocate
[out]objectthe allocated block
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
void lwmsg_data_free_memory ( LWMsgDataContext context,
void *  object 
)

Frees a block of memory using the data context's memory manager. This is the same memory manager used when reconstructing an object graph during unmarshalling.

Parameters
[in]contextthe data context
[in,out]objectthe block to free