lbmpdm.h

Go to the documentation of this file.

/** \file lbmpdm.h
        \brief Ultra Messaging (UM) Pre-Defined Message (PDM) API

        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 \b fields with
        each field corresponding to a specific field information object in the definition.
        Field info consists of:
        - A name (string names or integer names are supported).
        - A type (discussed below).
        - If the field is required.
        Message fields consist of:
        - A handle to the corresponding field info.
        - A value (particular to the field type).
        Each named field may only appear once in a message. If multiple fields of the same name
        and type are needed, an array field can be used to store multiple values for that field.
        PDM messages can be added as a field to other PDM messages by using the field type PDM_MESSAGE.

        \par Field types
        The following field types (and arrays thereof) are supported by PDM:
        <table>
                <tr>
                        <td>Description</td>
                        <td>PDM Type</td>
                        <td>C Type</td>
                </tr>
                <tr>
                        <td>Boolean</td>
                        <td>PDM_TYPE_BOOLEAN</td>
                        <td><tt>uint8_t</tt></td>
                </tr>
                <tr>
                        <td>8-bit signed integer</td>
                        <td>PDM_TYPE_INT8</td>
                        <td><tt>int8_t</tt></td>
                </tr>
                <tr>
                        <td>8-bit unsigned integer</td>
                        <td>PDM_TYPE_UINT8</td>
                        <td><tt>uint8_t</tt></td>
                </tr>
                <tr>
                        <td>16-bit signed integer</td>
                        <td>PDM_TYPE_INT16</td>
                        <td><tt>int16_t</tt></td>
                </tr>
                <tr>
                        <td>16-bit unsigned integer</td>
                        <td>PDM_TYPE_UINT16</td>
                        <td><tt>uint16_t</tt></td>
                </tr>
                <tr>
                        <td>32-bit signed integer</td>
                        <td>PDM_TYPE_INT32</td>
                        <td><tt>int32_t</tt></td>
                </tr>
                <tr>
                        <td>32-bit unsigned integer</td>
                        <td>PDM_TYPE_UINT32</td>
                        <td><tt>uint32_t</tt></td>
                </tr>
                <tr>
                        <td>64-bit signed integer</td>
                        <td>PDM_TYPE_INT64</td>
                        <td><tt>int64_t</tt></td>
                </tr>
                <tr>
                        <td>64-bit unsigned integer</td>
                        <td>PDM_TYPE_UINT64</td>
                        <td><tt>uint64_t</tt></td>
                </tr>
                <tr>
                        <td>Single-precision floating point</td>
                        <td>PDM_TYPE_FLOAT</td>
                        <td><tt>float</tt></td>
                </tr>
                <tr>
                        <td>Double-precision floating point</td>
                        <td>PDM_TYPE_DOUBLE</td>
                        <td><tt>double</tt></td>
                </tr>
                <tr>
                        <td>Decimal</td>
                        <td>PDM_TYPE_DECIMAL</td>
                        <td><tt>struct decimal</tt></td>
                </tr>
                <tr>
                        <td>Timestamp</td>
                        <td>PDM_TYPE_TIMESTAMP</td>
                        <td><tt>struct timestamp</tt></td>
                </tr>
                <tr>
                        <td>Fixed Length String</td>
                        <td>PDM_TYPE_FIX_STRING</td>
                        <td><tt>char *</tt></td>
                </tr>
                <tr>
                        <td>String</td>
                        <td>PDM_TYPE_STRING</td>
                        <td><tt>char *</tt></td>
                </tr>
                <tr>
                        <td>Fixed Length Unicode</td>
                        <td>PDM_TYPE_FIX_UNICODE</td>
                        <td><tt>char *</tt></td>
                </tr>
                <tr>
                        <td>Unicode</td>
                        <td>PDM_TYPE_UNICODE</td>
                        <td><tt>char *</tt></td>
                </tr>
                <tr>
                        <td>Nested PDM message</td>
                        <td>PDM_TYPE_MESSAGE</td>
                        <td><tt>lbmpdm_msg_t *</tt></td>
                </tr>
                <tr>
                        <td>Binary large object (BLOB)</td>
                        <td>PDM_TYPE_BLOB</td>
                        <td><tt>void *</tt></td>
                </tr>
        </table>
        \par
        Note that arrays are homogeneous.
        \par 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.
        \code
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);
        \endcode
        \par
        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).
        \par
        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).
        \par Sample code
        Checking of return codes has been omitted but should be done during actual usage of pdm.
        \code
{
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);
}
        \endcode
        \par Creating a message
        Messages are created from definitions.  The line above that is used to create the message:
        \code
lbmpdm_msg_create(&msg1, defn, 0);
        \endcode
        \par Setting field values in a message
        Scalar (non-array) fields are added to a message via the
        <tt>lbmpdm_msg_set_field_value()</tt> to set a field's value using its handle.
        \par
        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:
        \code
rc = lbmpdm_msg_set_field_value(msg1, h1, &quant, 0);
        \endcode
        \par
        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.
        \par Setting the value of array fields in a message
        To set an array's value in a message, call the
        <tt>lbmpdm_msg_set_field_value_vec()</tt> API function.
        \par
        As an example, the code that sets the string array field value is:
        \code
rc = lbmpdm_msg_set_field_value_vec(msg1, h2, str_arr, str_len_arr, str_arr_num_elem);
        \endcode
        \par
        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}.
        \par 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:
        \code
rc = lbmpdm_msg_serialize(msg1, msg_buffer);
rc = lbm_src_send(src, msg_buffer, msg_len, 0);
        \endcode
        \par 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:
        \code
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);
        \endcode
        \par Fetching fields from a message
        When fetching a field from a message, the field should be accessed by its handle.
        \par
        Scalar (non-array) fields may be retrieved via the <tt>lbmpdm_msg_get_field_value()</tt>.
        \code
rc = lbmpdm_msg_get_field_value(msg2, h1, &rcv_quant, &rcv_quant_sz);
        \endcode
        \par
        Array fields may be retrieved via the <tt>lbmpdm_msg_get_field_value_vec()</tt>.
        \code
rc = lbmpdm_msg_get_field_value_vec(msg2, h2, rcv_str_arr, str_len_arr, &str_arr_num_elem);
        \endcode
        \par
        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.
        \par 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.
        \code
lbmpdm_msg_delete(msg1);
lbmpdm_msg_delete(msg2);
lbmpdm_defn_delete(defn);
        \endcode
        \par 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.
        \par
        The function lbmpdm_errmsg() will return a descriptive error message.
        \par 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.
        \par
        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.
        \par
        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.
        \par
        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.
*/

/*!     \brief PDM API function return codes.
*/
#ifndef _LBMPDM_H_
#define _LBMPDM_H_

#if defined(__cplusplus)
extern "C" {
#endif

#if HAVE_STDINT_H
        #include <stdint.h>
#endif
#include <stdlib.h>

/* Directives to show how we treat exporting functions with Windows from the DLL */
#if defined(_WIN32)
        #if defined(_DLL) && defined(LBM_EXPORT_SYMS)
                #define LBMPDMExpDLL __declspec(dllexport)
        #elif defined(LBM_STATIC_LIB)
                #define LBMPDMExpDLL
        #else
                #define LBMPDMExpDLL __declspec(dllimport)
        #endif
#elif defined(__TANDEM)
        #if defined(LBM_EXPORT_SYMS)
                #define LBMPDMExpDLL export$
        #else
                #define LBMPDMExpDLL import$
        #endif
#else
        #define LBMPDMExpDLL
#endif

#if defined(_WIN32)
#if !defined(DONT_TYPEDEF_INT_T)
        typedef __int8 int8_t;
        typedef __int16 int16_t;
        typedef __int32 int32_t;
        typedef __int64 int64_t;

        typedef unsigned __int8 uint8_t;
        typedef unsigned __int16 uint16_t;
        typedef unsigned __int32 uint32_t;
        typedef unsigned __int64 uint64_t;
#endif
        /* C99 printf format macros missing from VC. */
        #define PRId8 "d"
        #define PRId16 "d"
        #define PRId32 "d"
        #define PRId64 "I64d"
        #define PRIu8 "u"
        #define PRIu16 "u"
        #define PRIu32 "u"
        #define PRIu64 "I64u"
        #define PRIx8 "x"
        #define PRIx16 "x"
        #define PRIx32 "x"
        #define PRIx64 "I64x"
        #define PRIuSZ "Iu"
        /* C99 scanf format macros missing from VC. */
        #define SCNd8 "d"
        #define SCNd16 "hd"
        #define SCNd32 "ld"
        #define SCNd64 "I64d"
        #define SCNu8 "u"
        #define SCNu16 "hu"
        #define SCNu32 "lu"
        #define SCNu64 "I64u"
        #define SCNx64 "I64x"
        #define SCNuSZ "Iu"
#elif defined(__VMS)
        #include <inttypes.h>
        /* C99 printf format macros missing from OpenVMS. */
        #define PRId8 "d"
        #define PRId16 "d"
        #define PRId32 "d"
        #define PRId64 "lld"
        #define PRIu8 "u"
        #define PRIu16 "u"
        #define PRIu32 "u"
        #define PRIu64 "llu"
        #define PRIuSZ "zu"
        /* C99 scanf format macros missing from OpenVMS. */
        #define SCNd8 "hhd"
        #define SCNd16 "hd"
        #define SCNd32 "d"
        #define SCNd64 "lld"
        #define SCNu8 "hhu"
        #define SCNu16 "hu"
        #define SCNu32 "u"
        #define SCNu64 "llu"
        #define SCNuSZ "zu"
#else
        #include <inttypes.h>
        #ifndef PRIuSZ
                #define PRIuSZ "zu"
        #endif
        #ifndef SCNuSZ
                #define SCNuSZ "zu"
        #endif
#endif

/*! \brief 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 \c lbmpdm_get_field_handle_by_str_name or
        \c lbpdm_get_field_handle_by_int_name functions.
 */
typedef int32_t lbmpdm_field_handle_t;

/*!     \brief Structure to hold a scaled decimal number.
        A scaled decimal number consists of a mantissa \f$m\f$ and an exponent \f$exp\f$.
        It represents the value \f$m\cdot 10^{exp}\f$.

        The mantissa is represented as a 64-bit signed integer.
        The exponent is represented as an 8-bit signed integer,
        and can range from -128 to 127.
*/
typedef struct {
        /*! Mantissa. */
        int64_t mant;
        /*! Exponent. */
        int8_t exp;
} lbmpdm_decimal_t;

/*!     \brief Structure to hold a timestamp value.

        The tv_secs is the number of seconds since the epoch.
        The tv_usecs is the additional microseconds since the epoch.
        and can range from -128 to 127.
*/
typedef struct {
        /*! Seconds since epoch */
        int32_t tv_secs;
        /*! Microseconds since last second */
        int32_t tv_usecs; 
} lbmpdm_timestamp_t;

struct lbmpdm_msg_strct_t;
/*!     \brief Structure to hold a pdm message.
*/
typedef struct lbmpdm_msg_stct_t lbmpdm_msg_t;

struct lbmpdm_defn_stct_t;
/*!     \brief Structure to hold a pdm definition.
*/
typedef struct lbmpdm_defn_stct_t lbmpdm_defn_t;

/*! \brief Attribute struct to be passed along with the name
        when adding field info to a definition
 */
struct lbmpdm_field_info_attr_stct_t {
        int flags;
        /*! If the field is required or not. */
        uint8_t req;
        /*! The number of characters for fixed string or fixed unicode types. */
        uint32_t fixed_str_len;
        /*! The number of elements for fixed arrays. */
        uint32_t num_arr_elem;
        /* Fill for external pdm struct for future binary compatibility. */
        char fill[256];
};
typedef struct lbmpdm_field_info_attr_stct_t lbmpdm_field_info_attr_t;

/*! \brief Field value struct that can be populated with a field value when passed
        to the lbmpdm_msg_get_field_value_stct function.
 */
struct lbmpdm_field_value_stct_t {
        /*! The field type. */
        uint16_t field_type;
        /*! If the field is an array */
        uint8_t is_array;
        /*! If the field is a fixed length field. */
        uint8_t is_fixed;
        /*! The length in bytes of the field for scalar fields. */
        size_t len;
        /*! A pointer to the field value for scalar fields. */
        char *value;
        /*! The number of elements in the array for array fields. */
        uint32_t num_arr_elem;
        /*! An array of size_t representing the length in bytes for each array element for array fields. */
        size_t *len_arr;
        /*! An array of pointers to the field values for array fields. */
        char **value_arr;
        /* Fill for external pdm struct for future binary compatibility. */
        char fill[256];
};
typedef struct lbmpdm_field_value_stct_t lbmpdm_field_value_t;

struct lbmpdm_iter_stct_t;
/*! \brief Iterator structure that is used to traverse the fields of a message.
 */
typedef struct lbmpdm_iter_stct_t lbmpdm_iter_t;

/*! PDM true/false values. PDM value for FALSE. */
#define PDM_FALSE (uint8_t) 0

/*! PDM true/false values. PDM value for TRUE. */
#define PDM_TRUE (uint8_t) 1

/*! PDM Field Info Flags. Field is required. */
#define PDM_FIELD_INFO_FLAG_REQ 0x1

/*! PDM Field Info Flags. Field has a fixed string length (for string and unicode types). */
#define PDM_FIELD_INFO_FLAG_FIXED_STR_LEN 0x2

/*! PDM Field Info Flags. Field has a fixed array size (for array types). */
#define PDM_FIELD_INFO_FLAG_NUM_ARR_ELEM 0x4

/*! PDM Message Flags. If any variable or optional fields have been set (set internally). */
#define PDM_MSG_FLAG_VAR_OR_OPT_FLDS_SET 0x1

/*! PDM Message Flags. If the definition should be serialized with the message. */
#define PDM_MSG_FLAG_INCL_DEFN 0x2

/*! PDM Message Flags. If a message should override its existing definition with one included when deserializing a message. */
#define PDM_MSG_FLAG_USE_MSG_DEFN_IF_NEEDED 0x4

/*! PDM Message Flags. If a message should try to load a needed definition from the cache when deserializing. */
#define PDM_MSG_FLAG_TRY_LOAD_DEFN_FROM_CACHE 0x8

/*! PDM Message Flags. If the field values need bytes to be swapped (set internally). */
#define PDM_MSG_FLAG_NEED_BYTE_SWAP 0x10

/*! PDM Message Flags. If a message's existing definition should be deleted when replaced when deserializing a message. */
#define PDM_MSG_FLAG_DEL_DEFN_WHEN_REPLACED 0x20

/*! PDM Message Version Policy. Use Exact Match versioning Policy. */
#define PDM_MSG_VER_POLICY_EXACT 0

/*! PDM Message Version Policy. Use Best Match versioning Policy. */
#define PDM_MSG_VER_POLICY_BEST 1

/*! PDM Return Code. Operation was successful. */
#define PDM_SUCCESS 0

/*! PDM Return Code. Operation failed. See lbmpdm_errnum() or lbmpdm_errmsg() for the reason. */
#define PDM_FAILURE -1

/*! PDM Error Code. Field is null. */
#define PDM_ERR_FIELD_IS_NULL 1

/*! PDM Error Code. No more fields to iterate over. */
#define PDM_ERR_NO_MORE_FIELDS 2

/*! PDM Error Code. Insufficient buffer length given. */
#define PDM_ERR_INSUFFICIENT_BUFFER_LENGTH 3

/*! PDM Error Code. Invalid parameter given. */
#define PDM_ERR_EINVAL 4

/*! PDM Error Code. Field not found. */
#define PDM_ERR_FIELD_NOT_FOUND 5

/*! PDM Error Code. Not a valid PDM message. */
#define PDM_ERR_MSG_INVALID 6

/*! PDM Error Code. Not a valid PDM definition. */
#define PDM_ERR_DEFN_INVALID 7

/*! PDM Error Code. No memory available. */
#define PDM_ERR_NOMEM 8

/*! PDM Error Code. Required field not set. */
#define PDM_ERR_REQ_FIELD_NOT_SET 9

/*! PDM Error Code. Error creating field section. */
#define PDM_ERR_CREATE_SECTION 10

/*! PDM Error Code. Error creating buffer. */
#define PDM_ERR_CREATE_BUFFER 11

/*! PDM Field Type. Invalid Type. */
#define PDM_INTERNAL_TYPE_INVALID -1

/*! PDM Field Type. boolean. */
#define PDM_TYPE_BOOLEAN 0

/*! PDM Field Type. 8 bit integer. */
#define PDM_TYPE_INT8 1

/*! PDM Field Type. unsigned 8 bit integer. */
#define PDM_TYPE_UINT8 2

/*! PDM Field Type. 16 bit integer. */
#define PDM_TYPE_INT16 3

/*! PDM Field Type. unsigned 16 bit integer. */
#define PDM_TYPE_UINT16 4

/*! PDM Field Type. 32 bit integer. */
#define PDM_TYPE_INT32 5

/*! PDM Field Type. unsigned 32 bit integer. */
#define PDM_TYPE_UINT32 6

/*! PDM Field Type. 64 bit integer. */
#define PDM_TYPE_INT64 7

/*! PDM Field Type. unsigned 64 bit integer. */
#define PDM_TYPE_UINT64 8

/*! PDM Field Type. float. */
#define PDM_TYPE_FLOAT 9

/*! PDM Field Type. double. */
#define PDM_TYPE_DOUBLE 10

/*! PDM Field Type. decimal. */
#define PDM_TYPE_DECIMAL 11

/*! PDM Field Type. timestamp. */
#define PDM_TYPE_TIMESTAMP 12

/*! PDM Field Type. fixed string. */
#define PDM_TYPE_FIX_STRING 13

/*! PDM Field Type. string (variable length). */
#define PDM_TYPE_STRING 14

/*! PDM Field Type. fixed unicode. */
#define PDM_TYPE_FIX_UNICODE 15

/*! PDM Field Type. unicode (variable length). */
#define PDM_TYPE_UNICODE 16

/*! PDM Field Type. blob (variable length). */
#define PDM_TYPE_BLOB 17

/*! PDM Field Type. PDM message (variable length). */
#define PDM_TYPE_MESSAGE 18

/*! PDM Field Type. boolean array. */
#define PDM_TYPE_BOOLEAN_ARR 19

/*! PDM Field Type. 8 bit integer array. */
#define PDM_TYPE_INT8_ARR 20

/*! PDM Field Type. unsigned 8 bit integer array. */
#define PDM_TYPE_UINT8_ARR 21

/*! PDM Field Type. 16 bit integer array. */
#define PDM_TYPE_INT16_ARR 22

/*! PDM Field Type. unsigned 16 bit integer array. */
#define PDM_TYPE_UINT16_ARR 23

/*! PDM Field Type. 32 bit integer array. */
#define PDM_TYPE_INT32_ARR 24

/*! PDM Field Type. unsigned 32 bit integer array. */
#define PDM_TYPE_UINT32_ARR 25

/*! PDM Field Type. 64 bit integer array. */
#define PDM_TYPE_INT64_ARR 26

/*! PDM Field Type. unsigned 64 bit integer array. */
#define PDM_TYPE_UINT64_ARR 27

/*! PDM Field Type. float array. */
#define PDM_TYPE_FLOAT_ARR 28

/*! PDM Field Type. double array. */
#define PDM_TYPE_DOUBLE_ARR 29

/*! PDM Field Type. decimal array. */
#define PDM_TYPE_DECIMAL_ARR 30

/*! PDM Field Type. timestamp array. */
#define PDM_TYPE_TIMESTAMP_ARR 31

/*! PDM Field Type. fixed string array. */
#define PDM_TYPE_FIX_STRING_ARR 32

/*! PDM Field Type. string array. */
#define PDM_TYPE_STRING_ARR 33

/*! PDM Field Type. fixed unicode array. */
#define PDM_TYPE_FIX_UNICODE_ARR 34

/*! PDM Field Type. unicode array. */
#define PDM_TYPE_UNICODE_ARR 35

/*! PDM Field Type. blob array. */
#define PDM_TYPE_BLOB_ARR 36

/*! PDM Field Type. PDM message array. */
#define PDM_TYPE_MESSAGE_ARR 37

/*! PDM Field Name Type. Use string field names. */
#define PDM_DEFN_STR_FIELD_NAMES 0

/*! PDM Field Name Type. Use integer field names. */
#define PDM_DEFN_INT_FIELD_NAMES 1

/*! PDM Iterator Invalid Handle. Indicates invalid field handle. */
#define PDM_ITER_INVALID_FIELD_HANDLE -1

/*! \brief Return the error number last encountered by this thread.
        \return An integer error number.
 */
LBMPDMExpDLL int lbmpdm_errnum();

/*! \brief Return an ASCII string containing the error message last encountered
        by this thread.
        \return Pointer to a static char array holding the error message.
 */
LBMPDMExpDLL const char *lbmpdm_errmsg();

/*! \brief 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.
        \param cache_size -- how many buckets should this hash contain?  If
         set to zero this will default.
 */
LBMPDMExpDLL int lbmpdm_cache_init(uint32_t cache_size);

/*! \brief 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.
        \param defn -- the new definition structure being added.
 */
LBMPDMExpDLL int lbmpdm_cache_struct_add(lbmpdm_defn_t *defn);

/*! \brief delete a definition structure from the cache. Does not error if the
        structure doesn't exist.
        \param id -- id of the structure being deleted.  If the id
        is not found this will do nothing.
 */
LBMPDMExpDLL int lbmpdm_cache_struct_remove(int32_t id);

/*! \brief delete a definition structure from the cache by its id and version.
        Does not error if the structure doesn't exist.
        \param id -- id of the structure being deleted.  If the id
        is not found this will do nothing.
        \param vers_major -- major version of the definition
        \param vers_minor -- minor version of the definition
 */
LBMPDMExpDLL int lbmpdm_cache_struct_remove_by_version(int32_t id, uint8_t vers_major, uint8_t vers_minor);

/*! \brief 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.
        \param defn -- pointer to the structure to return.  This
        field is not altered if nothing is found for a given id.
        \param id -- id to search for in the hash.
 */
LBMPDMExpDLL int lbmpdm_cache_struct_find(lbmpdm_defn_t **defn, int32_t id);

/*! \brief 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.
        \param defn -- pointer to the structure to return.  This
        field is not altered if nothing is found for a given id.
        \param id -- id to search for in the hash.
        \param vers_major -- major version to search for in the hash.
        \param vers_minor -- minor version 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);

/*! \brief nuke the whole cache, this deletes all the structures within
        the cache as well.
 */
LBMPDMExpDLL int lbmpdm_cache_clear_all();


/*! \brief Retrieve a field handle from a definition via name.
 *      \param defn -- definition created from lbmpdm_defn_create.
 *      \param str_name -- the name of the field to be retrieved.
 *      \return 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);

/*! \brief Retrieve a field handle from a definition via name.
 *      \param defn -- definition created from lbmpdm_defn_create.
 *      \param int_name -- the name of the field to be retrieved.
 *      \return A valid field handle on success, PDM_FAILURE otherwise.
 */
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_int_name(lbmpdm_defn_t *defn, int32_t int_name);

/*! \brief 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.
        \param defn -- pointer to newly created definition.
        \param num_fields -- how many fields to initially assume we will
        have, this is for optimization, not a limit to how many fields.
        \param id -- This is the id for the definition.  It is assumed
        that this is a unique id.
        \param 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.
        \param vrs_mnr -- A version minor number
        \param 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.
        \return 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);

/*! \brief delete a given definition. 
        \param defn -- definition to be deleted.
        \return PDM_SUCCESS or PDM_FAILURE.
 */
LBMPDMExpDLL int lbmpdm_defn_delete(lbmpdm_defn_t *defn);

/*! \brief make this definition final.  This needs to be done before using
        it in a message.
        \param defn -- the definition to be finalized.
        \return PDM_SUCCESS or PDM_FAILURE
 */
LBMPDMExpDLL int lbmpdm_defn_finalize(lbmpdm_defn_t *defn);

/*! \brief adds field info to the definition by string name
        \param str_name -- the string name
        \param type -- the PDM field type
        \param info_attr -- the field information attributes
        \return 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);

/*! \brief adds field info to the definition by integer name
        \param int_name -- the integer name
        \param type -- the PDM field type
        \param info_attr -- the field information attributes
        \return PDM_SUCCESS or PDM_FAILURE
 */
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);

/*! \brief 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.
        \param defn -- A pointer to a PDM defn object.
        \return the exact length of the serialized defn
 */
LBMPDMExpDLL uint32_t lbmpdm_defn_get_length(lbmpdm_defn_t *defn);

/*! \brief Gets the id of the definition.
        \param defn -- A pointer to a PDM defn object.
        \return the id of the definition
 */
LBMPDMExpDLL int32_t lbmpdm_defn_get_id(lbmpdm_defn_t *defn);

/*! \brief Gets the number of fields in the definition
        \param defn -- A pointer to a PDM defn object.
        \return the number of fields in the definition
 */
LBMPDMExpDLL int32_t lbmpdm_defn_get_num_fields(lbmpdm_defn_t *defn);

/*! \brief Gets the message major version number from the definition
        \param defn -- A pointer to a PDM defn object.
        \return the major version number
 */
LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_major(lbmpdm_defn_t *defn);

/*! \brief Gets the message minor version number from the definition
        \param defn -- A pointer to a PDM defn object.
        \return the minor version number
 */
LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_minor(lbmpdm_defn_t *defn);

/*! \brief Gets the field names type (either PDM_DEFN_STR_FIELD_NAMES or PDM_DEFN_INT_FIELD_NAMES)
        from the definition.
        \param defn -- A pointer to a PDM defn object.
        \return the field names type
 */
LBMPDMExpDLL uint8_t lbmpdm_defn_get_field_names_type(lbmpdm_defn_t *defn);

/*! \brief Gets whether or not the definition has been finalized (either PDM_TRUE or PDM_FALSE).
        \param defn -- A pointer to a PDM defn object.
        \return the value indicating whether or not the definition has been finalized
 */
LBMPDMExpDLL uint8_t lbmpdm_defn_is_finalized(lbmpdm_defn_t *defn);

/*! \brief Gets the string field name from a given definition's field handle.
        \param defn -- A pointer to a PDM defn object.
        \param handle -- A valid field handle from the definition.
        \return the string field name or NULL.
 */
LBMPDMExpDLL const char *lbmpdm_defn_get_field_info_str_name(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);

/*! \brief Gets the integer field name from a given definition's field handle.
        \param defn -- A pointer to a PDM defn object.
        \param handle -- A valid field handle from the definition.
        \return the int field name or -1.
 */
LBMPDMExpDLL int32_t lbmpdm_defn_get_field_info_int_name(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);

/*! \brief Gets the PDM field type from a given definition's field handle.
        \param defn -- A pointer to a PDM defn object.
        \param handle -- A valid field handle from the definition.
        \return the PDM type or PDM_INTERNAL_TYPE_INVALID.
 */
LBMPDMExpDLL int16_t lbmpdm_defn_get_field_info_type(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);

/*! \brief 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.
        \param defn A PDM defn to be serialized
        \param buffer The caller allocated buffer
        \param defn_len Will be set to the length of the definition
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_defn_serialize(lbmpdm_defn_t *defn, char *buffer, uint32_t *defn_len);

/*! \brief Deserialize the associated buffer into a newly created defn

        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.

        \sa lbmpdm_msg_delete()
        \param defn A pointer to a previously created PDM defn object
        \param bufptr The buffer to be deserialized
        \param buflen The length of the buffer.
        \param swap_bytes Whether or not bytes should be swapped to deal with endianness.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_defn_deserialize(lbmpdm_defn_t *defn, const char *bufptr, uint32_t buflen, uint8_t swap_bytes);

/*! \brief creates a message with the specified definition
        \param message -- pointer to the newly created message
        \param defn -- the definition to be used by the message
        \param flags -- flags to set in the message
        \return PDM_SUCCESS or PDM_FAILURE
 */
LBMPDMExpDLL int lbmpdm_msg_create(lbmpdm_msg_t **message, lbmpdm_defn_t *defn, uint32_t flags);

/*! \brief 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.
        \sa lbmpdm_msg_create()
        \param message --  A pointer to a PDM message object.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_delete(lbmpdm_msg_t *message);

/*! \brief 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.
        \sa lbmpdm_msg_create()
        \param message --  A pointer to a PDM message object.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_and_defn_delete(lbmpdm_msg_t *message);

/*! \brief 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.
        \param message -- A pointer to a PDM message object.
        \return the exact length of the serialized message
 */
LBMPDMExpDLL uint32_t lbmpdm_msg_get_length(const lbmpdm_msg_t *message);

/*! \brief Gets a pointer to the message definition.
        \param message -- A pointer to a PDM message object.
        \return the message definition
 */
LBMPDMExpDLL lbmpdm_defn_t *lbmpdm_msg_get_defn(const lbmpdm_msg_t *message);

/*! \brief Gets whether or not the field value has been set.
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \return PDM_TRUE or PDM_FALSE
 */
LBMPDMExpDLL uint8_t lbmpdm_msg_is_field_set(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle);

/*! \brief Populates a field value struct with the value from the message.
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \param field_value -- A pointer to a field value structure
        \return 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);

/*! \brief Gets a field value from the message
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \param value -- A pointer to a value big enough to hold the field value
        \param 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.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_get_field_value(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t *len);

/*! \brief Gets an array of field values from the message
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \param value -- An array of pointers with each one already allocated of sufficient length to hold each field value element
        \param 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.
        \param 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.
        \return 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);

/*! \brief Sets a field value in a message
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \param value -- A pointer to a value that should be set into the message
        \param 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.
        \return 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);

/*! \brief Sets an array of field values in a message
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \param value -- A pointer to an array of values that should be set into the message
        \param 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.
        \param num_arr_elem -- The number of elements in the value and len array.
        \return 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);

/*! \brief Removes a field value from a message (marking it unset)
        \param message -- A pointer to a PDM message object.
        \param handle -- A valid field handle
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_remove_field_value(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle);

/*! \brief Sets the message include definition flag.
        \param message -- A pointer to a PDM message object.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_set_incl_defn_flag(lbmpdm_msg_t *message);

/*! \brief Unsets the message include definition flag.
        \param message -- A pointer to a PDM message object.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_unset_incl_defn_flag(lbmpdm_msg_t *message);

/*! \brief 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.
        \sa lbmpdm_msg_get_field_value_stct
        \param field_value -- A pointer to a field value structure.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_field_value_stct_delete(lbmpdm_field_value_t *field_value);

/*! \brief Serialize a message to a buffer.
        The message that is passed in is serialized into the
        caller's supplied buffer.
        \param message A PDM Message to be serialized
        \param buffer The caller allocated buffer
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_serialize(lbmpdm_msg_t *message, char *buffer);

/*! \brief Deserialize the associated buffer into a newly created message

        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.

        \sa lbmpdm_msg_delete()
        \param message A pointer to a previously created PDM message object
        \param bufptr The buffer to be deserialized
        \param buflen The length of the buffer.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_msg_deserialize(lbmpdm_msg_t *message, const char *bufptr, uint32_t buflen);

/*! \brief 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.
        \param message A PDM Message to be serialized
        \return a valid char * or NULL if an error occurred.
 */
LBMPDMExpDLL char *lbmpdm_msg_get_data(lbmpdm_msg_t *message);

/*! \brief Creates a pdm iterator to iterate through the fields in a message
        \param iter -- Pointer to the iterator pointer which will be created
        \param message -- the pdm message
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_iter_create(lbmpdm_iter_t **iter, lbmpdm_msg_t *message);

/*! \brief Creates a pdm iterator to iterate through the fields in a message starting at a particular field
        \param iter -- Pointer to the iterator pointer which will be created
        \param message -- the pdm message
        \param field_handle -- the handle to the field where the iterator should start
        \return 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);

/*! \brief Deletes the iterator
        \param iter -- the pdm iterator
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_iter_delete(lbmpdm_iter_t *iter);

/*! \brief Gets the current field handle from the iterator
        \param iter -- The pdm iterator
        \return the lbmpdm_field_handle_t (field handle)
 */
LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_iter_get_current(lbmpdm_iter_t *iter);

/*! \brief Sets the iterator back to the first field
        \param iter -- the pdm iterator
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_iter_first(lbmpdm_iter_t *iter);

/*! \brief Steps the iterator to the next first field
        \param iter -- the pdm iterator
        \return PDM_SUCCESS if successful or PDM_ERR_NO_MORE_FIELDS if moved beyond the last field
 */
LBMPDMExpDLL int lbmpdm_iter_next(lbmpdm_iter_t *iter);

/*! \brief Checks to see if the iterator has another field to step to
        \param iter -- the pdm iterator
        \return PDM_TRUE if there are more fields or PDM_FALSE if this is the last field
 */
LBMPDMExpDLL uint8_t lbmpdm_iter_has_next(lbmpdm_iter_t *iter);

/*! \brief Checks to see if the current field is set
        \param iter -- the pdm iterator
        \return PDM_TRUE if the current field is set or PDM_FALSE if it is not
 */
LBMPDMExpDLL uint8_t lbmpdm_iter_is_current_set(lbmpdm_iter_t *iter);

/*! \brief Sets the message used to step through by this iterator
        \param iter -- the pdm iterator
        \param message -- the pdm message to step through
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_iter_set_msg(lbmpdm_iter_t *iter, lbmpdm_msg_t *message);

/*! \brief Sets the current field value to the value passed in
        \param iter -- the pdm iterator
        \param value -- the new field value
        \param len -- the len of the enw field value
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_iter_set_current_field_value(lbmpdm_iter_t *iter, void *value, size_t len);

/*! \brief Sets the current field values to the passed array of values
        \param iter -- the pdm iterator
        \param value -- A pointer to an array of values that should be set into the message
        \param 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.
        \param num_arr_elem -- The number of elements in the value and len array.
        \return 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);

/*! \brief Gets a field value from the iterator's current field
        \param iter -- the pdm iterator
        \param value -- A pointer to a value big enough to hold the field value
        \param 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.
        \param num_arr_elem -- The number of elements in the value and len array.
        \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
 */
LBMPDMExpDLL int lbmpdm_iter_get_current_field_value(lbmpdm_iter_t *iter, void *value, size_t *len);

/*! \brief Gets an array of field values from the iterator's current field
        \param iter -- the pdm iterator
        \param value -- A pointer to an array of values big enough to hold the field values
        \param 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.
        \param num_arr_elem -- The number of elements in the value and len array.
        \return 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);

#if defined(__cplusplus)
}
#endif /* __cplusplus */

#endif /* _LBMPDM_H_ */

---