lbmpdm.h

Go to the documentation of this file.

/*
        All of the documentation and software included in this and any
        other Informatica Inc. Ultra Messaging Releases
        Copyright (C) Informatica Inc. 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 Inc.

        (C) Copyright 2007,2023 Informatica Inc. 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.
*/

#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. */
#if (_MSC_VER < 1900)
        #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"
        
        /* 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"
#endif
        #define PRIuSZ "Iu"
        #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

typedef int32_t lbmpdm_field_handle_t;

typedef struct {
        int64_t mant;
        int8_t exp;
} lbmpdm_decimal_t;

typedef struct {
        int32_t tv_secs;
        int32_t tv_usecs; 
} lbmpdm_timestamp_t;

struct lbmpdm_msg_strct_t;
typedef struct lbmpdm_msg_stct_t lbmpdm_msg_t;

struct lbmpdm_defn_stct_t;
typedef struct lbmpdm_defn_stct_t lbmpdm_defn_t;

struct lbmpdm_field_info_attr_stct_t {
        int flags;
        uint8_t req;
        uint32_t fixed_str_len;
        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;

struct lbmpdm_field_value_stct_t {
        uint16_t field_type;
        uint8_t is_array;
        uint8_t is_fixed;
        size_t len;
        char *value;
        uint32_t num_arr_elem;
        size_t *len_arr;
        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;
typedef struct lbmpdm_iter_stct_t lbmpdm_iter_t;

#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

LBMPDMExpDLL int lbmpdm_errnum();

LBMPDMExpDLL const char *lbmpdm_errmsg();

LBMPDMExpDLL int lbmpdm_cache_init(uint32_t cache_size);

LBMPDMExpDLL int lbmpdm_cache_struct_add(lbmpdm_defn_t *defn);

LBMPDMExpDLL int lbmpdm_cache_struct_remove(int32_t id);

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

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

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

LBMPDMExpDLL int lbmpdm_cache_clear_all();


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

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_int_name(lbmpdm_defn_t *defn, int32_t int_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);

LBMPDMExpDLL int lbmpdm_defn_delete(lbmpdm_defn_t *defn);

LBMPDMExpDLL int lbmpdm_defn_finalize(lbmpdm_defn_t *defn);

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);

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);

LBMPDMExpDLL uint32_t lbmpdm_defn_get_length(lbmpdm_defn_t *defn);

LBMPDMExpDLL int32_t lbmpdm_defn_get_id(lbmpdm_defn_t *defn);

LBMPDMExpDLL int32_t lbmpdm_defn_get_num_fields(lbmpdm_defn_t *defn);

LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_major(lbmpdm_defn_t *defn);

LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_minor(lbmpdm_defn_t *defn);

LBMPDMExpDLL uint8_t lbmpdm_defn_get_field_names_type(lbmpdm_defn_t *defn);

LBMPDMExpDLL uint8_t lbmpdm_defn_is_finalized(lbmpdm_defn_t *defn);

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

LBMPDMExpDLL int32_t lbmpdm_defn_get_field_info_int_name(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);

LBMPDMExpDLL int16_t lbmpdm_defn_get_field_info_type(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);

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

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

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

LBMPDMExpDLL int lbmpdm_msg_delete(lbmpdm_msg_t *message);

LBMPDMExpDLL int lbmpdm_msg_and_defn_delete(lbmpdm_msg_t *message);

LBMPDMExpDLL uint32_t lbmpdm_msg_get_length(const lbmpdm_msg_t *message);

LBMPDMExpDLL lbmpdm_defn_t *lbmpdm_msg_get_defn(const lbmpdm_msg_t *message);

LBMPDMExpDLL uint8_t lbmpdm_msg_is_field_set(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle);

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

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

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);

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

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);

LBMPDMExpDLL int lbmpdm_msg_remove_field_value(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle);

LBMPDMExpDLL int lbmpdm_msg_set_incl_defn_flag(lbmpdm_msg_t *message);

LBMPDMExpDLL int lbmpdm_msg_unset_incl_defn_flag(lbmpdm_msg_t *message);

LBMPDMExpDLL int lbmpdm_field_value_stct_delete(lbmpdm_field_value_t *field_value);

LBMPDMExpDLL int lbmpdm_msg_serialize(lbmpdm_msg_t *message, char *buffer);

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

LBMPDMExpDLL char *lbmpdm_msg_get_data(lbmpdm_msg_t *message);

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

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

LBMPDMExpDLL int lbmpdm_iter_delete(lbmpdm_iter_t *iter);

LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_iter_get_current(lbmpdm_iter_t *iter);

LBMPDMExpDLL int lbmpdm_iter_first(lbmpdm_iter_t *iter);

LBMPDMExpDLL int lbmpdm_iter_next(lbmpdm_iter_t *iter);

LBMPDMExpDLL uint8_t lbmpdm_iter_has_next(lbmpdm_iter_t *iter);

LBMPDMExpDLL uint8_t lbmpdm_iter_is_current_set(lbmpdm_iter_t *iter);

LBMPDMExpDLL int lbmpdm_iter_set_msg(lbmpdm_iter_t *iter, lbmpdm_msg_t *message);

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

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

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

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_ */