lbmpdm.h File Reference

Ultra Messaging (UM) Pre-Defined Message (PDM) API. More...

#include <stdlib.h>
#include <inttypes.h>

Include dependency graph for lbmpdm.h:

Go to the source code of this file.

Data Structures

struct  lbmpdm_decimal_t
 Structure to hold a scaled decimal number. A scaled decimal number consists of a mantissa $m$ and an exponent $exp$. It represents the value $m\cdot 10^{exp}$. More...
struct  lbmpdm_timestamp_t
 Structure to hold a timestamp value. More...
struct  lbmpdm_field_info_attr_stct_t
 Attribute struct to be passed along with the name when adding field info to a definition. More...
struct  lbmpdm_field_value_stct_t
 Field value struct that can be populated with a field value when passed to the lbmpdm_msg_get_field_value_stct function. More...

Defines

#define LBMPDMExpDLL
 PDM API function return codes.
#define PRIuSZ   "zu"
#define SCNuSZ   "zu"
#define PDM_FALSE   (uint8_t) 0
#define PDM_TRUE   (uint8_t) 1
#define PDM_FIELD_INFO_FLAG_REQ   0x1
#define PDM_FIELD_INFO_FLAG_FIXED_STR_LEN   0x2
#define PDM_FIELD_INFO_FLAG_NUM_ARR_ELEM   0x4
#define PDM_MSG_FLAG_VAR_OR_OPT_FLDS_SET   0x1
#define PDM_MSG_FLAG_INCL_DEFN   0x2
#define PDM_MSG_FLAG_USE_MSG_DEFN_IF_NEEDED   0x4
#define PDM_MSG_FLAG_TRY_LOAD_DEFN_FROM_CACHE   0x8
#define PDM_MSG_FLAG_NEED_BYTE_SWAP   0x10
#define PDM_MSG_FLAG_DEL_DEFN_WHEN_REPLACED   0x20
#define PDM_MSG_VER_POLICY_EXACT   0
#define PDM_MSG_VER_POLICY_BEST   1
#define PDM_SUCCESS   0
#define PDM_FAILURE   -1
#define PDM_ERR_FIELD_IS_NULL   1
#define PDM_ERR_NO_MORE_FIELDS   2
#define PDM_ERR_INSUFFICIENT_BUFFER_LENGTH   3
#define PDM_ERR_EINVAL   4
#define PDM_ERR_FIELD_NOT_FOUND   5
#define PDM_ERR_MSG_INVALID   6
#define PDM_ERR_DEFN_INVALID   7
#define PDM_ERR_NOMEM   8
#define PDM_ERR_REQ_FIELD_NOT_SET   9
#define PDM_ERR_CREATE_SECTION   10
#define PDM_ERR_CREATE_BUFFER   11
#define PDM_INTERNAL_TYPE_INVALID   -1
#define PDM_TYPE_BOOLEAN   0
#define PDM_TYPE_INT8   1
#define PDM_TYPE_UINT8   2
#define PDM_TYPE_INT16   3
#define PDM_TYPE_UINT16   4
#define PDM_TYPE_INT32   5
#define PDM_TYPE_UINT32   6
#define PDM_TYPE_INT64   7
#define PDM_TYPE_UINT64   8
#define PDM_TYPE_FLOAT   9
#define PDM_TYPE_DOUBLE   10
#define PDM_TYPE_DECIMAL   11
#define PDM_TYPE_TIMESTAMP   12
#define PDM_TYPE_FIX_STRING   13
#define PDM_TYPE_STRING   14
#define PDM_TYPE_FIX_UNICODE   15
#define PDM_TYPE_UNICODE   16
#define PDM_TYPE_BLOB   17
#define PDM_TYPE_MESSAGE   18
#define PDM_TYPE_BOOLEAN_ARR   19
#define PDM_TYPE_INT8_ARR   20
#define PDM_TYPE_UINT8_ARR   21
#define PDM_TYPE_INT16_ARR   22
#define PDM_TYPE_UINT16_ARR   23
#define PDM_TYPE_INT32_ARR   24
#define PDM_TYPE_UINT32_ARR   25
#define PDM_TYPE_INT64_ARR   26
#define PDM_TYPE_UINT64_ARR   27
#define PDM_TYPE_FLOAT_ARR   28
#define PDM_TYPE_DOUBLE_ARR   29
#define PDM_TYPE_DECIMAL_ARR   30
#define PDM_TYPE_TIMESTAMP_ARR   31
#define PDM_TYPE_FIX_STRING_ARR   32
#define PDM_TYPE_STRING_ARR   33
#define PDM_TYPE_FIX_UNICODE_ARR   34
#define PDM_TYPE_UNICODE_ARR   35
#define PDM_TYPE_BLOB_ARR   36
#define PDM_TYPE_MESSAGE_ARR   37
#define PDM_DEFN_STR_FIELD_NAMES   0
#define PDM_DEFN_INT_FIELD_NAMES   1
#define PDM_ITER_INVALID_FIELD_HANDLE   -1

Typedefs

typedef int32_t lbmpdm_field_handle_t
 Type representing a handle to a message field. Field handles are returned when adding a field to a definition, or can be retrieved from a definition using the lbmpdm_get_field_handle_by_str_name or lbpdm_get_field_handle_by_int_name functions.
typedef lbmpdm_msg_stct_t lbmpdm_msg_t
 Structure to hold a pdm message.
typedef lbmpdm_defn_stct_t lbmpdm_defn_t
 Structure to hold a pdm definition.
typedef lbmpdm_field_info_attr_stct_t lbmpdm_field_info_attr_t
typedef lbmpdm_field_value_stct_t lbmpdm_field_value_t
typedef lbmpdm_iter_stct_t lbmpdm_iter_t
 Iterator structure that is used to traverse the fields of a message.

Functions

LBMPDMExpDLL int lbmpdm_errnum ()
 Return the error number last encountered by this thread.
LBMPDMExpDLL const char * lbmpdm_errmsg ()
 Return an ASCII string containing the error message last encountered by this thread.
LBMPDMExpDLL int lbmpdm_cache_init (uint32_t cache_size)
 initialize the cache for a given number of buckets. If 0 is given the the cache will default. The default can be altered via a PDM attribute.
LBMPDMExpDLL int lbmpdm_cache_struct_add (lbmpdm_defn_t *defn)
 add a definition structure to the cache. It is assumed that the structure has a unique id, if the id is set to zero the structure will not be inserted into the map.
LBMPDMExpDLL int lbmpdm_cache_struct_remove (int32_t id)
 delete a definition structure from the cache. Does not error if the structure doesn't exist.
LBMPDMExpDLL int lbmpdm_cache_struct_remove_by_version (int32_t id, uint8_t vers_major, uint8_t vers_minor)
 delete a definition structure from the cache by its id and version. Does not error if the structure doesn't exist.
LBMPDMExpDLL int lbmpdm_cache_struct_find (lbmpdm_defn_t **defn, int32_t id)
 find a given definition structure by id and return the structure for it. Returns PDM_FAILURE for nothing found, and PDM_SUCCESS for something found. Note, since a structure with the id of 0 won't exist in the cache you will never find one being returned from this find with an id of 0.
LBMPDMExpDLL int lbmpdm_cache_struct_find_by_version (lbmpdm_defn_t **defn, int32_t id, uint8_t vers_major, uint8_t vers_minor)
 find a given definition structure by id, major version, and minor version and return the structure for it. Returns PDM_FAILURE for nothing found, and PDM_SUCCESS for something found. Note, since a structure with the id of 0 won't exist in the cache you will never find one being returned from this find with an id of 0.
LBMPDMExpDLL int lbmpdm_cache_clear_all ()
 nuke the whole cache, this deletes all the structures within the cache as well.
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_str_name (lbmpdm_defn_t *defn, const char *str_name)
 Retrieve a field handle from a definition via name.
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_int_name (lbmpdm_defn_t *defn, int32_t int_name)
 Retrieve a field handle from a definition via name.
LBMPDMExpDLL int lbmpdm_defn_create (lbmpdm_defn_t **defn, int32_t num_fields, int32_t id, int8_t vrs_mjr, int8_t vrs_mnr, uint8_t field_names_type)
 Create a definition, with the passed number of fields. The num_fields is required to be at least 1. The number of fields can grow beyond this value, it is used initially to size the internal field info array.
LBMPDMExpDLL int lbmpdm_defn_delete (lbmpdm_defn_t *defn)
 delete a given definition.
LBMPDMExpDLL int lbmpdm_defn_finalize (lbmpdm_defn_t *defn)
 make this definition final. This needs to be done before using it in a message.
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_add_field_info_by_str_name (lbmpdm_defn_t *defn, const char *str_name, int16_t type, lbmpdm_field_info_attr_t *info_attr)
 adds field info to the definition by string name
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_add_field_info_by_int_name (lbmpdm_defn_t *defn, int32_t int_name, int16_t type, lbmpdm_field_info_attr_t *info_attr)
 adds field info to the definition by integer name
LBMPDMExpDLL uint32_t lbmpdm_defn_get_length (lbmpdm_defn_t *defn)
 Gets the exact length of the serialized defn. This can be used to allocate a buffer of the exact length needed to serialize the defn.
LBMPDMExpDLL int32_t lbmpdm_defn_get_id (lbmpdm_defn_t *defn)
 Gets the id of the definition.
LBMPDMExpDLL int32_t lbmpdm_defn_get_num_fields (lbmpdm_defn_t *defn)
 Gets the number of fields in the definition.
LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_major (lbmpdm_defn_t *defn)
 Gets the message major version number from the definition.
LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_minor (lbmpdm_defn_t *defn)
 Gets the message minor version number from the definition.
LBMPDMExpDLL uint8_t lbmpdm_defn_get_field_names_type (lbmpdm_defn_t *defn)
 Gets the field names type (either PDM_DEFN_STR_FIELD_NAMES or PDM_DEFN_INT_FIELD_NAMES) from the definition.
LBMPDMExpDLL uint8_t lbmpdm_defn_is_finalized (lbmpdm_defn_t *defn)
 Gets whether or not the definition has been finalized (either PDM_TRUE or PDM_FALSE).
LBMPDMExpDLL const char * lbmpdm_defn_get_field_info_str_name (lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle)
 Gets the string field name from a given definition's field handle.
LBMPDMExpDLL int32_t lbmpdm_defn_get_field_info_int_name (lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle)
 Gets the integer field name from a given definition's field handle.
LBMPDMExpDLL int16_t lbmpdm_defn_get_field_info_type (lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle)
 Gets the PDM field type from a given definition's field handle.
LBMPDMExpDLL int lbmpdm_defn_serialize (lbmpdm_defn_t *defn, char *buffer, uint32_t *defn_len)
 Serialize a defn to a buffer. In normal usage this is not needed as the defn is either known in advance or sent as part of a message. The defn that is passed in is serialized into the caller's supplied buffer.
LBMPDMExpDLL int lbmpdm_defn_deserialize (lbmpdm_defn_t *defn, const char *bufptr, uint32_t buflen, uint8_t swap_bytes)
 Deserialize the associated buffer into a newly created defn.
LBMPDMExpDLL int lbmpdm_msg_create (lbmpdm_msg_t **message, lbmpdm_defn_t *defn, uint32_t flags)
 creates a message with the specified definition
LBMPDMExpDLL int lbmpdm_msg_delete (lbmpdm_msg_t *message)
 Delete an lbmpdm_msg_t object and all associated resources (except the defn) This deletes a previously created PDM message and all resources associated with the message.
LBMPDMExpDLL int lbmpdm_msg_and_defn_delete (lbmpdm_msg_t *message)
 Delete an lbmpdm_msg_t object and all associated resources (including the defn) This deletes a previously created PDM message and all resources associated with the message.
LBMPDMExpDLL uint32_t lbmpdm_msg_get_length (const lbmpdm_msg_t *message)
 Gets the exact length of the serialized message. This can be used to allocate a buffer of the exact length needed to serialize the message.
LBMPDMExpDLL lbmpdm_defn_tlbmpdm_msg_get_defn (const lbmpdm_msg_t *message)
 Gets a pointer to the message definition.
LBMPDMExpDLL uint8_t lbmpdm_msg_is_field_set (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle)
 Gets whether or not the field value has been set.
LBMPDMExpDLL int lbmpdm_msg_get_field_value_stct (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, lbmpdm_field_value_t *field_value)
 Populates a field value struct with the value from the message.
LBMPDMExpDLL int lbmpdm_msg_get_field_value (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t *len)
 Gets a field value from the message.
LBMPDMExpDLL int lbmpdm_msg_get_field_value_vec (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t len[], size_t *num_arr_elem)
 Gets an array of field values from the message.
LBMPDMExpDLL int lbmpdm_msg_set_field_value (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t len)
 Sets a field value in a message.
LBMPDMExpDLL int lbmpdm_msg_set_field_value_vec (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t len[], size_t num_arr_elem)
 Sets an array of field values in a message.
LBMPDMExpDLL int lbmpdm_msg_remove_field_value (lbmpdm_msg_t *message, lbmpdm_field_handle_t handle)
 Removes a field value from a message (marking it unset).
LBMPDMExpDLL int lbmpdm_msg_set_incl_defn_flag (lbmpdm_msg_t *message)
 Sets the message include definition flag.
LBMPDMExpDLL int lbmpdm_msg_unset_incl_defn_flag (lbmpdm_msg_t *message)
 Unsets the message include definition flag.
LBMPDMExpDLL int lbmpdm_field_value_stct_delete (lbmpdm_field_value_t *field_value)
 Deletes the allocated resources inside the field value struct. This does NOT free the actual field value struct passed in (which should be done outside PDM). Also, this does not affect the field value in the message, only this field value struct.
LBMPDMExpDLL int lbmpdm_msg_serialize (lbmpdm_msg_t *message, char *buffer)
 Serialize a message to a buffer. The message that is passed in is serialized into the caller's supplied buffer.
LBMPDMExpDLL int lbmpdm_msg_deserialize (lbmpdm_msg_t *message, const char *bufptr, uint32_t buflen)
 Deserialize the associated buffer into a newly created message.
LBMPDMExpDLL char * lbmpdm_msg_get_data (lbmpdm_msg_t *message)
 Serialize a message to a buffer and return the buffer. The message that is passed in is serialized into a buffer which will be cleaned up when the message is deleted. Use lbmpdm_msg_get_length to get the length of the buffer.
LBMPDMExpDLL int lbmpdm_iter_create (lbmpdm_iter_t **iter, lbmpdm_msg_t *message)
 Creates a pdm iterator to iterate through the fields in a message.
LBMPDMExpDLL int lbmpdm_iter_create_from_field_handle (lbmpdm_iter_t **iter, lbmpdm_msg_t *message, lbmpdm_field_handle_t field_handle)
 Creates a pdm iterator to iterate through the fields in a message starting at a particular field.
LBMPDMExpDLL int lbmpdm_iter_delete (lbmpdm_iter_t *iter)
 Deletes the iterator.
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_iter_get_current (lbmpdm_iter_t *iter)
 Gets the current field handle from the iterator.
LBMPDMExpDLL int lbmpdm_iter_first (lbmpdm_iter_t *iter)
 Sets the iterator back to the first field.
LBMPDMExpDLL int lbmpdm_iter_next (lbmpdm_iter_t *iter)
 Steps the iterator to the next first field.
LBMPDMExpDLL uint8_t lbmpdm_iter_has_next (lbmpdm_iter_t *iter)
 Checks to see if the iterator has another field to step to.
LBMPDMExpDLL uint8_t lbmpdm_iter_is_current_set (lbmpdm_iter_t *iter)
 Checks to see if the current field is set.
LBMPDMExpDLL int lbmpdm_iter_set_msg (lbmpdm_iter_t *iter, lbmpdm_msg_t *message)
 Sets the message used to step through by this iterator.
LBMPDMExpDLL int lbmpdm_iter_set_current_field_value (lbmpdm_iter_t *iter, void *value, size_t len)
 Sets the current field value to the value passed in.
LBMPDMExpDLL int lbmpdm_iter_set_current_field_value_vec (lbmpdm_iter_t *iter, void *value, size_t len[], size_t num_arr_elem)
 Sets the current field values to the passed array of values.
LBMPDMExpDLL int lbmpdm_iter_get_current_field_value (lbmpdm_iter_t *iter, void *value, size_t *len)
 Gets a field value from the iterator's current field.
LBMPDMExpDLL int lbmpdm_iter_get_current_field_value_vec (lbmpdm_iter_t *iter, void *value, size_t len[], size_t *num_arr_elem)
 Gets an array of field values from the iterator's current field.


Detailed Description

The Ultra Messaging (UM) Pre-Defined Message (PDM) API Description. Included are types, constants, and functions related to the API. Contents are subject to change.

All of the documentation and software included in this and any other Informatica Corporation Ultra Messaging Releases Copyright (C) Informatica Corporation. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted only as covered by the terms of a valid software license agreement with Informatica Corporation.

Copyright (C) 2007-2014, Informatica Corporation. All Rights Reserved.

THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE. INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF THE LIKELIHOOD OF SUCH DAMAGES.

The LBM Pre-Defined Message(PDM) API provides a framework for applications to create message definitions and messages from those definitions. A PDM definition contains a list of field information describing the fields that will be contained in a message. A PDM message contains one or more fields with each field corresponding to a specific field information object in the definition. Field info consists of:

Field types
The following field types (and arrays thereof) are supported by PDM:
Description PDM Type C Type
Boolean PDM_TYPE_BOOLEAN uint8_t
8-bit signed integer PDM_TYPE_INT8 int8_t
8-bit unsigned integer PDM_TYPE_UINT8 uint8_t
16-bit signed integer PDM_TYPE_INT16 int16_t
16-bit unsigned integer PDM_TYPE_UINT16 uint16_t
32-bit signed integer PDM_TYPE_INT32 int32_t
32-bit unsigned integer PDM_TYPE_UINT32 uint32_t
64-bit signed integer PDM_TYPE_INT64 int64_t
64-bit unsigned integer PDM_TYPE_UINT64 uint64_t
Single-precision floating point PDM_TYPE_FLOAT float
Double-precision floating point PDM_TYPE_DOUBLE double
Decimal PDM_TYPE_DECIMAL struct decimal
Timestamp PDM_TYPE_TIMESTAMP struct timestamp
Fixed Length String PDM_TYPE_FIX_STRING char *
String PDM_TYPE_STRING char *
Fixed Length Unicode PDM_TYPE_FIX_UNICODE char *
Unicode PDM_TYPE_UNICODE char *
Nested PDM message PDM_TYPE_MESSAGE lbmpdm_msg_t *
Binary large object (BLOB) PDM_TYPE_BLOB void *
Note that arrays are homogeneous.
Creating a message definition
A message definition must be defined (via lbmpdm_defn_create()) before a message can be created. After creating the definition, field info can be added. Once all field information has been added to a definition, the definition must be finalized (lbmpdm_defn_finalize()). Each definition must be given an id to identify that definition (and messages created with the definition) to all consumers of the message. This allows all messaging participants to define the message and for PDM to quickly deserialize the messages. As an example, we will create a simple definition with two fields, a 32-bit signed integer and a string array. We will give the definition an id of 1000.
lbmpdm_defn_t *defn;
lbmpdm_field_handle_t h1;
lbmpdm_field_handle_t h2;
lbmpdm_field_info_attr_t info_attr;

if (lbmpdm_defn_create(&defn, 2, 1000, 1, 0, PDM_DEFN_STR_FIELD_NAMES) != PDM_SUCCESS) {
  printf("Failed to create the definition");
  return;
}

info_attr.flags = 0;

h1 = lbmpdm_defn_add_field_info_by_str_name(defn, "Field1", PDM_TYPE_INT32, NULL);

info_attr.flags |= PDM_FIELD_INFO_FLAG_REQ;
info_attr.req = PDM_FALSE;
h2 = lbmpdm_defn_add_field_info_by_str_name(defn, "Field2", PDM_TYPE_STRING_ARR, &info_attr);

lbmpdm_defn_finalize(defn);
The values of the info_attr struct will only be examined if the corresponding PDM_FIELD_INFO_FLAG_* has been set when it is passed to the add_field_info function. If NULL is passed instead of an info_attr pointer or any of the flags are not set, then default values will be used when adding the field info(which are: required = PDM_TRUE, fixed string length = 0, and number of array elements = 0).
Once the definition exists, a message can be created and field values can be set in the message. The fields can be set by using the field handle that was returned from the call to the definition to add field info (or the field handle can be looked up from the definition).
Sample code
Checking of return codes has been omitted but should be done during actual usage of pdm.
{
int rc;
lbmpdm_msg_t *msg1;
lbmpdm_msg_t *msg2;
char *msg_buffer;
int msg_len;

int32_t quant = 50;
char *str_arr[3] = {"s1", "str2", "string3"};
size_t str_len_arr[3] = {3, 5, 8};
size_t str_arr_num_elem = 3;

int32_t rcv_quant;
size_t rcv_quant_sz = sizeof(int32_t);
char *rcv_str_arr[3];
rcv_str_arr[0] = malloc(3);
rcv_str_arr[1] = malloc(5);
rcv_str_arr[2] = malloc(8);

lbmpdm_msg_create(&msg1, defn, 0);

rc = lbmpdm_msg_set_field_value(msg1, h1, &quant, 0);
rc = lbmpdm_msg_set_field_value_vec(msg1, h2, str_arr, str_len_arr, str_arr_num_elem);

msg_len = lbmpdm_msg_get_length(msg1);
msg_buffer = malloc(msg_len);
rc = lbmpdm_msg_serialize(msg1, msg_buffer);

rc = lbmpdm_msg_create(&msg2, defn, 0);
rc = lbmpdm_msg_deserialize(msg2, msg_buffer, msg_len);

rc = lbmpdm_msg_get_field_value(msg2, h1, &rcv_quant, &rcv_quant_sz);
rc = lbmpdm_msg_get_field_value_vec(msg2, h2, rcv_str_arr, str_len_arr, &str_arr_num_elem);

printf("rcv_quant = %d\n", rcv_quant);
printf("rcv_str_arr[0] = %s\n", rcv_str_arr[0]);
printf("rcv_str_arr[1] = %s\n", rcv_str_arr[1]);
printf("rcv_str_arr[2] = %s\n", rcv_str_arr[2]);

free(rcv_str_arr[0]);
free(rcv_str_arr[1]);
free(rcv_str_arr[2]);

free(msg_buffer);

lbmpdm_msg_delete(msg1);
lbmpdm_msg_delete(msg2);
lbmpdm_defn_delete(defn);
}
Creating a message
Messages are created from definitions. The line above that is used to create the message:
lbmpdm_msg_create(&msg1, defn, 0);
Setting field values in a message
Scalar (non-array) fields are added to a message via the lbmpdm_msg_set_field_value() to set a field's value using its handle.
When setting a field's value, data of the appropriate type must be supplied. A 0 length can be supplied for fixed length fields but it is recommended to pass the correct size in bytes to ensure the correct number of bytes are copied into the message. As an example, to set a 32-bit signed integer field to a message:
rc = lbmpdm_msg_set_field_value(msg1, h1, &quant, 0);
Setting a string value is done by passing the char * and the actual size of the string in bytes (normally this is the num_chars + 1 to account for the null character but for UNICODE types this value will be larger). For the MESSAGE type, the value argument should be a lbmpdm_msg_t * and the length argument should be sizeof(lbmpdm_msg_t *) because the setter will attempt to access the lbmpdm_msg_t via the pointer and then serialize it to bytes via its serialize method.
Setting the value of array fields in a message
To set an array's value in a message, call the lbmpdm_msg_set_field_value_vec() API function.
As an example, the code that sets the string array field value is:
rc = lbmpdm_msg_set_field_value_vec(msg1, h2, str_arr, str_len_arr, str_arr_num_elem);
Setting an array field value requires an addition number of elements parameter and expects an array of lengths (one for each element in the array). Again, string types should pass a length array that indicates the size in bytes of each string rather than the number of characters as shown in the example code which uses sizes a length array of {3, 5, 8}.
Serializing the message
Once a PDM message is constructed, it must be serialized for transmission. The API function lbmpdm_msg_serialize() serializes the message to the buffer provided. The length of the serialized data may be obtained via the API function lbmpdm_msg_get_length(). For example, a constructed message may be sent by:
rc = lbmpdm_msg_serialize(msg1, msg_buffer);
rc = lbm_src_send(src, msg_buffer, msg_len, 0);
Deserializing a message
When the bytes for a pdm message are received, they must be deserialized so that individual fields can be accessed. The lbmpdm_msg_t should be reused when possible to deserialize multiple incoming messages. This is done via the lbmpdm_msg_deserialize() API function:
rc = lbmpdm_msg_deserialize(msg2, msg_buffer, msg_len);
// Deserializing an lbm message would be the following
//rc = lbmpdm_msg_deserialize(msg2, lbmmsg->data, lbmmsg->len);
Fetching fields from a message
When fetching a field from a message, the field should be accessed by its handle.
Scalar (non-array) fields may be retrieved via the lbmpdm_msg_get_field_value().
rc = lbmpdm_msg_get_field_value(msg2, h1, &rcv_quant, &rcv_quant_sz);
Array fields may be retrieved via the lbmpdm_msg_get_field_value_vec().
rc = lbmpdm_msg_get_field_value_vec(msg2, h2, rcv_str_arr, str_len_arr, &str_arr_num_elem);
When accessing a field, it is expected that value pointer being provided already points to an area of sufficient size to hold the field's value. The len argument should indicate the size or sizes (for array types) of the available space. If the size is not sufficient, a PDM_FAILURE will be returned and the failing len argument will be updated to indicate the actual size needed. For array types, the same logic applies to the number of elements argument, where if the number of allocated elements indicated by the input parameter is insufficient, the call will fail and the value will be updated to indicate the needed number of elements. For the MESSAGE type, the value argument should be a lbmpdm_msg_t * that points to an empty lbmpdm_msg_t which has been created with a NULL definition. The length argument should be sizeof(lbmpdm_msg_t *) because the setter will attempt to access the lbmpdm_msg_t via the pointer and then deserialize the bytes into it.
Disposing of a message and definition
Once a PDM message (created by either the lbmpdm_msg_create() or lbmpdm_msg_deserialize() API calls) is no longer needed, it must be deleted to avoid a resource leak. This is done via the lbmpdm_msg_delete() API call.
Error information
All functions return a value to indicate the success of failure of the operation. Most return PDM_SUCCESS to indicate success, or PDM_FAILURE otherwise. Consult the individual function documentation for exceptions.
The function lbmpdm_errmsg() will return a descriptive error message.
Additional Information
When adding arrays to a definition, an array length can be specified in the info attributes. A 0 length means that the array's length is variable and will be determined when the array is set in the actual message. A positive number for the array length will create a fixed array of that size.
When adding PDM_TYPE_FIX_STRING, PDM_TYPE_FIX_STRING_ARR, PDM_TYPE_FIX_UNICODE, or PDM_TYPE_FIX_UNICODE_ARR, field information to a definition, a fixed string length must be specified in the info attributes. The value should be the number of characters in the string (excluding the null character). The appropriate amount of space will be then allocated in the message for each of the expected fixed strings (for the FIX_STRING types, there will be num_chars + 1 bytes allocated per string and for the FIX_UNICODE types, there will be 4 * num_chars + 1 bytes allocated per string). By using fixed strings for a field, as well as making the field required (and specifying a fixed size for the array types), the best performance and size can be achieved because the field will be optimized as a "fixed required" field.
When setting and getting field values of type FIX_STRING and FIX_UNICODE (and the corresponding arrays), extra care should be made to ensure the len parameters are correct. When setting the value, the len should indicate the actual number of bytes represented by the string that should be copied (which should include the null character). If this is less than the size indicated to the definition when setting up the field information, the rest of the space will be zeroed out. When getting the value, enough space should be allocated for the entire size of the fixed string field, which as described above should be the number of characters + 1 for the string types and 4 * the number of characters + 1 for the unicode types.
An additional way to get a field value from a message is by using the lbmpdm_msg_get_field_value_stct method, which does not require the storage and lengths to be allocated beforehand but instead will allocate everything during the call and set all of the appropriate values of the provided lbmpdm_field_value_t. Although simpler to use, the drawback is not being able to use preallocated space to hold the field value as the other get_field_value methods are able to do. It also requires the application to manage the field_value_t and call the field_value_stct_delete method when finished to clean up the allocated memory inside the field_value_t.

Define Documentation

#define PDM_DEFN_INT_FIELD_NAMES   1

PDM Field Name Type. Use integer field names.

#define PDM_DEFN_STR_FIELD_NAMES   0

PDM Field Name Type. Use string field names.

#define PDM_ERR_CREATE_BUFFER   11

PDM Error Code. Error creating buffer.

#define PDM_ERR_CREATE_SECTION   10

PDM Error Code. Error creating field section.

#define PDM_ERR_DEFN_INVALID   7

PDM Error Code. Not a valid PDM definition.

#define PDM_ERR_EINVAL   4

PDM Error Code. Invalid parameter given.

#define PDM_ERR_FIELD_IS_NULL   1

PDM Error Code. Field is null.

#define PDM_ERR_FIELD_NOT_FOUND   5

PDM Error Code. Field not found.

#define PDM_ERR_INSUFFICIENT_BUFFER_LENGTH   3

PDM Error Code. Insufficient buffer length given.

#define PDM_ERR_MSG_INVALID   6

PDM Error Code. Not a valid PDM message.

#define PDM_ERR_NO_MORE_FIELDS   2

PDM Error Code. No more fields to iterate over.

#define PDM_ERR_NOMEM   8

PDM Error Code. No memory available.

#define PDM_ERR_REQ_FIELD_NOT_SET   9

PDM Error Code. Required field not set.

#define PDM_FAILURE   -1

PDM Return Code. Operation failed. See lbmpdm_errnum() or lbmpdm_errmsg() for the reason.

#define PDM_FALSE   (uint8_t) 0

PDM true/false values. PDM value for FALSE.

#define PDM_FIELD_INFO_FLAG_FIXED_STR_LEN   0x2

PDM Field Info Flags. Field has a fixed string length (for string and unicode types).

#define PDM_FIELD_INFO_FLAG_NUM_ARR_ELEM   0x4

PDM Field Info Flags. Field has a fixed array size (for array types).

#define PDM_FIELD_INFO_FLAG_REQ   0x1

PDM Field Info Flags. Field is required.

#define PDM_INTERNAL_TYPE_INVALID   -1

PDM Field Type. Invalid Type.

#define PDM_ITER_INVALID_FIELD_HANDLE   -1

PDM Iterator Invalid Handle. Indicates invalid field handle.

#define PDM_MSG_FLAG_DEL_DEFN_WHEN_REPLACED   0x20

PDM Message Flags. If a message's existing definition should be deleted when replaced when deserializing a message.

#define PDM_MSG_FLAG_INCL_DEFN   0x2

PDM Message Flags. If the definition should be serialized with the message.

#define PDM_MSG_FLAG_NEED_BYTE_SWAP   0x10

PDM Message Flags. If the field values need bytes to be swapped (set internally).

#define PDM_MSG_FLAG_TRY_LOAD_DEFN_FROM_CACHE   0x8

PDM Message Flags. If a message should try to load a needed definition from the cache when deserializing.

#define PDM_MSG_FLAG_USE_MSG_DEFN_IF_NEEDED   0x4

PDM Message Flags. If a message should override its existing definition with one included when deserializing a message.

#define PDM_MSG_FLAG_VAR_OR_OPT_FLDS_SET   0x1

PDM Message Flags. If any variable or optional fields have been set (set internally).

#define PDM_MSG_VER_POLICY_BEST   1

PDM Message Version Policy. Use Best Match versioning Policy.

#define PDM_MSG_VER_POLICY_EXACT   0

PDM Message Version Policy. Use Exact Match versioning Policy.

#define PDM_SUCCESS   0

PDM Return Code. Operation was successful.

#define PDM_TRUE   (uint8_t) 1

PDM true/false values. PDM value for TRUE.

#define PDM_TYPE_BLOB   17

PDM Field Type. blob (variable length).

#define PDM_TYPE_BLOB_ARR   36

PDM Field Type. blob array.

#define PDM_TYPE_BOOLEAN   0

PDM Field Type. boolean.

#define PDM_TYPE_BOOLEAN_ARR   19

PDM Field Type. boolean array.

#define PDM_TYPE_DECIMAL   11

PDM Field Type. decimal.

#define PDM_TYPE_DECIMAL_ARR   30

PDM Field Type. decimal array.

#define PDM_TYPE_DOUBLE   10

PDM Field Type. double.

#define PDM_TYPE_DOUBLE_ARR   29

PDM Field Type. double array.

#define PDM_TYPE_FIX_STRING   13

PDM Field Type. fixed string.

#define PDM_TYPE_FIX_STRING_ARR   32

PDM Field Type. fixed string array.

#define PDM_TYPE_FIX_UNICODE   15

PDM Field Type. fixed unicode.

#define PDM_TYPE_FIX_UNICODE_ARR   34

PDM Field Type. fixed unicode array.

#define PDM_TYPE_FLOAT   9

PDM Field Type. float.

#define PDM_TYPE_FLOAT_ARR   28

PDM Field Type. float array.

#define PDM_TYPE_INT16   3

PDM Field Type. 16 bit integer.

#define PDM_TYPE_INT16_ARR   22

PDM Field Type. 16 bit integer array.

#define PDM_TYPE_INT32   5

PDM Field Type. 32 bit integer.

#define PDM_TYPE_INT32_ARR   24

PDM Field Type. 32 bit integer array.

#define PDM_TYPE_INT64   7

PDM Field Type. 64 bit integer.

#define PDM_TYPE_INT64_ARR   26

PDM Field Type. 64 bit integer array.

#define PDM_TYPE_INT8   1

PDM Field Type. 8 bit integer.

#define PDM_TYPE_INT8_ARR   20

PDM Field Type. 8 bit integer array.

#define PDM_TYPE_MESSAGE   18

PDM Field Type. PDM message (variable length).

#define PDM_TYPE_MESSAGE_ARR   37

PDM Field Type. PDM message array.

#define PDM_TYPE_STRING   14

PDM Field Type. string (variable length).

#define PDM_TYPE_STRING_ARR   33

PDM Field Type. string array.

#define PDM_TYPE_TIMESTAMP   12

PDM Field Type. timestamp.

#define PDM_TYPE_TIMESTAMP_ARR   31

PDM Field Type. timestamp array.

#define PDM_TYPE_UINT16   4

PDM Field Type. unsigned 16 bit integer.

#define PDM_TYPE_UINT16_ARR   23

PDM Field Type. unsigned 16 bit integer array.

#define PDM_TYPE_UINT32   6

PDM Field Type. unsigned 32 bit integer.

#define PDM_TYPE_UINT32_ARR   25

PDM Field Type. unsigned 32 bit integer array.

#define PDM_TYPE_UINT64   8

PDM Field Type. unsigned 64 bit integer.

#define PDM_TYPE_UINT64_ARR   27

PDM Field Type. unsigned 64 bit integer array.

#define PDM_TYPE_UINT8   2

PDM Field Type. unsigned 8 bit integer.

#define PDM_TYPE_UINT8_ARR   21

PDM Field Type. unsigned 8 bit integer array.

#define PDM_TYPE_UNICODE   16

PDM Field Type. unicode (variable length).

#define PDM_TYPE_UNICODE_ARR   35

PDM Field Type. unicode array.


Function Documentation

LBMPDMExpDLL int lbmpdm_cache_init ( uint32_t  cache_size  ) 

Parameters:
cache_size -- how many buckets should this hash contain? If set to zero this will default.

LBMPDMExpDLL int lbmpdm_cache_struct_add ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- the new definition structure being added.

LBMPDMExpDLL int lbmpdm_cache_struct_find ( lbmpdm_defn_t **  defn,
int32_t  id 
)

Parameters:
defn -- pointer to the structure to return. This field is not altered if nothing is found for a given id.
id -- id to search for in the hash.

LBMPDMExpDLL int lbmpdm_cache_struct_find_by_version ( lbmpdm_defn_t **  defn,
int32_t  id,
uint8_t  vers_major,
uint8_t  vers_minor 
)

Parameters:
defn -- pointer to the structure to return. This field is not altered if nothing is found for a given id.
id -- id to search for in the hash.
vers_major -- major version to search for in the hash.
vers_minor -- minor version to search for in the hash.

LBMPDMExpDLL int lbmpdm_cache_struct_remove ( int32_t  id  ) 

Parameters:
id -- id of the structure being deleted. If the id is not found this will do nothing.

LBMPDMExpDLL int lbmpdm_cache_struct_remove_by_version ( int32_t  id,
uint8_t  vers_major,
uint8_t  vers_minor 
)

Parameters:
id -- id of the structure being deleted. If the id is not found this will do nothing.
vers_major -- major version of the definition
vers_minor -- minor version of the definition

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_add_field_info_by_int_name ( lbmpdm_defn_t defn,
int32_t  int_name,
int16_t  type,
lbmpdm_field_info_attr_t info_attr 
)

Parameters:
int_name -- the integer name
type -- the PDM field type
info_attr -- the field information attributes
Returns:
PDM_SUCCESS or PDM_FAILURE

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_add_field_info_by_str_name ( lbmpdm_defn_t defn,
const char *  str_name,
int16_t  type,
lbmpdm_field_info_attr_t info_attr 
)

Parameters:
str_name -- the string name
type -- the PDM field type
info_attr -- the field information attributes
Returns:
PDM_SUCCESS or PDM_FAILURE

LBMPDMExpDLL int lbmpdm_defn_create ( lbmpdm_defn_t **  defn,
int32_t  num_fields,
int32_t  id,
int8_t  vrs_mjr,
int8_t  vrs_mnr,
uint8_t  field_names_type 
)

Parameters:
defn -- pointer to newly created definition.
num_fields -- how many fields to initially assume we will have, this is for optimization, not a limit to how many fields.
id -- This is the id for the definition. It is assumed that this is a unique id.
vrs_mjr -- A version major number to be assigned to the newly created definition. When deserializing a message, PDM will attempt to use the existing set definition if the ids match. If the message flag is set to use the included message definition or try to load the definition from the cache, then an attempt will be made to replace the set definition with the new one by its version numbers. Please note: when versioning message definitions, adding optional fields only is the safest way to unsure interoperability with older versions. Adding new required fields or modifying the types of existing required fields may lead to messages that are not deserializable by receivers with older definition versions.
vrs_mnr -- A version minor number
field_names_type -- A type that indicates whether the field names will be strings or ints. Use either PDM_DEFN_STR_FIELD_NAMES or PDM_DEFN_INT_FIELD_NAMES for the value.
Returns:
PDM_SUCCESS or PDM_FAILURE.

LBMPDMExpDLL int lbmpdm_defn_delete ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- definition to be deleted.
Returns:
PDM_SUCCESS or PDM_FAILURE.

LBMPDMExpDLL int lbmpdm_defn_deserialize ( lbmpdm_defn_t defn,
const char *  bufptr,
uint32_t  buflen,
uint8_t  swap_bytes 
)

This will take the passed buffer and deserialize the contents into a newly created defn. When finished with the defn, the caller must call lbmpdm_defn_delete() to properly dispose of the defn. This is done automatically by a message when the defn is included. The message normally indicates to the definition whether or not swap bytes need to be set to PDM_TRUE so to use this method directly, this knowledge must be determined outside PDM.

See also:
lbmpdm_msg_delete()
Parameters:
defn A pointer to a previously created PDM defn object
bufptr The buffer to be deserialized
buflen The length of the buffer.
swap_bytes Whether or not bytes should be swapped to deal with endianness.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_defn_finalize ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- the definition to be finalized.
Returns:
PDM_SUCCESS or PDM_FAILURE

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_int_name ( lbmpdm_defn_t defn,
int32_t  int_name 
)

Parameters:
defn -- definition created from lbmpdm_defn_create.
int_name -- the name of the field to be retrieved.
Returns:
A valid field handle on success, PDM_FAILURE otherwise.

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_str_name ( lbmpdm_defn_t defn,
const char *  str_name 
)

Parameters:
defn -- definition created from lbmpdm_defn_create.
str_name -- the name of the field to be retrieved.
Returns:
A valid field handle on success, PDM_FAILURE otherwise.

LBMPDMExpDLL int32_t lbmpdm_defn_get_field_info_int_name ( lbmpdm_defn_t defn,
lbmpdm_field_handle_t  handle 
)

Parameters:
defn -- A pointer to a PDM defn object.
handle -- A valid field handle from the definition.
Returns:
the int field name or -1.

LBMPDMExpDLL const char* lbmpdm_defn_get_field_info_str_name ( lbmpdm_defn_t defn,
lbmpdm_field_handle_t  handle 
)

Parameters:
defn -- A pointer to a PDM defn object.
handle -- A valid field handle from the definition.
Returns:
the string field name or NULL.

LBMPDMExpDLL int16_t lbmpdm_defn_get_field_info_type ( lbmpdm_defn_t defn,
lbmpdm_field_handle_t  handle 
)

Parameters:
defn -- A pointer to a PDM defn object.
handle -- A valid field handle from the definition.
Returns:
the PDM type or PDM_INTERNAL_TYPE_INVALID.

LBMPDMExpDLL uint8_t lbmpdm_defn_get_field_names_type ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the field names type

LBMPDMExpDLL int32_t lbmpdm_defn_get_id ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the id of the definition

LBMPDMExpDLL uint32_t lbmpdm_defn_get_length ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the exact length of the serialized defn

LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_major ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the major version number

LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_minor ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the minor version number

LBMPDMExpDLL int32_t lbmpdm_defn_get_num_fields ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the number of fields in the definition

LBMPDMExpDLL uint8_t lbmpdm_defn_is_finalized ( lbmpdm_defn_t defn  ) 

Parameters:
defn -- A pointer to a PDM defn object.
Returns:
the value indicating whether or not the definition has been finalized

LBMPDMExpDLL int lbmpdm_defn_serialize ( lbmpdm_defn_t defn,
char *  buffer,
uint32_t *  defn_len 
)

Parameters:
defn A PDM defn to be serialized
buffer The caller allocated buffer
defn_len Will be set to the length of the definition
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL const char* lbmpdm_errmsg (  ) 

Returns:
Pointer to a static char array holding the error message.

LBMPDMExpDLL int lbmpdm_errnum (  ) 

Returns:
An integer error number.

LBMPDMExpDLL int lbmpdm_field_value_stct_delete ( lbmpdm_field_value_t field_value  ) 

See also:
lbmpdm_msg_get_field_value_stct
Parameters:
field_value -- A pointer to a field value structure.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_create ( lbmpdm_iter_t **  iter,
lbmpdm_msg_t message 
)

Parameters:
iter -- Pointer to the iterator pointer which will be created
message -- the pdm message
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_create_from_field_handle ( lbmpdm_iter_t **  iter,
lbmpdm_msg_t message,
lbmpdm_field_handle_t  field_handle 
)

Parameters:
iter -- Pointer to the iterator pointer which will be created
message -- the pdm message
field_handle -- the handle to the field where the iterator should start
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_delete ( lbmpdm_iter_t iter  ) 

Parameters:
iter -- the pdm iterator
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_first ( lbmpdm_iter_t iter  ) 

Parameters:
iter -- the pdm iterator
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_iter_get_current ( lbmpdm_iter_t iter  ) 

Parameters:
iter -- The pdm iterator
Returns:
the lbmpdm_field_handle_t (field handle)

LBMPDMExpDLL int lbmpdm_iter_get_current_field_value ( lbmpdm_iter_t iter,
void *  value,
size_t *  len 
)

Parameters:
iter -- the pdm iterator
value -- A pointer to a value big enough to hold the field value
len -- A pointer describing the currently allocated length of the void *value. If it is not large enough to hold the field value, PDM_FAILURE will be returned and len will be set to the needed length.
num_arr_elem -- The number of elements in the value and len array.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_get_current_field_value_vec ( lbmpdm_iter_t iter,
void *  value,
size_t  len[],
size_t *  num_arr_elem 
)

Parameters:
iter -- the pdm iterator
value -- A pointer to an array of values big enough to hold the field values
len -- An array of lengths describing the currently allocated length of each void *value array element. If it is not large enough to hold the field value, PDM_FAILURE will be returned and that len element will be set to the needed length.
num_arr_elem -- The number of elements in the value and len array.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL uint8_t lbmpdm_iter_has_next ( lbmpdm_iter_t iter  ) 

Parameters:
iter -- the pdm iterator
Returns:
PDM_TRUE if there are more fields or PDM_FALSE if this is the last field

LBMPDMExpDLL uint8_t lbmpdm_iter_is_current_set ( lbmpdm_iter_t iter  ) 

Parameters:
iter -- the pdm iterator
Returns:
PDM_TRUE if the current field is set or PDM_FALSE if it is not

LBMPDMExpDLL int lbmpdm_iter_next ( lbmpdm_iter_t iter  ) 

Parameters:
iter -- the pdm iterator
Returns:
PDM_SUCCESS if successful or PDM_ERR_NO_MORE_FIELDS if moved beyond the last field

LBMPDMExpDLL int lbmpdm_iter_set_current_field_value ( lbmpdm_iter_t iter,
void *  value,
size_t  len 
)

Parameters:
iter -- the pdm iterator
value -- the new field value
len -- the len of the enw field value
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_set_current_field_value_vec ( lbmpdm_iter_t iter,
void *  value,
size_t  len[],
size_t  num_arr_elem 
)

Parameters:
iter -- the pdm iterator
value -- A pointer to an array of values that should be set into the message
len -- A size_t array describing the currently allocated lengths of each element in the value array For fixed length types, setting a len element to 0 will allow it to default to the fixed length size of the type.
num_arr_elem -- The number of elements in the value and len array.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_iter_set_msg ( lbmpdm_iter_t iter,
lbmpdm_msg_t message 
)

Parameters:
iter -- the pdm iterator
message -- the pdm message to step through
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_and_defn_delete ( lbmpdm_msg_t message  ) 

See also:
lbmpdm_msg_create()
Parameters:
message -- A pointer to a PDM message object.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_create ( lbmpdm_msg_t **  message,
lbmpdm_defn_t defn,
uint32_t  flags 
)

Parameters:
message -- pointer to the newly created message
defn -- the definition to be used by the message
flags -- flags to set in the message
Returns:
PDM_SUCCESS or PDM_FAILURE

LBMPDMExpDLL int lbmpdm_msg_delete ( lbmpdm_msg_t message  ) 

See also:
lbmpdm_msg_create()
Parameters:
message -- A pointer to a PDM message object.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_deserialize ( lbmpdm_msg_t message,
const char *  bufptr,
uint32_t  buflen 
)

This will take the passed buffer and deserialize the contents into a newly created message. It will verify that the buffer is a valid PDM message before trying to deserialize. When finished with the message, the caller must call lbmpdm_msg_delete() to properly dispose of the message.

See also:
lbmpdm_msg_delete()
Parameters:
message A pointer to a previously created PDM message object
bufptr The buffer to be deserialized
buflen The length of the buffer.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL char* lbmpdm_msg_get_data ( lbmpdm_msg_t message  ) 

Parameters:
message A PDM Message to be serialized
Returns:
a valid char * or NULL if an error occurred.

LBMPDMExpDLL lbmpdm_defn_t* lbmpdm_msg_get_defn ( const lbmpdm_msg_t message  ) 

Parameters:
message -- A pointer to a PDM message object.
Returns:
the message definition

LBMPDMExpDLL int lbmpdm_msg_get_field_value ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle,
void *  value,
size_t *  len 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
value -- A pointer to a value big enough to hold the field value
len -- A pointer describing the currently allocated length of the void *value. If it is not large enough to hold the field value, PDM_FAILURE will be returned and len will be set to the needed length.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_get_field_value_stct ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle,
lbmpdm_field_value_t field_value 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
field_value -- A pointer to a field value structure
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_get_field_value_vec ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle,
void *  value,
size_t  len[],
size_t *  num_arr_elem 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
value -- An array of pointers with each one already allocated of sufficient length to hold each field value element
len -- An array describing the currently allocated lengths of each element of the void *value. If any len element is not large enough to hold the field value, PDM_FAILURE will be returned and the len array will be set to the needed lengths.
num_arr_elem -- A pointer to the number of allocated elements in the value and len arrays. If the number is less than the number of elements in the actual field value, PDM_FAILURE will be returned and num_arr_elem will be set to the correct value.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL uint32_t lbmpdm_msg_get_length ( const lbmpdm_msg_t message  ) 

Parameters:
message -- A pointer to a PDM message object.
Returns:
the exact length of the serialized message

LBMPDMExpDLL uint8_t lbmpdm_msg_is_field_set ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
Returns:
PDM_TRUE or PDM_FALSE

LBMPDMExpDLL int lbmpdm_msg_remove_field_value ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_serialize ( lbmpdm_msg_t message,
char *  buffer 
)

Parameters:
message A PDM Message to be serialized
buffer The caller allocated buffer
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_set_field_value ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle,
void *  value,
size_t  len 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
value -- A pointer to a value that should be set into the message
len -- A size_t describing the currently allocated length of the void *value. For fixed length types, setting len to 0 will allow it to default to the fixed length size of the type.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_set_field_value_vec ( lbmpdm_msg_t message,
lbmpdm_field_handle_t  handle,
void *  value,
size_t  len[],
size_t  num_arr_elem 
)

Parameters:
message -- A pointer to a PDM message object.
handle -- A valid field handle
value -- A pointer to an array of values that should be set into the message
len -- A size_t array describing the currently allocated lengths of each element in the value array For fixed length types, setting a len element to 0 will allow it to default to the fixed length size of the type.
num_arr_elem -- The number of elements in the value and len array.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_set_incl_defn_flag ( lbmpdm_msg_t message  ) 

Parameters:
message -- A pointer to a PDM message object.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.

LBMPDMExpDLL int lbmpdm_msg_unset_incl_defn_flag ( lbmpdm_msg_t message  ) 

Parameters:
message -- A pointer to a PDM message object.
Returns:
PDM_SUCCESS if successful or PDM_FAILURE otherwise.


Generated on Thu Mar 6 13:11:13 2014 for LBM API by  doxygen 1.5.2