lbmpdm.h

Go to the documentation of this file.
00001 /** \file lbmpdm.h
00002         \brief Ultra Messaging (UM) Pre-Defined Message (PDM) API
00003 
00004         The Ultra Messaging (UM) Pre-Defined Message (PDM)
00005         API Description. Included are types, constants, and functions related
00006         to the API. Contents are subject to change.
00007 
00008         All of the documentation and software included in this and any
00009         other Informatica Corporation Ultra Messaging Releases
00010         Copyright (C) Informatica Corporation. All rights reserved.
00011 
00012         Redistribution and use in source and binary forms, with or without
00013         modification, are permitted only as covered by the terms of a
00014         valid software license agreement with Informatica Corporation.
00015 
00016         Copyright (C) 2007-2014, Informatica Corporation. All Rights Reserved.
00017 
00018         THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES
00019         EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF
00020         NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
00021         PURPOSE.  INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE
00022         UNINTERRUPTED OR ERROR-FREE.  INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE
00023         LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR
00024         INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE
00025         TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF
00026         THE LIKELIHOOD OF SUCH DAMAGES.
00027 
00028         The LBM Pre-Defined Message(PDM) API provides a framework for applications
00029         to create message definitions and messages from those definitions.
00030         A PDM definition contains a list of field information describing the fields
00031         that will be contained in a message. A PDM message contains one or more \b fields with
00032         each field corresponding to a specific field information object in the definition.
00033         Field info consists of:
00034         - A name (string names or integer names are supported).
00035         - A type (discussed below).
00036         - If the field is required.
00037         Message fields consist of:
00038         - A handle to the corresponding field info.
00039         - A value (particular to the field type).
00040         Each named field may only appear once in a message. If multiple fields of the same name
00041         and type are needed, an array field can be used to store multiple values for that field.
00042         PDM messages can be added as a field to other PDM messages by using the field type PDM_MESSAGE.
00043 
00044         \par Field types
00045         The following field types (and arrays thereof) are supported by PDM:
00046         <table>
00047                 <tr>
00048                         <td>Description</td>
00049                         <td>PDM Type</td>
00050                         <td>C Type</td>
00051                 </tr>
00052                 <tr>
00053                         <td>Boolean</td>
00054                         <td>PDM_TYPE_BOOLEAN</td>
00055                         <td><tt>uint8_t</tt></td>
00056                 </tr>
00057                 <tr>
00058                         <td>8-bit signed integer</td>
00059                         <td>PDM_TYPE_INT8</td>
00060                         <td><tt>int8_t</tt></td>
00061                 </tr>
00062                 <tr>
00063                         <td>8-bit unsigned integer</td>
00064                         <td>PDM_TYPE_UINT8</td>
00065                         <td><tt>uint8_t</tt></td>
00066                 </tr>
00067                 <tr>
00068                         <td>16-bit signed integer</td>
00069                         <td>PDM_TYPE_INT16</td>
00070                         <td><tt>int16_t</tt></td>
00071                 </tr>
00072                 <tr>
00073                         <td>16-bit unsigned integer</td>
00074                         <td>PDM_TYPE_UINT16</td>
00075                         <td><tt>uint16_t</tt></td>
00076                 </tr>
00077                 <tr>
00078                         <td>32-bit signed integer</td>
00079                         <td>PDM_TYPE_INT32</td>
00080                         <td><tt>int32_t</tt></td>
00081                 </tr>
00082                 <tr>
00083                         <td>32-bit unsigned integer</td>
00084                         <td>PDM_TYPE_UINT32</td>
00085                         <td><tt>uint32_t</tt></td>
00086                 </tr>
00087                 <tr>
00088                         <td>64-bit signed integer</td>
00089                         <td>PDM_TYPE_INT64</td>
00090                         <td><tt>int64_t</tt></td>
00091                 </tr>
00092                 <tr>
00093                         <td>64-bit unsigned integer</td>
00094                         <td>PDM_TYPE_UINT64</td>
00095                         <td><tt>uint64_t</tt></td>
00096                 </tr>
00097                 <tr>
00098                         <td>Single-precision floating point</td>
00099                         <td>PDM_TYPE_FLOAT</td>
00100                         <td><tt>float</tt></td>
00101                 </tr>
00102                 <tr>
00103                         <td>Double-precision floating point</td>
00104                         <td>PDM_TYPE_DOUBLE</td>
00105                         <td><tt>double</tt></td>
00106                 </tr>
00107                 <tr>
00108                         <td>Decimal</td>
00109                         <td>PDM_TYPE_DECIMAL</td>
00110                         <td><tt>struct decimal</tt></td>
00111                 </tr>
00112                 <tr>
00113                         <td>Timestamp</td>
00114                         <td>PDM_TYPE_TIMESTAMP</td>
00115                         <td><tt>struct timestamp</tt></td>
00116                 </tr>
00117                 <tr>
00118                         <td>Fixed Length String</td>
00119                         <td>PDM_TYPE_FIX_STRING</td>
00120                         <td><tt>char *</tt></td>
00121                 </tr>
00122                 <tr>
00123                         <td>String</td>
00124                         <td>PDM_TYPE_STRING</td>
00125                         <td><tt>char *</tt></td>
00126                 </tr>
00127                 <tr>
00128                         <td>Fixed Length Unicode</td>
00129                         <td>PDM_TYPE_FIX_UNICODE</td>
00130                         <td><tt>char *</tt></td>
00131                 </tr>
00132                 <tr>
00133                         <td>Unicode</td>
00134                         <td>PDM_TYPE_UNICODE</td>
00135                         <td><tt>char *</tt></td>
00136                 </tr>
00137                 <tr>
00138                         <td>Nested PDM message</td>
00139                         <td>PDM_TYPE_MESSAGE</td>
00140                         <td><tt>lbmpdm_msg_t *</tt></td>
00141                 </tr>
00142                 <tr>
00143                         <td>Binary large object (BLOB)</td>
00144                         <td>PDM_TYPE_BLOB</td>
00145                         <td><tt>void *</tt></td>
00146                 </tr>
00147         </table>
00148         \par
00149         Note that arrays are homogeneous.
00150         \par Creating a message definition
00151         A message definition must be defined (via lbmpdm_defn_create())
00152         before a message can be created.  After creating the definition, field info
00153         can be added.  Once all field information has been added to a definition, the definition
00154         must be finalized (lbmpdm_defn_finalize()).  Each definition must be given an id
00155         to identify that definition (and messages created with the definition) to all
00156         consumers of the message.  This allows all messaging participants to define the
00157         message and for PDM to quickly deserialize the messages.
00158         As an example, we will create a simple definition with two fields, a 32-bit signed
00159         integer and a string array.  We will give the definition an id of 1000.
00160         \code
00161 lbmpdm_defn_t *defn;
00162 lbmpdm_field_handle_t h1;
00163 lbmpdm_field_handle_t h2;
00164 lbmpdm_field_info_attr_t info_attr;
00165 
00166 if (lbmpdm_defn_create(&defn, 2, 1000, 1, 0, PDM_DEFN_STR_FIELD_NAMES) != PDM_SUCCESS) {
00167   printf("Failed to create the definition");
00168   return;
00169 }
00170 
00171 info_attr.flags = 0;
00172 
00173 h1 = lbmpdm_defn_add_field_info_by_str_name(defn, "Field1", PDM_TYPE_INT32, NULL);
00174 
00175 info_attr.flags |= PDM_FIELD_INFO_FLAG_REQ;
00176 info_attr.req = PDM_FALSE;
00177 h2 = lbmpdm_defn_add_field_info_by_str_name(defn, "Field2", PDM_TYPE_STRING_ARR, &info_attr);
00178 
00179 lbmpdm_defn_finalize(defn);
00180         \endcode
00181         \par
00182         The values of the info_attr struct will only be examined if the corresponding PDM_FIELD_INFO_FLAG_*
00183         has been set when it is passed to the add_field_info function.  If NULL is passed instead of an
00184         info_attr pointer or any of the flags are not set, then default values will be used when adding
00185         the field info(which are: required = PDM_TRUE, fixed string length = 0,
00186         and number of array elements = 0).
00187         \par
00188         Once the definition exists, a message can be created and field values can be
00189         set in the message.  The fields can be set by using the field handle
00190         that was returned from the call to the definition to add field info
00191         (or the field handle can be looked up from the definition).
00192         \par Sample code
00193         Checking of return codes has been omitted but should be done during actual usage of pdm.
00194         \code
00195 {
00196 int rc;
00197 lbmpdm_msg_t *msg1;
00198 lbmpdm_msg_t *msg2;
00199 char *msg_buffer;
00200 int msg_len;
00201 
00202 int32_t quant = 50;
00203 char *str_arr[3] = {"s1", "str2", "string3"};
00204 size_t str_len_arr[3] = {3, 5, 8};
00205 size_t str_arr_num_elem = 3;
00206 
00207 int32_t rcv_quant;
00208 size_t rcv_quant_sz = sizeof(int32_t);
00209 char *rcv_str_arr[3];
00210 rcv_str_arr[0] = malloc(3);
00211 rcv_str_arr[1] = malloc(5);
00212 rcv_str_arr[2] = malloc(8);
00213 
00214 lbmpdm_msg_create(&msg1, defn, 0);
00215 
00216 rc = lbmpdm_msg_set_field_value(msg1, h1, &quant, 0);
00217 rc = lbmpdm_msg_set_field_value_vec(msg1, h2, str_arr, str_len_arr, str_arr_num_elem);
00218 
00219 msg_len = lbmpdm_msg_get_length(msg1);
00220 msg_buffer = malloc(msg_len);
00221 rc = lbmpdm_msg_serialize(msg1, msg_buffer);
00222 
00223 rc = lbmpdm_msg_create(&msg2, defn, 0);
00224 rc = lbmpdm_msg_deserialize(msg2, msg_buffer, msg_len);
00225 
00226 rc = lbmpdm_msg_get_field_value(msg2, h1, &rcv_quant, &rcv_quant_sz);
00227 rc = lbmpdm_msg_get_field_value_vec(msg2, h2, rcv_str_arr, str_len_arr, &str_arr_num_elem);
00228 
00229 printf("rcv_quant = %d\n", rcv_quant);
00230 printf("rcv_str_arr[0] = %s\n", rcv_str_arr[0]);
00231 printf("rcv_str_arr[1] = %s\n", rcv_str_arr[1]);
00232 printf("rcv_str_arr[2] = %s\n", rcv_str_arr[2]);
00233 
00234 free(rcv_str_arr[0]);
00235 free(rcv_str_arr[1]);
00236 free(rcv_str_arr[2]);
00237 
00238 free(msg_buffer);
00239 
00240 lbmpdm_msg_delete(msg1);
00241 lbmpdm_msg_delete(msg2);
00242 lbmpdm_defn_delete(defn);
00243 }
00244         \endcode
00245         \par Creating a message
00246         Messages are created from definitions.  The line above that is used to create the message:
00247         \code
00248 lbmpdm_msg_create(&msg1, defn, 0);
00249         \endcode
00250         \par Setting field values in a message
00251         Scalar (non-array) fields are added to a message via the
00252         <tt>lbmpdm_msg_set_field_value()</tt> to set a field's value using its handle.
00253         \par
00254         When setting a field's value, data of the appropriate type must be supplied.
00255         A 0 length can be supplied for fixed length fields but it is recommended to pass
00256         the correct size in bytes to ensure the correct number of bytes are copied into
00257         the message.  As an example, to set a 32-bit signed integer field to a message:
00258         \code
00259 rc = lbmpdm_msg_set_field_value(msg1, h1, &quant, 0);
00260         \endcode
00261         \par
00262         Setting a string value is done by passing the char * and the actual size
00263         of the string in bytes (normally this is the num_chars + 1 to account for the null character
00264         but for UNICODE types this value will be larger).  For the MESSAGE type, the value argument
00265         should be a lbmpdm_msg_t * and the length argument should be sizeof(lbmpdm_msg_t *) because
00266         the setter will attempt to access the lbmpdm_msg_t via the pointer and then serialize it
00267         to bytes via its serialize method.
00268         \par Setting the value of array fields in a message
00269         To set an array's value in a message, call the
00270         <tt>lbmpdm_msg_set_field_value_vec()</tt> API function.
00271         \par
00272         As an example, the code that sets the string array field value is:
00273         \code
00274 rc = lbmpdm_msg_set_field_value_vec(msg1, h2, str_arr, str_len_arr, str_arr_num_elem);
00275         \endcode
00276         \par
00277         Setting an array field value requires an addition number of elements parameter and expects
00278         an array of lengths (one for each element in the array).  Again, string types should pass a length
00279         array that indicates the size in bytes of each string rather than the number of characters as
00280         shown in the example code which uses sizes a length array of {3, 5, 8}.
00281         \par Serializing the message
00282         Once a PDM message is constructed, it must be serialized for transmission.
00283         The API function lbmpdm_msg_serialize() serializes the message to
00284         the buffer provided.  The length of the serialized data may be obtained via the API function
00285         lbmpdm_msg_get_length().
00286         For example, a constructed message may be sent by:
00287         \code
00288 rc = lbmpdm_msg_serialize(msg1, msg_buffer);
00289 rc = lbm_src_send(src, msg_buffer, msg_len, 0);
00290         \endcode
00291         \par Deserializing a message
00292         When the bytes for a pdm message are received, they must be deserialized so that individual fields can be
00293         accessed. The lbmpdm_msg_t should be reused when possible to deserialize multiple incoming messages.
00294         This is done via the lbmpdm_msg_deserialize() API function:
00295         \code
00296 rc = lbmpdm_msg_deserialize(msg2, msg_buffer, msg_len);
00297 // Deserializing an lbm message would be the following
00298 //rc = lbmpdm_msg_deserialize(msg2, lbmmsg->data, lbmmsg->len);
00299         \endcode
00300         \par Fetching fields from a message
00301         When fetching a field from a message, the field should be accessed by its handle.
00302         \par
00303         Scalar (non-array) fields may be retrieved via the <tt>lbmpdm_msg_get_field_value()</tt>.
00304         \code
00305 rc = lbmpdm_msg_get_field_value(msg2, h1, &rcv_quant, &rcv_quant_sz);
00306         \endcode
00307         \par
00308         Array fields may be retrieved via the <tt>lbmpdm_msg_get_field_value_vec()</tt>.
00309         \code
00310 rc = lbmpdm_msg_get_field_value_vec(msg2, h2, rcv_str_arr, str_len_arr, &str_arr_num_elem);
00311         \endcode
00312         \par
00313         When accessing a field, it is expected that value pointer being provided already points
00314         to an area of sufficient size to hold the field's value.  The len argument should indicate
00315         the size or sizes (for array types) of the available space.  If the size is not sufficient,
00316         a PDM_FAILURE will be returned and the failing len argument will be updated to indicate the
00317         actual size     needed.  For array types, the same logic applies to the number of elements argument,
00318         where if the number of allocated elements indicated by the input parameter is insufficient, the
00319         call will fail and the value will be updated to indicate the needed number of elements.
00320         For the MESSAGE type, the value argument should be a lbmpdm_msg_t * that points to an empty
00321         lbmpdm_msg_t which has been created with a NULL definition.  The length argument should be sizeof(lbmpdm_msg_t *) because
00322         the setter will attempt to access the lbmpdm_msg_t via the pointer and then deserialize the bytes
00323         into it.
00324         \par Disposing of a message and definition
00325         Once a PDM message (created by either the lbmpdm_msg_create() or
00326         lbmpdm_msg_deserialize() API calls) is no longer needed,
00327         it must be deleted to avoid a resource leak.
00328         This is done via the lbmpdm_msg_delete() API call.
00329         \code
00330 lbmpdm_msg_delete(msg1);
00331 lbmpdm_msg_delete(msg2);
00332 lbmpdm_defn_delete(defn);
00333         \endcode
00334         \par Error information
00335         All functions return a value to indicate the success of failure of the operation.
00336         Most return PDM_SUCCESS to indicate success, or PDM_FAILURE otherwise.
00337         Consult the individual function documentation for exceptions.
00338         \par
00339         The function lbmpdm_errmsg() will return a descriptive error message.
00340         \par Additional Information
00341         When adding arrays to a definition, an array length can be specified in the info attributes.
00342         A 0 length means that the array's length is variable and will be determined when the
00343         array is set in the actual message.  A positive number for the array length
00344         will create a fixed array of that size.
00345         \par
00346         When adding PDM_TYPE_FIX_STRING, PDM_TYPE_FIX_STRING_ARR, PDM_TYPE_FIX_UNICODE, or PDM_TYPE_FIX_UNICODE_ARR,
00347         field information to a definition, a fixed string length must be specified in the info attributes.
00348         The value should be the number of characters in the string (excluding the null character).  The
00349         appropriate amount of space will be then allocated in the message for each of the expected fixed strings
00350         (for the FIX_STRING types, there will be num_chars + 1 bytes allocated per string and for the FIX_UNICODE types,
00351         there will be 4 * num_chars + 1 bytes allocated per string).  By using fixed strings for a field, as
00352         well as making the field required (and specifying a fixed size for the array types), the best performance
00353         and size can be achieved because the field will be optimized as a "fixed required" field.
00354         \par
00355         When setting and getting field values of type FIX_STRING and FIX_UNICODE (and the corresponding arrays),
00356         extra care should be made to ensure the len parameters are correct.  When setting the value, the len should
00357         indicate the actual number of bytes represented by the string that should be copied
00358         (which should include the null character).  If this is less than the size indicated to the definition when
00359         setting up the field information, the rest of the space will be zeroed out.  When getting the value, enough
00360         space should be allocated for the entire size of the fixed string field, which as described above should be
00361         the number of characters + 1 for the string types and 4 * the number of characters + 1 for the unicode types.
00362         \par
00363         An additional way to get a field value from a message is by using the lbmpdm_msg_get_field_value_stct method,
00364         which does not require the storage and lengths to be allocated beforehand but instead will allocate everything
00365         during the call and set all of the appropriate values of the provided lbmpdm_field_value_t.  Although simpler to use,
00366         the drawback is not being able to use preallocated space to hold the field value as the other get_field_value methods
00367         are able to do.  It also requires the application to manage the field_value_t and call the field_value_stct_delete
00368         method when finished to clean up the allocated memory inside the field_value_t.
00369 */
00370 
00371 /*!     \brief PDM API function return codes.
00372 */
00373 #ifndef _LBMPDM_H_
00374 #define _LBMPDM_H_
00375 
00376 #if defined(__cplusplus)
00377 extern "C" {
00378 #endif
00379 
00380 #if HAVE_STDINT_H
00381         #include <stdint.h>
00382 #endif
00383 #include <stdlib.h>
00384 
00385 /* Directives to show how we treat exporting functions with Windows from the DLL */
00386 #if defined(_WIN32)
00387         #if defined(_DLL) && defined(LBM_EXPORT_SYMS)
00388                 #define LBMPDMExpDLL __declspec(dllexport)
00389         #elif defined(LBM_STATIC_LIB)
00390                 #define LBMPDMExpDLL
00391         #else
00392                 #define LBMPDMExpDLL __declspec(dllimport)
00393         #endif
00394 #elif defined(__TANDEM)
00395         #if defined(LBM_EXPORT_SYMS)
00396                 #define LBMPDMExpDLL export$
00397         #else
00398                 #define LBMPDMExpDLL import$
00399         #endif
00400 #else
00401         #define LBMPDMExpDLL
00402 #endif
00403 
00404 #if defined(_WIN32)
00405 #if !defined(DONT_TYPEDEF_INT_T)
00406         typedef __int8 int8_t;
00407         typedef __int16 int16_t;
00408         typedef __int32 int32_t;
00409         typedef __int64 int64_t;
00410 
00411         typedef unsigned __int8 uint8_t;
00412         typedef unsigned __int16 uint16_t;
00413         typedef unsigned __int32 uint32_t;
00414         typedef unsigned __int64 uint64_t;
00415 #endif
00416         /* C99 printf format macros missing from VC. */
00417         #define PRId8 "d"
00418         #define PRId16 "d"
00419         #define PRId32 "d"
00420         #define PRId64 "I64d"
00421         #define PRIu8 "u"
00422         #define PRIu16 "u"
00423         #define PRIu32 "u"
00424         #define PRIu64 "I64u"
00425         #define PRIx8 "x"
00426         #define PRIx16 "x"
00427         #define PRIx32 "x"
00428         #define PRIx64 "I64x"
00429         #define PRIuSZ "Iu"
00430         /* C99 scanf format macros missing from VC. */
00431         #define SCNd8 "d"
00432         #define SCNd16 "hd"
00433         #define SCNd32 "ld"
00434         #define SCNd64 "I64d"
00435         #define SCNu8 "u"
00436         #define SCNu16 "hu"
00437         #define SCNu32 "lu"
00438         #define SCNu64 "I64u"
00439         #define SCNx64 "I64x"
00440         #define SCNuSZ "Iu"
00441 #elif defined(__VMS)
00442         #include <inttypes.h>
00443         /* C99 printf format macros missing from OpenVMS. */
00444         #define PRId8 "d"
00445         #define PRId16 "d"
00446         #define PRId32 "d"
00447         #define PRId64 "lld"
00448         #define PRIu8 "u"
00449         #define PRIu16 "u"
00450         #define PRIu32 "u"
00451         #define PRIu64 "llu"
00452         #define PRIuSZ "zu"
00453         /* C99 scanf format macros missing from OpenVMS. */
00454         #define SCNd8 "hhd"
00455         #define SCNd16 "hd"
00456         #define SCNd32 "d"
00457         #define SCNd64 "lld"
00458         #define SCNu8 "hhu"
00459         #define SCNu16 "hu"
00460         #define SCNu32 "u"
00461         #define SCNu64 "llu"
00462         #define SCNuSZ "zu"
00463 #else
00464         #include <inttypes.h>
00465         #ifndef PRIuSZ
00466                 #define PRIuSZ "zu"
00467         #endif
00468         #ifndef SCNuSZ
00469                 #define SCNuSZ "zu"
00470         #endif
00471 #endif
00472 
00473 /*! \brief Type representing a handle to a message field.  
00474         Field handles are returned when adding a field to
00475         a definition, or can be retrieved from a definition
00476         using the \c lbmpdm_get_field_handle_by_str_name or
00477         \c lbpdm_get_field_handle_by_int_name functions.
00478  */
00479 typedef int32_t lbmpdm_field_handle_t;
00480 
00481 /*!     \brief Structure to hold a scaled decimal number.
00482         A scaled decimal number consists of a mantissa \f$m\f$ and an exponent \f$exp\f$.
00483         It represents the value \f$m\cdot 10^{exp}\f$.
00484 
00485         The mantissa is represented as a 64-bit signed integer.
00486         The exponent is represented as an 8-bit signed integer,
00487         and can range from -128 to 127.
00488 */
00489 typedef struct {
00490         /*! Mantissa. */
00491         int64_t mant;
00492         /*! Exponent. */
00493         int8_t exp;
00494 } lbmpdm_decimal_t;
00495 
00496 /*!     \brief Structure to hold a timestamp value.
00497 
00498         The tv_secs is the number of seconds since the epoch.
00499         The tv_usecs is the additional microseconds since the epoch.
00500         and can range from -128 to 127.
00501 */
00502 typedef struct {
00503         /*! Seconds since epoch */
00504         int32_t tv_secs;
00505         /*! Microseconds since last second */
00506         int32_t tv_usecs; 
00507 } lbmpdm_timestamp_t;
00508 
00509 struct lbmpdm_msg_strct_t;
00510 /*!     \brief Structure to hold a pdm message.
00511 */
00512 typedef struct lbmpdm_msg_stct_t lbmpdm_msg_t;
00513 
00514 struct lbmpdm_defn_stct_t;
00515 /*!     \brief Structure to hold a pdm definition.
00516 */
00517 typedef struct lbmpdm_defn_stct_t lbmpdm_defn_t;
00518 
00519 /*! \brief Attribute struct to be passed along with the name
00520         when adding field info to a definition
00521  */
00522 struct lbmpdm_field_info_attr_stct_t {
00523         int flags;
00524         /*! If the field is required or not. */
00525         uint8_t req;
00526         /*! The number of characters for fixed string or fixed unicode types. */
00527         uint32_t fixed_str_len;
00528         /*! The number of elements for fixed arrays. */
00529         uint32_t num_arr_elem;
00530         /* Fill for external pdm struct for future binary compatibility. */
00531         char fill[256];
00532 };
00533 typedef struct lbmpdm_field_info_attr_stct_t lbmpdm_field_info_attr_t;
00534 
00535 /*! \brief Field value struct that can be populated with a field value when passed
00536         to the lbmpdm_msg_get_field_value_stct function.
00537  */
00538 struct lbmpdm_field_value_stct_t {
00539         /*! The field type. */
00540         uint16_t field_type;
00541         /*! If the field is an array */
00542         uint8_t is_array;
00543         /*! If the field is a fixed length field. */
00544         uint8_t is_fixed;
00545         /*! The length in bytes of the field for scalar fields. */
00546         size_t len;
00547         /*! A pointer to the field value for scalar fields. */
00548         char *value;
00549         /*! The number of elements in the array for array fields. */
00550         uint32_t num_arr_elem;
00551         /*! An array of size_t representing the length in bytes for each array element for array fields. */
00552         size_t *len_arr;
00553         /*! An array of pointers to the field values for array fields. */
00554         char **value_arr;
00555         /* Fill for external pdm struct for future binary compatibility. */
00556         char fill[256];
00557 };
00558 typedef struct lbmpdm_field_value_stct_t lbmpdm_field_value_t;
00559 
00560 struct lbmpdm_iter_stct_t;
00561 /*! \brief Iterator structure that is used to traverse the fields of a message.
00562  */
00563 typedef struct lbmpdm_iter_stct_t lbmpdm_iter_t;
00564 
00565 /*! PDM true/false values. PDM value for FALSE. */
00566 #define PDM_FALSE (uint8_t) 0
00567 
00568 /*! PDM true/false values. PDM value for TRUE. */
00569 #define PDM_TRUE (uint8_t) 1
00570 
00571 /*! PDM Field Info Flags. Field is required. */
00572 #define PDM_FIELD_INFO_FLAG_REQ 0x1
00573 
00574 /*! PDM Field Info Flags. Field has a fixed string length (for string and unicode types). */
00575 #define PDM_FIELD_INFO_FLAG_FIXED_STR_LEN 0x2
00576 
00577 /*! PDM Field Info Flags. Field has a fixed array size (for array types). */
00578 #define PDM_FIELD_INFO_FLAG_NUM_ARR_ELEM 0x4
00579 
00580 /*! PDM Message Flags. If any variable or optional fields have been set (set internally). */
00581 #define PDM_MSG_FLAG_VAR_OR_OPT_FLDS_SET 0x1
00582 
00583 /*! PDM Message Flags. If the definition should be serialized with the message. */
00584 #define PDM_MSG_FLAG_INCL_DEFN 0x2
00585 
00586 /*! PDM Message Flags. If a message should override its existing definition with one included when deserializing a message. */
00587 #define PDM_MSG_FLAG_USE_MSG_DEFN_IF_NEEDED 0x4
00588 
00589 /*! PDM Message Flags. If a message should try to load a needed definition from the cache when deserializing. */
00590 #define PDM_MSG_FLAG_TRY_LOAD_DEFN_FROM_CACHE 0x8
00591 
00592 /*! PDM Message Flags. If the field values need bytes to be swapped (set internally). */
00593 #define PDM_MSG_FLAG_NEED_BYTE_SWAP 0x10
00594 
00595 /*! PDM Message Flags. If a message's existing definition should be deleted when replaced when deserializing a message. */
00596 #define PDM_MSG_FLAG_DEL_DEFN_WHEN_REPLACED 0x20
00597 
00598 /*! PDM Message Version Policy. Use Exact Match versioning Policy. */
00599 #define PDM_MSG_VER_POLICY_EXACT 0
00600 
00601 /*! PDM Message Version Policy. Use Best Match versioning Policy. */
00602 #define PDM_MSG_VER_POLICY_BEST 1
00603 
00604 /*! PDM Return Code. Operation was successful. */
00605 #define PDM_SUCCESS 0
00606 
00607 /*! PDM Return Code. Operation failed. See lbmpdm_errnum() or lbmpdm_errmsg() for the reason. */
00608 #define PDM_FAILURE -1
00609 
00610 /*! PDM Error Code. Field is null. */
00611 #define PDM_ERR_FIELD_IS_NULL 1
00612 
00613 /*! PDM Error Code. No more fields to iterate over. */
00614 #define PDM_ERR_NO_MORE_FIELDS 2
00615 
00616 /*! PDM Error Code. Insufficient buffer length given. */
00617 #define PDM_ERR_INSUFFICIENT_BUFFER_LENGTH 3
00618 
00619 /*! PDM Error Code. Invalid parameter given. */
00620 #define PDM_ERR_EINVAL 4
00621 
00622 /*! PDM Error Code. Field not found. */
00623 #define PDM_ERR_FIELD_NOT_FOUND 5
00624 
00625 /*! PDM Error Code. Not a valid PDM message. */
00626 #define PDM_ERR_MSG_INVALID 6
00627 
00628 /*! PDM Error Code. Not a valid PDM definition. */
00629 #define PDM_ERR_DEFN_INVALID 7
00630 
00631 /*! PDM Error Code. No memory available. */
00632 #define PDM_ERR_NOMEM 8
00633 
00634 /*! PDM Error Code. Required field not set. */
00635 #define PDM_ERR_REQ_FIELD_NOT_SET 9
00636 
00637 /*! PDM Error Code. Error creating field section. */
00638 #define PDM_ERR_CREATE_SECTION 10
00639 
00640 /*! PDM Error Code. Error creating buffer. */
00641 #define PDM_ERR_CREATE_BUFFER 11
00642 
00643 /*! PDM Field Type. Invalid Type. */
00644 #define PDM_INTERNAL_TYPE_INVALID -1
00645 
00646 /*! PDM Field Type. boolean. */
00647 #define PDM_TYPE_BOOLEAN 0
00648 
00649 /*! PDM Field Type. 8 bit integer. */
00650 #define PDM_TYPE_INT8 1
00651 
00652 /*! PDM Field Type. unsigned 8 bit integer. */
00653 #define PDM_TYPE_UINT8 2
00654 
00655 /*! PDM Field Type. 16 bit integer. */
00656 #define PDM_TYPE_INT16 3
00657 
00658 /*! PDM Field Type. unsigned 16 bit integer. */
00659 #define PDM_TYPE_UINT16 4
00660 
00661 /*! PDM Field Type. 32 bit integer. */
00662 #define PDM_TYPE_INT32 5
00663 
00664 /*! PDM Field Type. unsigned 32 bit integer. */
00665 #define PDM_TYPE_UINT32 6
00666 
00667 /*! PDM Field Type. 64 bit integer. */
00668 #define PDM_TYPE_INT64 7
00669 
00670 /*! PDM Field Type. unsigned 64 bit integer. */
00671 #define PDM_TYPE_UINT64 8
00672 
00673 /*! PDM Field Type. float. */
00674 #define PDM_TYPE_FLOAT 9
00675 
00676 /*! PDM Field Type. double. */
00677 #define PDM_TYPE_DOUBLE 10
00678 
00679 /*! PDM Field Type. decimal. */
00680 #define PDM_TYPE_DECIMAL 11
00681 
00682 /*! PDM Field Type. timestamp. */
00683 #define PDM_TYPE_TIMESTAMP 12
00684 
00685 /*! PDM Field Type. fixed string. */
00686 #define PDM_TYPE_FIX_STRING 13
00687 
00688 /*! PDM Field Type. string (variable length). */
00689 #define PDM_TYPE_STRING 14
00690 
00691 /*! PDM Field Type. fixed unicode. */
00692 #define PDM_TYPE_FIX_UNICODE 15
00693 
00694 /*! PDM Field Type. unicode (variable length). */
00695 #define PDM_TYPE_UNICODE 16
00696 
00697 /*! PDM Field Type. blob (variable length). */
00698 #define PDM_TYPE_BLOB 17
00699 
00700 /*! PDM Field Type. PDM message (variable length). */
00701 #define PDM_TYPE_MESSAGE 18
00702 
00703 /*! PDM Field Type. boolean array. */
00704 #define PDM_TYPE_BOOLEAN_ARR 19
00705 
00706 /*! PDM Field Type. 8 bit integer array. */
00707 #define PDM_TYPE_INT8_ARR 20
00708 
00709 /*! PDM Field Type. unsigned 8 bit integer array. */
00710 #define PDM_TYPE_UINT8_ARR 21
00711 
00712 /*! PDM Field Type. 16 bit integer array. */
00713 #define PDM_TYPE_INT16_ARR 22
00714 
00715 /*! PDM Field Type. unsigned 16 bit integer array. */
00716 #define PDM_TYPE_UINT16_ARR 23
00717 
00718 /*! PDM Field Type. 32 bit integer array. */
00719 #define PDM_TYPE_INT32_ARR 24
00720 
00721 /*! PDM Field Type. unsigned 32 bit integer array. */
00722 #define PDM_TYPE_UINT32_ARR 25
00723 
00724 /*! PDM Field Type. 64 bit integer array. */
00725 #define PDM_TYPE_INT64_ARR 26
00726 
00727 /*! PDM Field Type. unsigned 64 bit integer array. */
00728 #define PDM_TYPE_UINT64_ARR 27
00729 
00730 /*! PDM Field Type. float array. */
00731 #define PDM_TYPE_FLOAT_ARR 28
00732 
00733 /*! PDM Field Type. double array. */
00734 #define PDM_TYPE_DOUBLE_ARR 29
00735 
00736 /*! PDM Field Type. decimal array. */
00737 #define PDM_TYPE_DECIMAL_ARR 30
00738 
00739 /*! PDM Field Type. timestamp array. */
00740 #define PDM_TYPE_TIMESTAMP_ARR 31
00741 
00742 /*! PDM Field Type. fixed string array. */
00743 #define PDM_TYPE_FIX_STRING_ARR 32
00744 
00745 /*! PDM Field Type. string array. */
00746 #define PDM_TYPE_STRING_ARR 33
00747 
00748 /*! PDM Field Type. fixed unicode array. */
00749 #define PDM_TYPE_FIX_UNICODE_ARR 34
00750 
00751 /*! PDM Field Type. unicode array. */
00752 #define PDM_TYPE_UNICODE_ARR 35
00753 
00754 /*! PDM Field Type. blob array. */
00755 #define PDM_TYPE_BLOB_ARR 36
00756 
00757 /*! PDM Field Type. PDM message array. */
00758 #define PDM_TYPE_MESSAGE_ARR 37
00759 
00760 /*! PDM Field Name Type. Use string field names. */
00761 #define PDM_DEFN_STR_FIELD_NAMES 0
00762 
00763 /*! PDM Field Name Type. Use integer field names. */
00764 #define PDM_DEFN_INT_FIELD_NAMES 1
00765 
00766 /*! PDM Iterator Invalid Handle. Indicates invalid field handle. */
00767 #define PDM_ITER_INVALID_FIELD_HANDLE -1
00768 
00769 /*! \brief Return the error number last encountered by this thread.
00770         \return An integer error number.
00771  */
00772 LBMPDMExpDLL int lbmpdm_errnum();
00773 
00774 /*! \brief Return an ASCII string containing the error message last encountered
00775         by this thread.
00776         \return Pointer to a static char array holding the error message.
00777  */
00778 LBMPDMExpDLL const char *lbmpdm_errmsg();
00779 
00780 /*! \brief initialize the cache for a given number of buckets. If 0 is
00781         given the the cache will default. The default can be altered via
00782         a PDM attribute.
00783         \param cache_size -- how many buckets should this hash contain?  If
00784          set to zero this will default.
00785  */
00786 LBMPDMExpDLL int lbmpdm_cache_init(uint32_t cache_size);
00787 
00788 /*! \brief add a definition structure to the cache. It is assumed that the
00789         structure has a unique id, if the id is set to zero the structure
00790         will not be inserted into the map.
00791         \param defn -- the new definition structure being added.
00792  */
00793 LBMPDMExpDLL int lbmpdm_cache_struct_add(lbmpdm_defn_t *defn);
00794 
00795 /*! \brief delete a definition structure from the cache. Does not error if the
00796         structure doesn't exist.
00797         \param id -- id of the structure being deleted.  If the id
00798         is not found this will do nothing.
00799  */
00800 LBMPDMExpDLL int lbmpdm_cache_struct_remove(int32_t id);
00801 
00802 /*! \brief delete a definition structure from the cache by its id and version.
00803         Does not error if the structure doesn't exist.
00804         \param id -- id of the structure being deleted.  If the id
00805         is not found this will do nothing.
00806         \param vers_major -- major version of the definition
00807         \param vers_minor -- minor version of the definition
00808  */
00809 LBMPDMExpDLL int lbmpdm_cache_struct_remove_by_version(int32_t id, uint8_t vers_major, uint8_t vers_minor);
00810 
00811 /*! \brief find a given definition structure by id and return the structure for
00812         it. Returns PDM_FAILURE for nothing found, and PDM_SUCCESS for something found.  Note,
00813         since a structure with the id of 0 won't exist in the cache you will
00814         never find one being returned from this find with an id of 0.
00815         \param defn -- pointer to the structure to return.  This
00816         field is not altered if nothing is found for a given id.
00817         \param id -- id to search for in the hash.
00818  */
00819 LBMPDMExpDLL int lbmpdm_cache_struct_find(lbmpdm_defn_t **defn, int32_t id);
00820 
00821 /*! \brief find a given definition structure by id, major version, and minor version
00822         and return the structure for it. Returns PDM_FAILURE for nothing found, and PDM_SUCCESS for something found.  Note,
00823         since a structure with the id of 0 won't exist in the cache you will
00824         never find one being returned from this find with an id of 0.
00825         \param defn -- pointer to the structure to return.  This
00826         field is not altered if nothing is found for a given id.
00827         \param id -- id to search for in the hash.
00828         \param vers_major -- major version to search for in the hash.
00829         \param vers_minor -- minor version to search for in the hash.
00830  */
00831 LBMPDMExpDLL int lbmpdm_cache_struct_find_by_version(lbmpdm_defn_t **defn, int32_t id, uint8_t vers_major, uint8_t vers_minor);
00832 
00833 /*! \brief nuke the whole cache, this deletes all the structures within
00834         the cache as well.
00835  */
00836 LBMPDMExpDLL int lbmpdm_cache_clear_all();
00837 
00838 
00839 /*! \brief Retrieve a field handle from a definition via name.
00840  *      \param defn -- definition created from lbmpdm_defn_create.
00841  *      \param str_name -- the name of the field to be retrieved.
00842  *      \return A valid field handle on success, PDM_FAILURE otherwise.
00843  */
00844 LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_str_name(lbmpdm_defn_t *defn, const char *str_name);
00845 
00846 /*! \brief Retrieve a field handle from a definition via name.
00847  *      \param defn -- definition created from lbmpdm_defn_create.
00848  *      \param int_name -- the name of the field to be retrieved.
00849  *      \return A valid field handle on success, PDM_FAILURE otherwise.
00850  */
00851 LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_defn_get_field_handle_by_int_name(lbmpdm_defn_t *defn, int32_t int_name);
00852 
00853 /*! \brief Create a definition, with the passed number of fields.  The
00854         num_fields is required to be at least 1.  The number of fields can
00855         grow beyond this value, it is used initially to size the internal
00856         field info array.
00857         \param defn -- pointer to newly created definition.
00858         \param num_fields -- how many fields to initially assume we will
00859         have, this is for optimization, not a limit to how many fields.
00860         \param id -- This is the id for the definition.  It is assumed
00861         that this is a unique id.
00862         \param vrs_mjr -- A version major number to be assigned to the newly
00863         created definition.  When deserializing a message, PDM will attempt
00864         to use the existing set definition if the ids match.  If the message flag
00865         is set to use the included message definition or try to load the definition from the cache,
00866         then an attempt will be made to replace the set definition with the new one by its version numbers.
00867         Please note: when versioning message definitions, adding
00868         optional fields only is the safest way to unsure interoperability
00869         with older versions. Adding new required fields or modifying the
00870         types of existing required fields may lead to messages that are not
00871         deserializable by receivers with older definition versions.
00872         \param vrs_mnr -- A version minor number
00873         \param field_names_type -- A type that indicates whether the field names will be strings or ints.  Use
00874         either PDM_DEFN_STR_FIELD_NAMES or PDM_DEFN_INT_FIELD_NAMES for the value.
00875         \return PDM_SUCCESS or PDM_FAILURE.
00876  */
00877 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);
00878 
00879 /*! \brief delete a given definition. 
00880         \param defn -- definition to be deleted.
00881         \return PDM_SUCCESS or PDM_FAILURE.
00882  */
00883 LBMPDMExpDLL int lbmpdm_defn_delete(lbmpdm_defn_t *defn);
00884 
00885 /*! \brief make this definition final.  This needs to be done before using
00886         it in a message.
00887         \param defn -- the definition to be finalized.
00888         \return PDM_SUCCESS or PDM_FAILURE
00889  */
00890 LBMPDMExpDLL int lbmpdm_defn_finalize(lbmpdm_defn_t *defn);
00891 
00892 /*! \brief adds field info to the definition by string name
00893         \param str_name -- the string name
00894         \param type -- the PDM field type
00895         \param info_attr -- the field information attributes
00896         \return PDM_SUCCESS or PDM_FAILURE
00897  */
00898 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);
00899 
00900 /*! \brief adds field info to the definition by integer name
00901         \param int_name -- the integer name
00902         \param type -- the PDM field type
00903         \param info_attr -- the field information attributes
00904         \return PDM_SUCCESS or PDM_FAILURE
00905  */
00906 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);
00907 
00908 /*! \brief Gets the exact length of the serialized defn.
00909         This can be used to allocate a buffer of the exact length needed
00910         to serialize the defn.
00911         \param defn -- A pointer to a PDM defn object.
00912         \return the exact length of the serialized defn
00913  */
00914 LBMPDMExpDLL uint32_t lbmpdm_defn_get_length(lbmpdm_defn_t *defn);
00915 
00916 /*! \brief Gets the id of the definition.
00917         \param defn -- A pointer to a PDM defn object.
00918         \return the id of the definition
00919  */
00920 LBMPDMExpDLL int32_t lbmpdm_defn_get_id(lbmpdm_defn_t *defn);
00921 
00922 /*! \brief Gets the number of fields in the definition
00923         \param defn -- A pointer to a PDM defn object.
00924         \return the number of fields in the definition
00925  */
00926 LBMPDMExpDLL int32_t lbmpdm_defn_get_num_fields(lbmpdm_defn_t *defn);
00927 
00928 /*! \brief Gets the message major version number from the definition
00929         \param defn -- A pointer to a PDM defn object.
00930         \return the major version number
00931  */
00932 LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_major(lbmpdm_defn_t *defn);
00933 
00934 /*! \brief Gets the message minor version number from the definition
00935         \param defn -- A pointer to a PDM defn object.
00936         \return the minor version number
00937  */
00938 LBMPDMExpDLL int8_t lbmpdm_defn_get_msg_vers_minor(lbmpdm_defn_t *defn);
00939 
00940 /*! \brief Gets the field names type (either PDM_DEFN_STR_FIELD_NAMES or PDM_DEFN_INT_FIELD_NAMES)
00941         from the definition.
00942         \param defn -- A pointer to a PDM defn object.
00943         \return the field names type
00944  */
00945 LBMPDMExpDLL uint8_t lbmpdm_defn_get_field_names_type(lbmpdm_defn_t *defn);
00946 
00947 /*! \brief Gets whether or not the definition has been finalized (either PDM_TRUE or PDM_FALSE).
00948         \param defn -- A pointer to a PDM defn object.
00949         \return the value indicating whether or not the definition has been finalized
00950  */
00951 LBMPDMExpDLL uint8_t lbmpdm_defn_is_finalized(lbmpdm_defn_t *defn);
00952 
00953 /*! \brief Gets the string field name from a given definition's field handle.
00954         \param defn -- A pointer to a PDM defn object.
00955         \param handle -- A valid field handle from the definition.
00956         \return the string field name or NULL.
00957  */
00958 LBMPDMExpDLL const char *lbmpdm_defn_get_field_info_str_name(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);
00959 
00960 /*! \brief Gets the integer field name from a given definition's field handle.
00961         \param defn -- A pointer to a PDM defn object.
00962         \param handle -- A valid field handle from the definition.
00963         \return the int field name or -1.
00964  */
00965 LBMPDMExpDLL int32_t lbmpdm_defn_get_field_info_int_name(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);
00966 
00967 /*! \brief Gets the PDM field type from a given definition's field handle.
00968         \param defn -- A pointer to a PDM defn object.
00969         \param handle -- A valid field handle from the definition.
00970         \return the PDM type or PDM_INTERNAL_TYPE_INVALID.
00971  */
00972 LBMPDMExpDLL int16_t lbmpdm_defn_get_field_info_type(lbmpdm_defn_t *defn, lbmpdm_field_handle_t handle);
00973 
00974 /*! \brief Serialize a defn to a buffer.  In normal usage this is not needed as the defn
00975         is either known in advance or sent as part of a message.
00976         The defn that is passed in is serialized into the caller's supplied buffer.
00977         \param defn A PDM defn to be serialized
00978         \param buffer The caller allocated buffer
00979         \param defn_len Will be set to the length of the definition
00980         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
00981  */
00982 LBMPDMExpDLL int lbmpdm_defn_serialize(lbmpdm_defn_t *defn, char *buffer, uint32_t *defn_len);
00983 
00984 /*! \brief Deserialize the associated buffer into a newly created defn
00985 
00986         This will take the passed buffer and deserialize the contents into a newly
00987         created defn.  When finished with the defn, the caller must call
00988         lbmpdm_defn_delete() to properly dispose of the defn.  This is done automatically by
00989         a message when the defn is included.  The message normally indicates to the
00990         definition whether or not swap bytes need to be set to PDM_TRUE so to use this method directly,
00991         this knowledge must be determined outside PDM.
00992 
00993         \sa lbmpdm_msg_delete()
00994         \param defn A pointer to a previously created PDM defn object
00995         \param bufptr The buffer to be deserialized
00996         \param buflen The length of the buffer.
00997         \param swap_bytes Whether or not bytes should be swapped to deal with endianness.
00998         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
00999  */
01000 LBMPDMExpDLL int lbmpdm_defn_deserialize(lbmpdm_defn_t *defn, const char *bufptr, uint32_t buflen, uint8_t swap_bytes);
01001 
01002 /*! \brief creates a message with the specified definition
01003         \param message -- pointer to the newly created message
01004         \param defn -- the definition to be used by the message
01005         \param flags -- flags to set in the message
01006         \return PDM_SUCCESS or PDM_FAILURE
01007  */
01008 LBMPDMExpDLL int lbmpdm_msg_create(lbmpdm_msg_t **message, lbmpdm_defn_t *defn, uint32_t flags);
01009 
01010 /*! \brief Delete an lbmpdm_msg_t object and all associated resources (except the defn)
01011         This deletes a previously created PDM message and all resources
01012         associated with the message.
01013         \sa lbmpdm_msg_create()
01014         \param message --  A pointer to a PDM message object.
01015         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01016  */
01017 LBMPDMExpDLL int lbmpdm_msg_delete(lbmpdm_msg_t *message);
01018 
01019 /*! \brief Delete an lbmpdm_msg_t object and all associated resources (including the defn)
01020         This deletes a previously created PDM message and all resources
01021         associated with the message.
01022         \sa lbmpdm_msg_create()
01023         \param message --  A pointer to a PDM message object.
01024         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01025  */
01026 LBMPDMExpDLL int lbmpdm_msg_and_defn_delete(lbmpdm_msg_t *message);
01027 
01028 /*! \brief Gets the exact length of the serialized message.
01029         This can be used to allocate a buffer of the exact length needed
01030         to serialize the message.
01031         \param message -- A pointer to a PDM message object.
01032         \return the exact length of the serialized message
01033  */
01034 LBMPDMExpDLL uint32_t lbmpdm_msg_get_length(const lbmpdm_msg_t *message);
01035 
01036 /*! \brief Gets a pointer to the message definition.
01037         \param message -- A pointer to a PDM message object.
01038         \return the message definition
01039  */
01040 LBMPDMExpDLL lbmpdm_defn_t *lbmpdm_msg_get_defn(const lbmpdm_msg_t *message);
01041 
01042 /*! \brief Gets whether or not the field value has been set.
01043         \param message -- A pointer to a PDM message object.
01044         \param handle -- A valid field handle
01045         \return PDM_TRUE or PDM_FALSE
01046  */
01047 LBMPDMExpDLL uint8_t lbmpdm_msg_is_field_set(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle);
01048 
01049 /*! \brief Populates a field value struct with the value from the message.
01050         \param message -- A pointer to a PDM message object.
01051         \param handle -- A valid field handle
01052         \param field_value -- A pointer to a field value structure
01053         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01054  */
01055 LBMPDMExpDLL int lbmpdm_msg_get_field_value_stct(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, lbmpdm_field_value_t *field_value);
01056 
01057 /*! \brief Gets a field value from the message
01058         \param message -- A pointer to a PDM message object.
01059         \param handle -- A valid field handle
01060         \param value -- A pointer to a value big enough to hold the field value
01061         \param len -- A pointer describing the currently allocated length of the void *value.  If it is not large
01062         enough to hold the field value, PDM_FAILURE will be returned and len will be set to the needed length.
01063         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01064  */
01065 LBMPDMExpDLL int lbmpdm_msg_get_field_value(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t *len);
01066 
01067 /*! \brief Gets an array of field values from the message
01068         \param message -- A pointer to a PDM message object.
01069         \param handle -- A valid field handle
01070         \param value -- An array of pointers with each one already allocated of sufficient length to hold each field value element
01071         \param len -- An array describing the currently allocated lengths of each element of the void *value.  If any len element is not large
01072         enough to hold the field value, PDM_FAILURE will be returned and the len array will be set to the needed lengths.
01073         \param num_arr_elem -- A pointer to the number of allocated elements in the value and len arrays.  If the number is
01074         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.
01075         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01076  */
01077 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);
01078 
01079 /*! \brief Sets a field value in a message
01080         \param message -- A pointer to a PDM message object.
01081         \param handle -- A valid field handle
01082         \param value -- A pointer to a value that should be set into the message
01083         \param len -- A size_t describing the currently allocated length of the void *value.
01084         For fixed length types, setting len to 0 will allow it to default to the fixed length size of the type.
01085         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01086  */
01087 LBMPDMExpDLL int lbmpdm_msg_set_field_value(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle, void *value, size_t len);
01088 
01089 /*! \brief Sets an array of field values in a message
01090         \param message -- A pointer to a PDM message object.
01091         \param handle -- A valid field handle
01092         \param value -- A pointer to an array of values that should be set into the message
01093         \param len -- A size_t array describing the currently allocated lengths of each element in the value array
01094         For fixed length types, setting a len element to 0 will allow it to default to the fixed length size of the type.
01095         \param num_arr_elem -- The number of elements in the value and len array.
01096         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01097  */
01098 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);
01099 
01100 /*! \brief Removes a field value from a message (marking it unset)
01101         \param message -- A pointer to a PDM message object.
01102         \param handle -- A valid field handle
01103         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01104  */
01105 LBMPDMExpDLL int lbmpdm_msg_remove_field_value(lbmpdm_msg_t *message, lbmpdm_field_handle_t handle);
01106 
01107 /*! \brief Sets the message include definition flag.
01108         \param message -- A pointer to a PDM message object.
01109         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01110  */
01111 LBMPDMExpDLL int lbmpdm_msg_set_incl_defn_flag(lbmpdm_msg_t *message);
01112 
01113 /*! \brief Unsets the message include definition flag.
01114         \param message -- A pointer to a PDM message object.
01115         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01116  */
01117 LBMPDMExpDLL int lbmpdm_msg_unset_incl_defn_flag(lbmpdm_msg_t *message);
01118 
01119 /*! \brief Deletes the allocated resources inside the field value struct.  This does NOT free
01120         the actual field value struct passed in (which should be done outside PDM).
01121         Also, this does not affect the field value in the message, only this field value struct.
01122         \sa lbmpdm_msg_get_field_value_stct
01123         \param field_value -- A pointer to a field value structure.
01124         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01125  */
01126 LBMPDMExpDLL int lbmpdm_field_value_stct_delete(lbmpdm_field_value_t *field_value);
01127 
01128 /*! \brief Serialize a message to a buffer.
01129         The message that is passed in is serialized into the
01130         caller's supplied buffer.
01131         \param message A PDM Message to be serialized
01132         \param buffer The caller allocated buffer
01133         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01134  */
01135 LBMPDMExpDLL int lbmpdm_msg_serialize(lbmpdm_msg_t *message, char *buffer);
01136 
01137 /*! \brief Deserialize the associated buffer into a newly created message
01138 
01139         This will take the passed buffer and deserialize the contents into a newly
01140         created message.  It will verify that the buffer is a valid PDM message before
01141         trying to deserialize.  When finished with the message, the caller must call
01142         lbmpdm_msg_delete() to properly dispose of the message.
01143 
01144         \sa lbmpdm_msg_delete()
01145         \param message A pointer to a previously created PDM message object
01146         \param bufptr The buffer to be deserialized
01147         \param buflen The length of the buffer.
01148         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01149  */
01150 LBMPDMExpDLL int lbmpdm_msg_deserialize(lbmpdm_msg_t *message, const char *bufptr, uint32_t buflen);
01151 
01152 /*! \brief Serialize a message to a buffer and return the buffer.
01153         The message that is passed in is serialized into a buffer
01154         which will be cleaned up when the message is deleted.
01155         Use lbmpdm_msg_get_length to get the length of the buffer.
01156         \param message A PDM Message to be serialized
01157         \return a valid char * or NULL if an error occurred.
01158  */
01159 LBMPDMExpDLL char *lbmpdm_msg_get_data(lbmpdm_msg_t *message);
01160 
01161 /*! \brief Creates a pdm iterator to iterate through the fields in a message
01162         \param iter -- Pointer to the iterator pointer which will be created
01163         \param message -- the pdm message
01164         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01165  */
01166 LBMPDMExpDLL int lbmpdm_iter_create(lbmpdm_iter_t **iter, lbmpdm_msg_t *message);
01167 
01168 /*! \brief Creates a pdm iterator to iterate through the fields in a message starting at a particular field
01169         \param iter -- Pointer to the iterator pointer which will be created
01170         \param message -- the pdm message
01171         \param field_handle -- the handle to the field where the iterator should start
01172         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01173  */
01174 LBMPDMExpDLL int lbmpdm_iter_create_from_field_handle(lbmpdm_iter_t **iter, lbmpdm_msg_t *message, lbmpdm_field_handle_t field_handle);
01175 
01176 /*! \brief Deletes the iterator
01177         \param iter -- the pdm iterator
01178         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01179  */
01180 LBMPDMExpDLL int lbmpdm_iter_delete(lbmpdm_iter_t *iter);
01181 
01182 /*! \brief Gets the current field handle from the iterator
01183         \param iter -- The pdm iterator
01184         \return the lbmpdm_field_handle_t (field handle)
01185  */
01186 LBMPDMExpDLL lbmpdm_field_handle_t lbmpdm_iter_get_current(lbmpdm_iter_t *iter);
01187 
01188 /*! \brief Sets the iterator back to the first field
01189         \param iter -- the pdm iterator
01190         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01191  */
01192 LBMPDMExpDLL int lbmpdm_iter_first(lbmpdm_iter_t *iter);
01193 
01194 /*! \brief Steps the iterator to the next first field
01195         \param iter -- the pdm iterator
01196         \return PDM_SUCCESS if successful or PDM_ERR_NO_MORE_FIELDS if moved beyond the last field
01197  */
01198 LBMPDMExpDLL int lbmpdm_iter_next(lbmpdm_iter_t *iter);
01199 
01200 /*! \brief Checks to see if the iterator has another field to step to
01201         \param iter -- the pdm iterator
01202         \return PDM_TRUE if there are more fields or PDM_FALSE if this is the last field
01203  */
01204 LBMPDMExpDLL uint8_t lbmpdm_iter_has_next(lbmpdm_iter_t *iter);
01205 
01206 /*! \brief Checks to see if the current field is set
01207         \param iter -- the pdm iterator
01208         \return PDM_TRUE if the current field is set or PDM_FALSE if it is not
01209  */
01210 LBMPDMExpDLL uint8_t lbmpdm_iter_is_current_set(lbmpdm_iter_t *iter);
01211 
01212 /*! \brief Sets the message used to step through by this iterator
01213         \param iter -- the pdm iterator
01214         \param message -- the pdm message to step through
01215         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01216  */
01217 LBMPDMExpDLL int lbmpdm_iter_set_msg(lbmpdm_iter_t *iter, lbmpdm_msg_t *message);
01218 
01219 /*! \brief Sets the current field value to the value passed in
01220         \param iter -- the pdm iterator
01221         \param value -- the new field value
01222         \param len -- the len of the enw field value
01223         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01224  */
01225 LBMPDMExpDLL int lbmpdm_iter_set_current_field_value(lbmpdm_iter_t *iter, void *value, size_t len);
01226 
01227 /*! \brief Sets the current field values to the passed array of values
01228         \param iter -- the pdm iterator
01229         \param value -- A pointer to an array of values that should be set into the message
01230         \param len -- A size_t array describing the currently allocated lengths of each element in the value array
01231         For fixed length types, setting a len element to 0 will allow it to default to the fixed length size of the type.
01232         \param num_arr_elem -- The number of elements in the value and len array.
01233         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01234  */
01235 LBMPDMExpDLL int lbmpdm_iter_set_current_field_value_vec(lbmpdm_iter_t *iter, void *value, size_t len[], size_t num_arr_elem);
01236 
01237 /*! \brief Gets a field value from the iterator's current field
01238         \param iter -- the pdm iterator
01239         \param value -- A pointer to a value big enough to hold the field value
01240         \param len -- A pointer describing the currently allocated length of the void *value.  If it is not large
01241         enough to hold the field value, PDM_FAILURE will be returned and len will be set to the needed length.
01242         \param num_arr_elem -- The number of elements in the value and len array.
01243         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01244  */
01245 LBMPDMExpDLL int lbmpdm_iter_get_current_field_value(lbmpdm_iter_t *iter, void *value, size_t *len);
01246 
01247 /*! \brief Gets an array of field values from the iterator's current field
01248         \param iter -- the pdm iterator
01249         \param value -- A pointer to an array of values big enough to hold the field values
01250         \param len -- An array of lengths describing the currently allocated length of each void *value array element.  If it is not large
01251         enough to hold the field value, PDM_FAILURE will be returned and that len element will be set to the needed length.
01252         \param num_arr_elem -- The number of elements in the value and len array.
01253         \return PDM_SUCCESS if successful or PDM_FAILURE otherwise.
01254  */
01255 LBMPDMExpDLL int lbmpdm_iter_get_current_field_value_vec(lbmpdm_iter_t *iter, void *value, size_t len[], size_t *num_arr_elem);
01256 
01257 #if defined(__cplusplus)
01258 }
01259 #endif /* __cplusplus */
01260 
01261 #endif /* _LBMPDM_H_ */
01262 

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