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