Data marshaling and manipulation.
More...
|
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 LWMsgContext * | lwmsg_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...
|
|
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:
-
Byte order of the octect representation
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.
An opqaue data context which facilitates all data model operations.
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] | context | an optional context |
[out] | dcontext | the created data context |
- Return values
-
Deletes the specified data context.
- Parameters
-
[in,out] | context | the data context |
- Return values
-
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] | context | the data context |
[in] | order | the data order |
Gets the byte order which will be used for subsequent marshal and unmarshal operations on the specified data context.
- Parameters
-
[in] | context | the data context |
- Returns
- the current byte order
Gets the context which was given to lwmsg_data_context_new() when the specified data context was created.
- Parameters
-
[in] | context | the data context |
- Returns
- the context, or NULL if no context was given at creation time
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] | context | the data context |
[in] | type | the type of the root node of the graph |
[in,out] | root | the root of the graph |
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] | context | the data context |
[in] | type | the type of the root node of the graph |
[in,out] | root | the root of the graph |
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] | context | an optional context |
[in] | type | the type of the root node of the graph |
[in,out] | root | the root of the graph |
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] | context | an optional context |
[in] | type | the type of the root node of the graph |
[in,out] | root | the root of the graph |
Converts a data structure of the specified type to a flat, serialized form, storing the result in the provided marshalling buffer.
- Parameters
-
[in,out] | context | the data context |
[in] | type | the type specification which describes the type of the data |
[in] | object | the root of the data to marshal |
[in,out] | buffer | the marshalling buffer into which the result will be stored |
- Return values
-
Converts a data structure of the specified type to a flat, serialized form, storing the result in the provided simple buffer.
- Parameters
-
[in,out] | context | the data context |
[in] | type | the type specification which describes the type of the data |
[in] | object | the root of the data to marshal |
[out] | buffer | the buffer into which the result will be stored |
[in] | length | the size of the buffer in bytes |
- Return values
-
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] | context | the data context |
[in] | type | the type specification which describes the type of the data |
[in] | object | the root of the data to marshal |
[out] | buffer | the allocated buffer containing the serialized representation |
[out] | length | the length of the buffer |
- Return values
-
Converts a serialized data structure to its unmarshalled form, allocating memory as necessary to form the object graph.
- Parameters
-
[in,out] | context | the data context |
[in] | type | the type specification which describes the type of the data |
[in,out] | buffer | the marshalling buffer from which data will be read |
[out] | out | the resulting unmarshalled object |
- Return values
-
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] | context | the data context |
[in] | type | the type specification which describes the type of the data |
[in,out] | buffer | the marshalling buffer from which data will be read |
[out] | object | the memory object into which the unmarshalled data will be written |
[in] | size | the size of object in bytes |
- Return values
-
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] | context | the data context |
[in] | type | the type specification which describes the type of the data |
[in] | buffer | the simple buffer from which data will be read |
[in] | length | the length of the buffer in bytes |
[out] | out | the resulting unmarshalled object |
- Return values
-
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] | context | the data context |
[in] | type | a type specification which describes the graph root |
[in] | root | the root of the data graph |
[out] | result | the resulting string |
- Return values
-
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] | context | the data context |
[in] | size | the number of bytes to allocate |
[out] | object | the allocated block |
- Return values
-
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] | context | the data context |
[in,out] | object | the block to free |