00001 /** \file lbmsdm.h 00002 \brief Ultra Messaging (UM) Self-Describing Message (SDM) API 00003 \author David K. Ameiss - Informatica Corporation 00004 \version $Id: //UMprod/REL_5_3_6/29West/lbm/src/sdm/lbm/lbmsdm.h#2 $ 00005 00006 The Ultra Messaging (UM) Self-Describing Message (SDM) 00007 API Description. Included are types, constants, and functions related 00008 to the API. Contents are subject to change. 00009 00010 All of the documentation and software included in this and any 00011 other Informatica Corporation Ultra Messaging Releases 00012 Copyright (C) Informatica Corporation. All rights reserved. 00013 00014 Redistribution and use in source and binary forms, with or without 00015 modification, are permitted only as covered by the terms of a 00016 valid software license agreement with Informatica Corporation. 00017 00018 Copyright (C) 2007-2014, Informatica Corporation. All Rights Reserved. 00019 00020 THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES 00021 EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF 00022 NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR 00023 PURPOSE. INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE 00024 UNINTERRUPTED OR ERROR-FREE. INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE 00025 LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR 00026 INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE 00027 TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF 00028 THE LIKELIHOOD OF SUCH DAMAGES. 00029 00030 The LBM Self-Describing Message (SDM) API provides a framework for applications 00031 to create and use messages containing self-describing data (name and type). 00032 An SDM message contains one or more \b fields. Each field consists of: 00033 - A name, limited to 255 characters in length. Field names are \em not case-sensitive. 00034 So, "price" is the same as "Price" is the same as "PRICE". 00035 - A type (discussed below). 00036 - A value (particular to the field type). 00037 Each named field may only appear once in a message. If multiple fields of the same name 00038 and type are needed, create an array field. A field in a nested message \b may have the 00039 same name as a field in the outer message, though. 00040 00041 \par Field types 00042 The following field types (and arrays thereof) are supported by SDM: 00043 <table> 00044 <tr> 00045 <td>Description</td> 00046 <td>SDM Type</td> 00047 <td>C Type</td> 00048 </tr> 00049 <tr> 00050 <td>Boolean</td> 00051 <td>::LBMSDM_TYPE_BOOLEAN</td> 00052 <td><tt>uint8_t</tt></td> 00053 </tr> 00054 <tr> 00055 <td>8-bit signed integer</td> 00056 <td>::LBMSDM_TYPE_INT8</td> 00057 <td><tt>int8_t</tt></td> 00058 </tr> 00059 <tr> 00060 <td>8-bit unsigned integer</td> 00061 <td>::LBMSDM_TYPE_UINT8</td> 00062 <td><tt>uint8_t</tt></td> 00063 </tr> 00064 <tr> 00065 <td>16-bit signed integer</td> 00066 <td>::LBMSDM_TYPE_INT16</td> 00067 <td><tt>int16_t</tt></td> 00068 </tr> 00069 <tr> 00070 <td>16-bit unsigned integer</td> 00071 <td>::LBMSDM_TYPE_UINT16</td> 00072 <td><tt>uint16_t</tt></td> 00073 </tr> 00074 <tr> 00075 <td>32-bit signed integer</td> 00076 <td>::LBMSDM_TYPE_INT32</td> 00077 <td><tt>int32_t</tt></td> 00078 </tr> 00079 <tr> 00080 <td>32-bit unsigned integer</td> 00081 <td>::LBMSDM_TYPE_UINT32</td> 00082 <td><tt>uint32_t</tt></td> 00083 </tr> 00084 <tr> 00085 <td>64-bit signed integer</td> 00086 <td>::LBMSDM_TYPE_INT64</td> 00087 <td><tt>int64_t</tt></td> 00088 </tr> 00089 <tr> 00090 <td>64-bit unsigned integer</td> 00091 <td>::LBMSDM_TYPE_UINT64</td> 00092 <td><tt>uint64_t</tt></td> 00093 </tr> 00094 <tr> 00095 <td>Single-precision floating point</td> 00096 <td>::LBMSDM_TYPE_FLOAT</td> 00097 <td><tt>float</tt></td> 00098 </tr> 00099 <tr> 00100 <td>Double-precision floating point</td> 00101 <td>::LBMSDM_TYPE_DOUBLE</td> 00102 <td><tt>double</tt></td> 00103 </tr> 00104 <tr> 00105 <td>String</td> 00106 <td>::LBMSDM_TYPE_STRING</td> 00107 <td><tt>char *</tt></td> 00108 </tr> 00109 <tr> 00110 <td>Scaled decimal</td> 00111 <td>::LBMSDM_TYPE_DECIMAL</td> 00112 <td>::lbmsdm_decimal_t</td> 00113 </tr> 00114 <tr> 00115 <td>Timestamp</td> 00116 <td>::LBMSDM_TYPE_TIMESTAMP</td> 00117 <td><tt>struct timeval</tt></td> 00118 </tr> 00119 <tr> 00120 <td>Nested message</td> 00121 <td>::LBMSDM_TYPE_MESSAGE</td> 00122 <td>::lbmsdm_msg_t <tt>*</tt></td> 00123 </tr> 00124 <tr> 00125 <td>Binary large object (BLOB)</td> 00126 <td>::LBMSDM_TYPE_BLOB</td> 00127 <td><tt>void *</tt></td> 00128 </tr> 00129 <tr> 00130 <td>Unicode string</td> 00131 <td>::LBMSDM_TYPE_UNICODE</td> 00132 <td><tt>wchar_t *</tt></td> 00133 </tr> 00134 </table> 00135 \par 00136 Note that arrays are homogeneous. 00137 All elements of an array must be of the same type. 00138 An error is reported if an attempt is made to add an element of one type to 00139 an array containing elements of a different type. 00140 \par Building a message 00141 A message must be created (via ::lbmsdm_msg_create() or ::lbmsdm_msg_parse()) 00142 before fields can be added. 00143 \par 00144 Once a field exists within a message, 00145 it can be referenced in one of three ways: 00146 - By the name associated with the field. 00147 - By index. This refers to the sequential position of the field within a message. 00148 The first field has index 0, the second has index 1, and so forth. 00149 - By iterator. See below for more information on iterators. 00150 \par Adding fields to a message 00151 Scalar (non-array) fields are added to a message via the <tt>lbmsdm_msg_add_xxx()</tt> 00152 API functions, 00153 where <tt>xxx</tt> is the type of the field being added. 00154 See the module \ref add for information on these functions. 00155 \par 00156 When adding a field, data of the appropriate type must be supplied. 00157 As an example, to add a 32-bit signed integer field named "quantity" to a message: 00158 \code 00159 int32_t quant = 50; 00160 int rc; 00161 rc = lbmsdm_msg_add_int32(msg, "quantity", quant); 00162 \endcode 00163 \par 00164 Alternatively, 00165 literals may be used to specify the value. 00166 The above example could also be coded as: 00167 \code 00168 rc = lbmsdm_msg_add_int32(msg, "quantity", 50); 00169 \endcode 00170 \par Adding array fields to a message 00171 Array fields are added to a message in two steps. 00172 First, the field itself is added via the <tt>lbmsdm_msg_add_xxx_array()</tt> API functions, 00173 where <tt>xxx</tt> is the type of the field being added. 00174 This does not provide a value for the field. 00175 See the module \ref add_array for information on these functions. 00176 \par 00177 Second, 00178 individual elements are added to the array field. 00179 This is done via the <tt>lbmsdm_msg_add_xxx_elem_idx()</tt>, 00180 <tt>lbmsdm_msg_add_xxx_elem_name()</tt>, 00181 and <tt>lbmsdm_iter_add_xxx_elem()</tt> API functions. 00182 See the modules \ref add_elem_idx, \ref add_elem_name, and \ref add_elem_iter 00183 for detailed information on these functions. 00184 \par 00185 As an example, 00186 the following code illustrates how to create a string array field, 00187 and add 3 elements to it. 00188 \code 00189 rc = lbmsdm_msg_add_string_array(msg, "string_array"); 00190 rc = lbmsdm_msg_add_string_elem_name(msg, "string_array", "String1"); 00191 rc = lbmsdm_msg_add_string_elem_name(msg, "string_array", "String2"); 00192 rc = lbmsdm_msg_add_string_elem_name(msg, "string_array", "String3"); 00193 \endcode 00194 \par Serializing the message 00195 Once the SDM message is constructed, it must be serialized for transmission. 00196 The API function ::lbmsdm_msg_get_data() returns a static pointer to a buffer 00197 containing the serialized form of the message, suitable for transmission. 00198 The length of the serialized data may be obtained via the API function 00199 ::lbmsdm_msg_get_datalen(). 00200 For example, a constructed message may be sent by: 00201 \code 00202 rc = lbm_src_send(src, lbmsdm_msg_get_data(msg), lbmsdm_msg_get_length(msg), 0); 00203 \endcode 00204 \par 00205 The pointer returned by ::lbmsdm_msg_get_data() is owned by the SDM API, 00206 and will automatically be freed when the message is destroyed. 00207 \par Deserializing a message 00208 When a message is received, it must be deserialized so that individual fields can be 00209 accessed. This is done via the ::lbmsdm_msg_parse() API function: 00210 \code 00211 lbmsdm_msg_t * sdmmsg; 00212 rc = lbmsdm_msg_parse(&sdmmsg, lbmmsg->data, lbmmsg->len); 00213 \endcode 00214 \par Disposing of a message 00215 Once an SDM message (created by either the ::lbmsdm_msg_create() or ::lbmsdm_msg_parse() 00216 API calls) is no longer needed, it must be disposed of to avoid a resource leak. 00217 This is done via the ::lbmsdm_msg_destroy() API call. 00218 \par Retrieving field information 00219 A number of API functions are available to retrieve information about individual fields. 00220 - ::lbmsdm_msg_get_fldcnt() returns the number of fields in the message. 00221 - ::lbmsdm_msg_get_name_idx() and ::lbmsdm_iter_get_name() return the field name 00222 associated with the referenced field. 00223 - ::lbmsdm_msg_get_type_name(), ::lbmsdm_msg_get_type_idx(), and 00224 ::lbmsdm_iter_get_type() return the type of the referenced field. 00225 - ::lbmsdm_msg_get_elemcnt_name(), ::lbmsdm_msg_get_elemcnt_idx(), 00226 and ::lbmsdm_iter_get_elemcnt() return the number of elements in an 00227 array field. 00228 - ::lbmsdm_msg_get_len_name(), ::lbmsdm_msg_get_len_idx(), and 00229 ::lbmsdm_iter_get_len() return the length (in bytes) required for a field. 00230 - ::lbmsdm_msg_get_elemlen_name(), ::lbmsdm_msg_get_elemlen_idx(), 00231 and ::lbmsdm_iter_get_elemlen() return the length (in bytes) for a specific 00232 element in an array field. 00233 \par Fetching fields from a message 00234 When fetching a field from a message, the field may be referenced by name, by index, 00235 or via an iterator. 00236 \par 00237 Scalar (non-array) fields may be retrieved via the <tt>lbmsdm_msg_get_xxx_name()</tt>, 00238 <tt>lbmsdm_msg_get_xxx_idx()</tt>, or <tt>lbmsdm_iter_get_xxx()</tt> functions, 00239 where <tt>xxx</tt> is the type the field value should be retrieved as. 00240 The sections \ref get_scalar_name, \ref get_scalar_idx, and \ref get_scalar_iter contain 00241 detailed information on these functions. 00242 \par 00243 Array field elements may be retrieved via the <tt>lbmsdm_msg_get_xxx_elem_name()</tt>, 00244 <tt>lbmsdm_msg_get_xxx_elem_idx()</tt>, or <tt>lbmsdm_iter_get_xxx_elem()</tt> functions, 00245 where <tt>xxx</tt> is the type the field element value should be retrieved as. 00246 The sections \ref get_elem_name, \ref get_elem_idx, and \ref get_elem_iter contain 00247 detailed information on these functions. 00248 \par Type conversion 00249 A limited form of automatic type conversion is provided. 00250 For example, given a field defined as ::LBMSDM_TYPE_UINT16, its value may be retrieved 00251 as an ::LBMSDM_TYPE_UINT32. 00252 The following table details which type conversions are supported. 00253 <table> 00254 <tr> 00255 <td colspan=2 rowspan=2></td> 00256 <th colspan=17 align=center>To</th> 00257 </tr> 00258 <tr> 00259 <th>boolean</th> 00260 <th>int8</th> 00261 <th>uint8</th> 00262 <th>int16</th> 00263 <th>uint16</th> 00264 <th>int32</th> 00265 <th>uint32</th> 00266 <th>int64</th> 00267 <th>uint64</th> 00268 <th>float</th> 00269 <th>double</th> 00270 <th>string</th> 00271 <th>unicode</th> 00272 <th>timestamp</th> 00273 <th>BLOB</th> 00274 <th>message</th> 00275 <th>decimal</th> 00276 </tr> 00277 <tr align=center> 00278 <th rowspan=17>From</th> 00279 <th>boolean</th> 00280 <td align=center>Yes</td> 00281 <td align=center>Yes</td> 00282 <td align=center>Yes</td> 00283 <td align=center>Yes</td> 00284 <td align=center>Yes</td> 00285 <td align=center>Yes</td> 00286 <td align=center>Yes</td> 00287 <td align=center>Yes</td> 00288 <td align=center>Yes</td> 00289 <td align=center>Yes</td> 00290 <td align=center>Yes</td> 00291 <td align=center>No</td> 00292 <td align=center>No</td> 00293 <td align=center>No</td> 00294 <td align=center>No</td> 00295 <td align=center>No</td> 00296 <td align=center>Yes</td> 00297 </tr> 00298 <tr> 00299 <th>int8</th> 00300 <td align=center>Yes</td> 00301 <td align=center>Yes</td> 00302 <td align=center>Yes</td> 00303 <td align=center>Yes</td> 00304 <td align=center>Yes</td> 00305 <td align=center>Yes</td> 00306 <td align=center>Yes</td> 00307 <td align=center>Yes</td> 00308 <td align=center>Yes</td> 00309 <td align=center>Yes</td> 00310 <td align=center>Yes</td> 00311 <td align=center>No</td> 00312 <td align=center>No</td> 00313 <td align=center>No</td> 00314 <td align=center>No</td> 00315 <td align=center>No</td> 00316 <td align=center>Yes</td> 00317 </tr> 00318 <tr> 00319 <th>uint8</th> 00320 <td align=center>Yes</td> 00321 <td align=center>Yes</td> 00322 <td align=center>Yes</td> 00323 <td align=center>Yes</td> 00324 <td align=center>Yes</td> 00325 <td align=center>Yes</td> 00326 <td align=center>Yes</td> 00327 <td align=center>Yes</td> 00328 <td align=center>Yes</td> 00329 <td align=center>Yes</td> 00330 <td align=center>Yes</td> 00331 <td align=center>No</td> 00332 <td align=center>No</td> 00333 <td align=center>No</td> 00334 <td align=center>No</td> 00335 <td align=center>No</td> 00336 <td align=center>Yes</td> 00337 </tr> 00338 <tr> 00339 <th>int16</th> 00340 <td align=center>Yes</td> 00341 <td align=center>Yes</td> 00342 <td align=center>Yes</td> 00343 <td align=center>Yes</td> 00344 <td align=center>Yes</td> 00345 <td align=center>Yes</td> 00346 <td align=center>Yes</td> 00347 <td align=center>Yes</td> 00348 <td align=center>Yes</td> 00349 <td align=center>Yes</td> 00350 <td align=center>Yes</td> 00351 <td align=center>No</td> 00352 <td align=center>No</td> 00353 <td align=center>No</td> 00354 <td align=center>No</td> 00355 <td align=center>No</td> 00356 <td align=center>Yes</td> 00357 </tr> 00358 <tr> 00359 <th>uint16</th> 00360 <td align=center>Yes</td> 00361 <td align=center>Yes</td> 00362 <td align=center>Yes</td> 00363 <td align=center>Yes</td> 00364 <td align=center>Yes</td> 00365 <td align=center>Yes</td> 00366 <td align=center>Yes</td> 00367 <td align=center>Yes</td> 00368 <td align=center>Yes</td> 00369 <td align=center>Yes</td> 00370 <td align=center>Yes</td> 00371 <td align=center>No</td> 00372 <td align=center>No</td> 00373 <td align=center>No</td> 00374 <td align=center>No</td> 00375 <td align=center>No</td> 00376 <td align=center>Yes</td> 00377 </tr> 00378 <tr> 00379 <th>int32</th> 00380 <td align=center>Yes</td> 00381 <td align=center>Yes</td> 00382 <td align=center>Yes</td> 00383 <td align=center>Yes</td> 00384 <td align=center>Yes</td> 00385 <td align=center>Yes</td> 00386 <td align=center>Yes</td> 00387 <td align=center>Yes</td> 00388 <td align=center>Yes</td> 00389 <td align=center>Yes</td> 00390 <td align=center>Yes</td> 00391 <td align=center>No</td> 00392 <td align=center>No</td> 00393 <td align=center>No</td> 00394 <td align=center>No</td> 00395 <td align=center>No</td> 00396 <td align=center>Yes</td> 00397 </tr> 00398 <tr> 00399 <th>uint32</th> 00400 <td align=center>Yes</td> 00401 <td align=center>Yes</td> 00402 <td align=center>Yes</td> 00403 <td align=center>Yes</td> 00404 <td align=center>Yes</td> 00405 <td align=center>Yes</td> 00406 <td align=center>Yes</td> 00407 <td align=center>Yes</td> 00408 <td align=center>Yes</td> 00409 <td align=center>Yes</td> 00410 <td align=center>Yes</td> 00411 <td align=center>No</td> 00412 <td align=center>No</td> 00413 <td align=center>No</td> 00414 <td align=center>No</td> 00415 <td align=center>No</td> 00416 <td align=center>Yes</td> 00417 </tr> 00418 <tr> 00419 <th>int64</th> 00420 <td align=center>Yes</td> 00421 <td align=center>Yes</td> 00422 <td align=center>Yes</td> 00423 <td align=center>Yes</td> 00424 <td align=center>Yes</td> 00425 <td align=center>Yes</td> 00426 <td align=center>Yes</td> 00427 <td align=center>Yes</td> 00428 <td align=center>Yes</td> 00429 <td align=center>Yes</td> 00430 <td align=center>Yes</td> 00431 <td align=center>No</td> 00432 <td align=center>No</td> 00433 <td align=center>No</td> 00434 <td align=center>No</td> 00435 <td align=center>No</td> 00436 <td align=center>Yes</td> 00437 </tr> 00438 <tr> 00439 <th>uint64</th> 00440 <td align=center>Yes</td> 00441 <td align=center>Yes</td> 00442 <td align=center>Yes</td> 00443 <td align=center>Yes</td> 00444 <td align=center>Yes</td> 00445 <td align=center>Yes</td> 00446 <td align=center>Yes</td> 00447 <td align=center>Yes</td> 00448 <td align=center>Yes</td> 00449 <td align=center>Yes</td> 00450 <td align=center>Yes</td> 00451 <td align=center>No</td> 00452 <td align=center>No</td> 00453 <td align=center>No</td> 00454 <td align=center>No</td> 00455 <td align=center>No</td> 00456 <td align=center>Yes</td> 00457 </tr> 00458 <tr> 00459 <th>float</th> 00460 <td align=center>Yes</td> 00461 <td align=center>Yes</td> 00462 <td align=center>Yes</td> 00463 <td align=center>Yes</td> 00464 <td align=center>Yes</td> 00465 <td align=center>Yes</td> 00466 <td align=center>Yes</td> 00467 <td align=center>Yes</td> 00468 <td align=center>Yes</td> 00469 <td align=center>Yes</td> 00470 <td align=center>Yes</td> 00471 <td align=center>No</td> 00472 <td align=center>No</td> 00473 <td align=center>No</td> 00474 <td align=center>No</td> 00475 <td align=center>No</td> 00476 <td align=center>No</td> 00477 </tr> 00478 <tr> 00479 <th>double</th> 00480 <td align=center>Yes</td> 00481 <td align=center>Yes</td> 00482 <td align=center>Yes</td> 00483 <td align=center>Yes</td> 00484 <td align=center>Yes</td> 00485 <td align=center>Yes</td> 00486 <td align=center>Yes</td> 00487 <td align=center>Yes</td> 00488 <td align=center>Yes</td> 00489 <td align=center>Yes</td> 00490 <td align=center>Yes</td> 00491 <td align=center>No</td> 00492 <td align=center>No</td> 00493 <td align=center>No</td> 00494 <td align=center>No</td> 00495 <td align=center>No</td> 00496 <td align=center>No</td> 00497 </tr> 00498 <tr> 00499 <th>string</th> 00500 <td align=center>No</td> 00501 <td align=center>No</td> 00502 <td align=center>No</td> 00503 <td align=center>No</td> 00504 <td align=center>No</td> 00505 <td align=center>No</td> 00506 <td align=center>No</td> 00507 <td align=center>No</td> 00508 <td align=center>No</td> 00509 <td align=center>No</td> 00510 <td align=center>No</td> 00511 <td align=center>Yes</td> 00512 <td align=center>No</td> 00513 <td align=center>No</td> 00514 <td align=center>No</td> 00515 <td align=center>No</td> 00516 <td align=center>No</td> 00517 </tr> 00518 <tr> 00519 <th>unicode</th> 00520 <td align=center>No</td> 00521 <td align=center>No</td> 00522 <td align=center>No</td> 00523 <td align=center>No</td> 00524 <td align=center>No</td> 00525 <td align=center>No</td> 00526 <td align=center>No</td> 00527 <td align=center>No</td> 00528 <td align=center>No</td> 00529 <td align=center>No</td> 00530 <td align=center>No</td> 00531 <td align=center>No</td> 00532 <td align=center>Yes</td> 00533 <td align=center>No</td> 00534 <td align=center>No</td> 00535 <td align=center>No</td> 00536 <td align=center>No</td> 00537 </tr> 00538 <tr> 00539 <th>timestamp</th> 00540 <td align=center>No</td> 00541 <td align=center>No</td> 00542 <td align=center>No</td> 00543 <td align=center>No</td> 00544 <td align=center>No</td> 00545 <td align=center>No</td> 00546 <td align=center>No</td> 00547 <td align=center>No</td> 00548 <td align=center>No</td> 00549 <td align=center>No</td> 00550 <td align=center>No</td> 00551 <td align=center>No</td> 00552 <td align=center>No</td> 00553 <td align=center>Yes</td> 00554 <td align=center>No</td> 00555 <td align=center>No</td> 00556 <td align=center>No</td> 00557 </tr> 00558 <tr> 00559 <th>BLOB</th> 00560 <td align=center>No</td> 00561 <td align=center>No</td> 00562 <td align=center>No</td> 00563 <td align=center>No</td> 00564 <td align=center>No</td> 00565 <td align=center>No</td> 00566 <td align=center>No</td> 00567 <td align=center>No</td> 00568 <td align=center>No</td> 00569 <td align=center>No</td> 00570 <td align=center>No</td> 00571 <td align=center>No</td> 00572 <td align=center>No</td> 00573 <td align=center>No</td> 00574 <td align=center>Yes</td> 00575 <td align=center>No</td> 00576 <td align=center>No</td> 00577 </tr> 00578 <tr> 00579 <th>message</th> 00580 <td align=center>No</td> 00581 <td align=center>No</td> 00582 <td align=center>No</td> 00583 <td align=center>No</td> 00584 <td align=center>No</td> 00585 <td align=center>No</td> 00586 <td align=center>No</td> 00587 <td align=center>No</td> 00588 <td align=center>No</td> 00589 <td align=center>No</td> 00590 <td align=center>No</td> 00591 <td align=center>No</td> 00592 <td align=center>No</td> 00593 <td align=center>No</td> 00594 <td align=center>No</td> 00595 <td align=center>Yes</td> 00596 <td align=center>No</td> 00597 </tr> 00598 <tr> 00599 <th>decimal</th> 00600 <td align=center>Yes</td> 00601 <td align=center>Yes</td> 00602 <td align=center>Yes</td> 00603 <td align=center>Yes</td> 00604 <td align=center>Yes</td> 00605 <td align=center>Yes</td> 00606 <td align=center>Yes</td> 00607 <td align=center>Yes</td> 00608 <td align=center>Yes</td> 00609 <td align=center>Yes</td> 00610 <td align=center>Yes</td> 00611 <td align=center>No</td> 00612 <td align=center>No</td> 00613 <td align=center>No</td> 00614 <td align=center>No</td> 00615 <td align=center>No</td> 00616 <td align=center>Yes</td> 00617 </tr> 00618 </table> 00619 \par 00620 The above conversion rules apply also when retrieving array elements. 00621 \par Fetching string, unicode, and BLOB values 00622 When fetching a field or array element value as a string, unicode, or BLOB, 00623 the data is copied into a buffer provided by the application. 00624 In addition to the buffer, 00625 the size of the buffer must be given. 00626 The size is specified in bytes for string and BLOB fields, 00627 and in <tt>wchar_t</tt>s for unicode fields. 00628 If the size specified is too small for the data, 00629 the error code ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH is returned. 00630 \par 00631 \par Fetching message fields 00632 When fetching the value of a message field, 00633 a copy of the message is created (via ::lbmsdm_msg_clone()) and returned. 00634 It is the application's responsibility to destroy the message (via ::lbmsdm_msg_destroy()) 00635 when it is no longer needed. 00636 \par Modifying fields in a message 00637 Existing fields in a message may be modified, both in terms of the field type and 00638 field value. 00639 For scalar (non-array) fields, 00640 the <tt>lbmsdm_msg_set_xxx_idx()</tt>, <tt>lbmsdm_msg_set_xxx_name()</tt>, 00641 and <tt>lbmsdm_iter_set_xxx()</tt> API functions may be used, 00642 where <tt>xxx</tt> is the type to be assigned to the field. 00643 See the sections \ref set_idx, \ref set_name, and \ref set_iter for information 00644 on these functions. 00645 \par 00646 For array fields, 00647 the <tt>lbmsdm_msg_set_xxx_array_idx()</tt>, <tt>lbmsdm_msg_set_xxx_array_name()</tt>, 00648 and <tt>lbmsdm_iter_set_xxx_array()</tt> API functions may be used, 00649 where <tt>xxx</tt> is the type to be assigned to the field. 00650 See the sections \ref set_array_idx, \ref set_array_name, and \ref set_array_iter 00651 for information on these functions. 00652 As when adding an array field to a message, 00653 once the field type has been set to an array type, 00654 individual elements must be added to the array field. 00655 \par 00656 Individual elements of an array field may be modified via the <tt>lbmsdm_msg_set_xxx_elem_idx()</tt>, 00657 <tt>lbmsdm_msg_set_xxx_elem_name()</tt>, and <tt>lbmsdm_iter_set_xxx_elem()</tt> API functions. 00658 See the sections \ref set_elem_idx, \ref set_elem_name, and \ref set_elem_iter for 00659 information on these functions. 00660 Note that arrays must contain homogeneous elements, 00661 so the type of an array element may not be changed, 00662 and is considered an error. 00663 \par Deleting fields from a message 00664 A field may be deleted from a message via the ::lbmsdm_msg_del_idx(), 00665 ::lbmsdm_msg_del_name(), and ::lbmsdm_iter_del() API calls. 00666 Deleting a field will cause any fields following it to be moved down one position, 00667 changing the index of those fields and potentially invalidating any iterators for 00668 that message. 00669 \par Deleting elements from an array field 00670 Individual elements may be deleted from an array field via the ::lbmsdm_msg_del_elem_idx(), 00671 ::lbmsdm_msg_del_elem_name(), and ::lbmsdm_iter_del_elem() API functions. 00672 \par Null fields 00673 SDM supports the concept of a \b null field. 00674 A null field is present in the message, 00675 but has no value associated with it. 00676 Once added to a message, 00677 a field may be set to null via the ::lbmsdm_msg_set_null_idx(), ::lbmsdm_msg_set_null_name(), 00678 or ::lbmsdm_iter_set_null() API functions. 00679 Setting the field (which may be either a scalar or array field) to null 00680 removes any values currently associated with the field. 00681 \par 00682 The ::lbmsdm_msg_is_null_idx(), ::lbmsdm_msg_is_null_name(), and ::lbmsdm_iter_is_null() 00683 API functions allow an application to determine if a given field is null. 00684 \par 00685 Attempting to retrieve a value or element value from a null field is not allowed, 00686 and will return an error. 00687 \par Iterators 00688 A field iterator allows sequential operation on the fields of a message without requiring 00689 the field name or index. 00690 An iterator is created via ::lbmsdm_iter_create(), 00691 the first field in a message is located via ::lbmsdm_iter_first(), 00692 and the next field is located via ::lbmsdm_iter_next(). 00693 An iterator should be destroyed when no longer needed, using the ::lbmsdm_iter_destroy() 00694 API call. 00695 \par 00696 Message fields may be queried, fetched, modified, and deleted via an iterator. 00697 In each case, 00698 the operation applies to the field currently referenced by the iterator. 00699 \par Error information 00700 All functions return a value to indicate the success of failure of the operation. 00701 Most return ::LBMSDM_SUCCESS to indicate success, or ::LBMSDM_FAILURE otherwise. 00702 Consult the individual function documentation for exceptions. 00703 \par 00704 The function ::lbmsdm_errnum() can be used to retrieve a detailed error code for the last 00705 error encountered, while ::lbmsdm_errmsg() will return a descriptive error message. 00706 \par Message Options 00707 The performance of SDM can be tuned through the use of message options. 00708 Options are contained within an attributes object (::lbmsdm_msg_attr_t), 00709 which is created via ::lbmsdm_msg_attr_create(). 00710 When no longer needed, 00711 an attributes object can be discarded by calling ::lbmsdm_msg_attr_delete(). 00712 Individual options within an attributes object can be set via ::lbmsdm_msg_attr_setopt() 00713 and ::lbmsdm_msg_attr_str_setopt(), 00714 and can be queried via ::lbmsdm_msg_attr_getopt() and ::lbmsdm_msg_attr_str_getopt(). 00715 A set of options can be specified at message creation time using ::lbmsdm_msg_create_ex() 00716 and ::lbmsdm_msg_parse_ex(). 00717 \par 00718 The following table lists the supported message options. 00719 <table> 00720 <tr> 00721 <th>Option</th> 00722 <th>Data type</th> 00723 <th>Allowed values</th> 00724 <th>Default</th> 00725 <th>Description</th> 00726 </tr> 00727 <tr> 00728 <th align="left"><tt>field_array_allocation</tt></th> 00729 <td align="center"><tt>int</tt></td> 00730 <td align="center">Any integer >= 0</td> 00731 <td align="center">32</td> 00732 <td> 00733 Internally, SDM maintains an array of field entries within a message. 00734 This option controls both the number of field entries initially allocated 00735 when the message is created, 00736 and the increment used when the array must be expanded when a field is added 00737 but the array is full. 00738 <p> 00739 If it is known that a large number of fields will be added to a message, 00740 setting this option to a larger value will result in a slight performance 00741 boost, 00742 since reallocation of the field array will occur less frequently. 00743 </p> 00744 <p> 00745 Similarly, 00746 if the number of fields to be added is small, 00747 setting this option to a smaller value will effect a small savings in memory 00748 usage (as well as reducing memory fragmentation). 00749 </p> 00750 </td> 00751 </tr> 00752 <tr> 00753 <th align="left"><tt>name_tree</tt></th> 00754 <td align="center"><tt>int</tt></td> 00755 <td align="center">1 (enable) or 0 (disable)</td> 00756 <td align="center">1</td> 00757 <td> 00758 In order to speed up access to fields by name, 00759 a tree of field names is maintained for each message. 00760 Maintenance of this tree 00761 (such as when fields are added or deleted) 00762 does incur some overhead. 00763 <p> 00764 In situations where fields are only added to a message 00765 (and not retrieved), 00766 this overhead can be eliminated by setting this option to <TT>0</TT>. 00767 Be aware, 00768 however, 00769 that retrieving a field by name from a message for which the name 00770 tree is disabled, 00771 will degenerate to using a linear search of the field array to 00772 locate the named field. 00773 This can incur much more overhead than was saved by not using 00774 the name tree. 00775 </p> 00776 <p> 00777 In addition, 00778 the use of the name tree allows SDM to detect 00779 (and prevent) 00780 the attempt to add two fields with the same name. 00781 Disabling the name tree also disables this safeguard. 00782 Further, 00783 any attempts to parse a message with duplicate field names using 00784 ::lbmsdm_msg_parse() or ::lbmsdm_msg_parse_ex() will fail 00785 and return an error. 00786 </p> 00787 </td> 00788 </tr> 00789 <tr> 00790 <th align="left"><tt>integer_index</tt></th> 00791 <td align="center"><tt>int</tt></td> 00792 <td align="center">1 (enable) or 0 (disable)</td> 00793 <td align="center">0</td> 00794 <td> 00795 Some optimizations can be done within SDM if it is known that each field 00796 name will be the string representation of a non-negative integer. 00797 Rather than looking up by name, 00798 each field name is used as the index of the field, 00799 and name lookups can be faster. 00800 <p> 00801 This option requires each field name to be a string representation of a 00802 non-negative integer. 00803 Any attempts to add a field or parse a message containing a field name which 00804 is not the string representation of a non-negative integer, 00805 when this option is set, 00806 will fail and return an error. 00807 </p> 00808 </td> 00809 </tr> 00810 </table> 00811 \par 00812 As an example, 00813 the following code fragment creates an attributes object, 00814 sets options, 00815 get the options, 00816 creates a message using the attributes object, 00817 then destroys the attributes object. 00818 For the sake of brevity, 00819 error checking has been omitted, 00820 as has the code to add fields to the message. 00821 \code 00822 lbmsdm_msg_attr_t * attr; 00823 lbmsdm_msg_t * msg; 00824 int name_tree; 00825 int alloc_size; 00826 char val_buf[256]; 00827 size_t val_len; 00828 00829 lbmsdm_msg_attr_create(&attr); 00830 00831 name_tree = 0; 00832 lbmsdm_msg_attr_setopt(attr, "name_tree", (void *)&name_tree, sizeof(name_tree)); 00833 lbmsdm_msg_attr_str_setopt(attr, "field_array_allocation", "128"); 00834 00835 val_len = sizeof(val_buf); 00836 lbmsdm_msg_attr_str_getopt(attr, "name_tree", val_buf, &val_len); 00837 printf("name_tree=%s\n", val_buf); 00838 val_len = sizeof(alloc_size); 00839 lbmsdm_msg_attr_getopt(attr, "field_array_allocation", (void *)&alloc_size, &val_len); 00840 printf("field_array_allocation=%d\n", alloc_size); 00841 00842 lbmsdm_msg_create_ex(&msg, attr); 00843 00844 lbmsdm_msg_attr_delete(attr); 00845 \endcode 00846 */ 00847 00848 #if !defined(LBMSDM_H_INCLUDED) 00849 #define LBMSDM_H_INCLUDED 00850 00851 #if defined(__cplusplus) 00852 extern "C" { 00853 #endif 00854 00855 #include <stdlib.h> 00856 #if defined(_WIN32) 00857 #include <windows.h> 00858 #include <winsock2.h> 00859 #if !defined(DONT_TYPEDEF_INT_T) 00860 typedef __int8 int8_t; 00861 typedef __int16 int16_t; 00862 typedef __int32 int32_t; 00863 typedef __int64 int64_t; 00864 #endif 00865 typedef unsigned __int8 uint8_t; 00866 typedef unsigned __int16 uint16_t; 00867 typedef unsigned __int32 uint32_t; 00868 typedef unsigned __int64 uint64_t; 00869 00870 /* C99 printf format macros missing from VC. */ 00871 #define PRId8 "d" 00872 #define PRId16 "d" 00873 #define PRId32 "d" 00874 #define PRId64 "I64d" 00875 #define PRIu8 "u" 00876 #define PRIu16 "u" 00877 #define PRIu32 "u" 00878 #define PRIu64 "I64u" 00879 #elif defined(__VMS) 00880 #include <inttypes.h> 00881 #define PRId8 "d" 00882 #define PRId16 "d" 00883 #define PRId32 "d" 00884 #define PRId64 "lld" 00885 #define PRIu8 "u" 00886 #define PRIu16 "u" 00887 #define PRIu32 "u" 00888 #define PRIu64 "llu" 00889 #else 00890 #include <inttypes.h> 00891 #include <sys/time.h> 00892 #endif 00893 00894 /* Directives to show how we treat exporting functions with Windows from the DLL */ 00895 #if defined(_WIN32) 00896 #if defined(_DLL) && defined(LBM_EXPORT_SYMS) 00897 #define LBMSDMExpDLL __declspec(dllexport) 00898 #elif defined(LBM_STATIC_LIB) 00899 #define LBMSDMExpDLL 00900 #else 00901 #define LBMSDMExpDLL __declspec(dllimport) 00902 #endif 00903 #elif defined(__TANDEM) 00904 #if defined(LBM_EXPORT_SYMS) 00905 #define LBMSDMExpDLL export$ 00906 #else 00907 #define LBMSDMExpDLL import$ 00908 #endif 00909 #else 00910 #define LBMSDMExpDLL 00911 #endif 00912 00913 /*! \brief Maximum length of a field name. 00914 */ 00915 #define LBMSDM_MAX_FIELD_NAME_LENGTH 255 00916 00917 struct lbmsdm_msg_attr_t_stct; 00918 /*! \brief Message attributes object for SDM (opaque). 00919 */ 00920 typedef struct lbmsdm_msg_attr_t_stct lbmsdm_msg_attr_t; 00921 00922 struct lbmsdm_msg_t_stct; 00923 /*! \brief Message object for SDM (opaque). 00924 */ 00925 typedef struct lbmsdm_msg_t_stct lbmsdm_msg_t; 00926 00927 /*! \brief Type definition for an SDM field type. 00928 */ 00929 typedef uint16_t lbmsdm_field_type_t; 00930 00931 struct lbmsdm_iter_t_stct; 00932 /*! \brief Message iterator object for SDM (opaque). 00933 */ 00934 typedef struct lbmsdm_iter_t_stct lbmsdm_iter_t; 00935 00936 #define LBMSDM_TYPE_MODIFIER_ARRAY 0x0100 00937 /*! \brief SDM field type definitions. 00938 */ 00939 enum 00940 { 00941 /*! SDM field type: Type is invalid. */ 00942 LBMSDM_TYPE_INVALID = 0, 00943 /*! SDM field type: Boolean (non-zero is true, zero is false). */ 00944 LBMSDM_TYPE_BOOLEAN = 1, 00945 /*! SDM field type: 8-bit signed integer. */ 00946 LBMSDM_TYPE_INT8 = 2, 00947 /*! SDM field type: 8-bit unsigned integer. */ 00948 LBMSDM_TYPE_UINT8 = 3, 00949 /*! SDM field type: 16-bit signed integer. */ 00950 LBMSDM_TYPE_INT16 = 4, 00951 /*! SDM field type: 16-bit unsigned integer. */ 00952 LBMSDM_TYPE_UINT16 = 5, 00953 /*! SDM field type: 32-bit signed integer. */ 00954 LBMSDM_TYPE_INT32 = 6, 00955 /*! SDM field type: 32-bit unsigned integer. */ 00956 LBMSDM_TYPE_UINT32 = 7, 00957 /*! SDM field type: 64-bit signed integer. */ 00958 LBMSDM_TYPE_INT64 = 8, 00959 /*! SDM field type: 64-bit unsigned integer. */ 00960 LBMSDM_TYPE_UINT64 = 9, 00961 /*! SDM field type: Single-precision floating point. */ 00962 LBMSDM_TYPE_FLOAT = 10, 00963 /*! SDM field type: Double-precision floating point. */ 00964 LBMSDM_TYPE_DOUBLE = 11, 00965 /*! SDM field type: Decimal number. */ 00966 LBMSDM_TYPE_DECIMAL = 12, 00967 /*! SDM field type: Seconds and microseconds since the epoch (UTC). */ 00968 LBMSDM_TYPE_TIMESTAMP = 13, 00969 /*! SDM field type: Nested SDM message. */ 00970 LBMSDM_TYPE_MESSAGE = 14, 00971 /*! SDM field type: Character string (ASCIZ). */ 00972 LBMSDM_TYPE_STRING = 15, 00973 /*! SDM field type: Unicode string. */ 00974 LBMSDM_TYPE_UNICODE = 16, 00975 /*! SDM field type: Binary Large Object (BLOB). */ 00976 LBMSDM_TYPE_BLOB = 17, 00977 /*! SDM field type: Array of Booleans (non-zero is true, zero is false). */ 00978 LBMSDM_TYPE_ARRAY_BOOLEAN = LBMSDM_TYPE_BOOLEAN | LBMSDM_TYPE_MODIFIER_ARRAY, 00979 /*! SDM field type: Array of 8-bit signed integers. */ 00980 LBMSDM_TYPE_ARRAY_INT8 = LBMSDM_TYPE_INT8 | LBMSDM_TYPE_MODIFIER_ARRAY, 00981 /*! SDM field type: Array of 8-bit unsigned integers. */ 00982 LBMSDM_TYPE_ARRAY_UINT8 = (LBMSDM_TYPE_UINT8 | LBMSDM_TYPE_MODIFIER_ARRAY), 00983 /*! SDM field type: Array of 16-bit signed integers. */ 00984 LBMSDM_TYPE_ARRAY_INT16 = (LBMSDM_TYPE_INT16 | LBMSDM_TYPE_MODIFIER_ARRAY), 00985 /*! SDM field type: Array of 16-bit unsigned integers. */ 00986 LBMSDM_TYPE_ARRAY_UINT16 = (LBMSDM_TYPE_UINT16 | LBMSDM_TYPE_MODIFIER_ARRAY), 00987 /*! SDM field type: Array of 32-bit signed integers. */ 00988 LBMSDM_TYPE_ARRAY_INT32 = (LBMSDM_TYPE_INT32 | LBMSDM_TYPE_MODIFIER_ARRAY), 00989 /*! SDM field type: Array of 32-bit unsigned integers. */ 00990 LBMSDM_TYPE_ARRAY_UINT32 = (LBMSDM_TYPE_UINT32 | LBMSDM_TYPE_MODIFIER_ARRAY), 00991 /*! SDM field type: Array of 64-bit signed integers. */ 00992 LBMSDM_TYPE_ARRAY_INT64 = (LBMSDM_TYPE_INT64 | LBMSDM_TYPE_MODIFIER_ARRAY), 00993 /*! SDM field type: Array of 64-bit unsigned integers. */ 00994 LBMSDM_TYPE_ARRAY_UINT64 = (LBMSDM_TYPE_UINT64 | LBMSDM_TYPE_MODIFIER_ARRAY), 00995 /*! SDM field type: Array of single-precision floating points. */ 00996 LBMSDM_TYPE_ARRAY_FLOAT = (LBMSDM_TYPE_FLOAT | LBMSDM_TYPE_MODIFIER_ARRAY), 00997 /*! SDM field type: Array of double-precision floating points. */ 00998 LBMSDM_TYPE_ARRAY_DOUBLE = (LBMSDM_TYPE_DOUBLE | LBMSDM_TYPE_MODIFIER_ARRAY), 00999 /*! SDM field type: Array of decimal numbers. */ 01000 LBMSDM_TYPE_ARRAY_DECIMAL = (LBMSDM_TYPE_DECIMAL | LBMSDM_TYPE_MODIFIER_ARRAY), 01001 /*! SDM field type: Array of timestamps (seconds and microseconds since the epoch (UTC)). */ 01002 LBMSDM_TYPE_ARRAY_TIMESTAMP = (LBMSDM_TYPE_TIMESTAMP | LBMSDM_TYPE_MODIFIER_ARRAY), 01003 /*! SDM field type: Array of nested SDM messages. */ 01004 LBMSDM_TYPE_ARRAY_MESSAGE = (LBMSDM_TYPE_MESSAGE | LBMSDM_TYPE_MODIFIER_ARRAY), 01005 /*! SDM field type: Array of character strings (ASCIZ). */ 01006 LBMSDM_TYPE_ARRAY_STRING = (LBMSDM_TYPE_STRING | LBMSDM_TYPE_MODIFIER_ARRAY), 01007 /*! SDM field type: Array of unicode strings. */ 01008 LBMSDM_TYPE_ARRAY_UNICODE = (LBMSDM_TYPE_UNICODE | LBMSDM_TYPE_MODIFIER_ARRAY), 01009 /*! SDM field type: Array of Binary Large Objects (BLOB). */ 01010 LBMSDM_TYPE_ARRAY_BLOB = (LBMSDM_TYPE_BLOB | LBMSDM_TYPE_MODIFIER_ARRAY) 01011 }; 01012 01013 /*! \brief SDM API function return codes. 01014 */ 01015 enum 01016 { 01017 /*! SDM return code: Operation was successful. */ 01018 LBMSDM_SUCCESS = 0, 01019 /*! SDM return code: Operation failed. See ::lbmsdm_errnum() or ::lbmsdm_errmsg() for the reason. */ 01020 LBMSDM_FAILURE = -1, 01021 /*! SDM return code: Field is null. */ 01022 LBMSDM_FIELD_IS_NULL = 1, 01023 /*! SDM return code: No more fields to iterate over. */ 01024 LBMSDM_NO_MORE_FIELDS = 2, 01025 /*! SDM return code: Insufficient buffer length given. */ 01026 LBMSDM_INSUFFICIENT_BUFFER_LENGTH = 3 01027 }; 01028 01029 /*! \brief SDM error codes. 01030 */ 01031 enum 01032 { 01033 /*! SDM error code: An invalid argument was passed. */ 01034 LBMSDM_ERR_EINVAL = 1, 01035 /*! SDM error code: Operation could not be completed due to memory allocation error. */ 01036 LBMSDM_ERR_ENOMEM, 01037 /*! SDM error code: Field name is too long. */ 01038 LBMSDM_ERR_NAMETOOLONG, 01039 /*! SDM error code: The field being added to the message already exists. */ 01040 LBMSDM_ERR_DUPLICATE_FIELD, 01041 /*! SDM error code: Invalid type. */ 01042 LBMSDM_ERR_BAD_TYPE, 01043 /*! SDM error code: The field does not exist in the message. */ 01044 LBMSDM_ERR_FIELD_NOT_FOUND, 01045 /*! SDM error code: The message is in an invalid form. */ 01046 LBMSDM_ERR_MSG_INVALID, 01047 /*! SDM error code: The field can not be converted as requested. */ 01048 LBMSDM_ERR_CANNOT_CONVERT, 01049 /*! SDM error code: The field is not an array field. */ 01050 LBMSDM_ERR_NOT_ARRAY, 01051 /*! SDM error code: The field is not a scalar field. */ 01052 LBMSDM_ERR_NOT_SCALAR, 01053 /*! SDM error code: The specified array element does not exist. */ 01054 LBMSDM_ERR_ELEMENT_NOT_FOUND, 01055 /*! SDM error code: The specified type is not supported. */ 01056 LBMSDM_ERR_TYPE_NOT_SUPPORTED, 01057 /*! SDM error code: Type mismatch. */ 01058 LBMSDM_ERR_TYPE_MISMATCH, 01059 /*! SDM error code: Unicode conversion error. */ 01060 LBMSDM_ERR_UNICODE_CONVERSION, 01061 /*! SDM error code: Field is null. */ 01062 LBMSDM_ERR_FIELD_IS_NULL, 01063 /*! SDM error code: Unable to add field. */ 01064 LBMSDM_ERR_ADDING_FIELD, 01065 /*! SDM error code: Iterator doesn't reference a valid field. */ 01066 LBMSDM_ERR_ITERATOR_INVALID, 01067 /*! SDM error code: Error deleting a field. */ 01068 LBMSDM_ERR_DELETING_FIELD, 01069 /*! SDM error code: Invalid field name. */ 01070 LBMSDM_ERR_INVALID_FIELD_NAME 01071 }; 01072 01073 /*! \brief Structure to hold a scaled decimal number. 01074 A scaled decimal number consists of a mantissa \f$m\f$ and an exponent \f$exp\f$. 01075 It represents the value \f$m\cdot 10^{exp}\f$. 01076 01077 The mantissa is represented as a 64-bit signed integer. 01078 The exponent is represented as an 8-bit signed integer, 01079 and can range from -128 to 127. 01080 */ 01081 typedef struct lbmsdm_decimal_t_stct 01082 { 01083 /*! Mantissa. */ 01084 int64_t mant; 01085 /*! Exponent. */ 01086 int8_t exp; 01087 } lbmsdm_decimal_t; 01088 01089 /*! \brief Return the error number last encountered by this thread. 01090 \return Integer error number (see LBMSDM_ERROR_*). 01091 */ 01092 LBMSDMExpDLL int lbmsdm_errnum(void); 01093 01094 /*! \brief Return an ASCII string containing the error message last encountered 01095 by this thread. 01096 \return Pointer to a static char array containing the error message. 01097 */ 01098 LBMSDMExpDLL const char * lbmsdm_errmsg(void); 01099 01100 #if defined(_WIN32) || defined(DOXYGEN) 01101 /*! \brief Perform required initialization under Windows. 01102 This function needs to be called before any other LBM SDM API function, 01103 but only when using the static version of the LBM SDM library on Windows. 01104 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01105 */ 01106 LBMSDMExpDLL int lbmsdm_win32_static_init(void); 01107 #endif 01108 01109 /*! \brief Create an SDM message to be filled in and sent. 01110 \param Message A pointer to a pointer to an SDM message object. 01111 Will be filled in by this function to point to the newly created 01112 ::lbmsdm_msg_t object. 01113 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01114 */ 01115 LBMSDMExpDLL int lbmsdm_msg_create(lbmsdm_msg_t * * Message); 01116 01117 /*! \brief Create an SDM message to be filled in and sent, with options. 01118 \param Message A pointer to a pointer to an SDM message object. 01119 Will be filled in by this function to point to the newly created 01120 ::lbmsdm_msg_t object. 01121 \param Attributes A pointer to an ::lbmsdm_msg_attr_t structure used to initialize 01122 the message options. 01123 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01124 */ 01125 LBMSDMExpDLL int lbmsdm_msg_create_ex(lbmsdm_msg_t * * Message, const lbmsdm_msg_attr_t * Attributes); 01126 01127 /*! \brief Create an SDM message to be parsed and processed from an existing buffer. 01128 \param Message A pointer to a pointer to an SDM message object. 01129 Will be filled in by this function to point to the newly created 01130 ::lbmsdm_msg_t object. 01131 \param Data A pointer to the buffer from which the message should be constructed. 01132 \param Length Length of \a Data. 01133 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01134 */ 01135 LBMSDMExpDLL int lbmsdm_msg_parse(lbmsdm_msg_t * * Message, const char * Data, size_t Length); 01136 01137 /*! \brief Create an SDM message to be parsed and processed from an existing buffer, with options. 01138 \param Message A pointer to a pointer to an SDM message object. 01139 Will be filled in by this function to point to the newly created 01140 ::lbmsdm_msg_t object. 01141 \param Data A pointer to the buffer from which the message should be constructed. 01142 \param Length Length of \a Data. 01143 \param Attributes A pointer to an ::lbmsdm_msg_attr_t structure used to initialize 01144 the message options. 01145 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01146 */ 01147 LBMSDMExpDLL int lbmsdm_msg_parse_ex(lbmsdm_msg_t * * Message, const char * Data, size_t Length, const lbmsdm_msg_attr_t * Attributes); 01148 01149 /*! \brief Create an SDM message to be parsed and processed from an existing buffer, using 01150 an already-existing ::lbmsdm_msg_t structure. 01151 \param Message A pointer to an existing SDM message object, 01152 into which the message buffer is parsed. 01153 The message will be cleared before parsing. 01154 \param Data A pointer to the buffer from which the message should be constructed. 01155 \param Length Length of \a Data. 01156 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01157 */ 01158 LBMSDMExpDLL int lbmsdm_msg_parse_reuse(lbmsdm_msg_t * Message, const char * Data, size_t Length); 01159 01160 /*! \brief Clone an existing SDM message. 01161 \param Message A pointer to a pointer to an SDM message object. 01162 Will be filled in by this function to point to the newly created 01163 ::lbmsdm_msg_t object. 01164 \param Original The SDM message to be cloned. 01165 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01166 */ 01167 LBMSDMExpDLL int lbmsdm_msg_clone(lbmsdm_msg_t * * Message, const lbmsdm_msg_t * Original); 01168 01169 /*! \brief Clear an SDM message, deleting all fields in the message. 01170 \param Message The SDM message to clear. 01171 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01172 */ 01173 LBMSDMExpDLL int lbmsdm_msg_clear(lbmsdm_msg_t * Message); 01174 01175 /*! \brief Destroy an SDM message object. 01176 \param Message The SDM message to destroy. 01177 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01178 */ 01179 LBMSDMExpDLL int lbmsdm_msg_destroy(lbmsdm_msg_t * Message); 01180 01181 /*! \brief Dump a message into a printable string. 01182 \param Message The SDM message to dump. 01183 \param Buffer Buffer into which to dump the message. 01184 \param Size Maximum size of \a Buffer. 01185 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01186 \note \a Buffer will be null-terminated. If \a Buffer isn't large enough to contain 01187 the entire message, it will be truncated to fit the available space. 01188 The values for unicode and BLOB fields will not formatted. 01189 */ 01190 LBMSDMExpDLL int lbmsdm_msg_dump(lbmsdm_msg_t * Message, char * Buffer, size_t Size); 01191 01192 /*! \defgroup add Add a field to a message 01193 The functions in this group allow scalar (non-array) fields to be added to a message. 01194 The field value is also specified. 01195 */ 01196 /*! \brief Add a field to a message. 01197 \ingroup add 01198 \param Message The SDM message to which the field is to be added. 01199 \param Name Name of the field to be added. 01200 \param Value Value of the field to be added. 01201 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01202 */ 01203 LBMSDMExpDLL int lbmsdm_msg_add_boolean(lbmsdm_msg_t * Message, const char * Name, uint8_t Value); 01204 01205 /*! \ingroup add 01206 \overload 01207 */ 01208 LBMSDMExpDLL int lbmsdm_msg_add_int8(lbmsdm_msg_t * Message, const char * Name, int8_t Value); 01209 01210 /*! \ingroup add 01211 \overload 01212 */ 01213 LBMSDMExpDLL int lbmsdm_msg_add_uint8(lbmsdm_msg_t * Message, const char * Name, uint8_t Value); 01214 01215 /*! \ingroup add 01216 \overload 01217 */ 01218 LBMSDMExpDLL int lbmsdm_msg_add_int16(lbmsdm_msg_t * Message, const char * Name, int16_t Value); 01219 01220 /*! \ingroup add 01221 \overload 01222 */ 01223 LBMSDMExpDLL int lbmsdm_msg_add_uint16(lbmsdm_msg_t * Message, const char * Name, uint16_t Value); 01224 01225 /*! \ingroup add 01226 \overload 01227 */ 01228 LBMSDMExpDLL int lbmsdm_msg_add_int32(lbmsdm_msg_t * Message, const char * Name, int32_t Value); 01229 01230 /*! \ingroup add 01231 \overload 01232 */ 01233 LBMSDMExpDLL int lbmsdm_msg_add_uint32(lbmsdm_msg_t * Message, const char * Name, uint32_t Value); 01234 01235 /*! \ingroup add 01236 \overload 01237 */ 01238 LBMSDMExpDLL int lbmsdm_msg_add_int64(lbmsdm_msg_t * Message, const char * Name, int64_t Value); 01239 01240 /*! \ingroup add 01241 \overload 01242 */ 01243 LBMSDMExpDLL int lbmsdm_msg_add_uint64(lbmsdm_msg_t * Message, const char * Name, uint64_t Value); 01244 01245 /*! \ingroup add 01246 \overload 01247 */ 01248 LBMSDMExpDLL int lbmsdm_msg_add_float(lbmsdm_msg_t * Message, const char * Name, float Value); 01249 01250 /*! \ingroup add 01251 \overload 01252 */ 01253 LBMSDMExpDLL int lbmsdm_msg_add_double(lbmsdm_msg_t * Message, const char * Name, double Value); 01254 01255 /*! \ingroup add 01256 \overload 01257 */ 01258 LBMSDMExpDLL int lbmsdm_msg_add_decimal(lbmsdm_msg_t * Message, const char * Name, const lbmsdm_decimal_t * Value); 01259 01260 /*! \ingroup add 01261 \overload 01262 */ 01263 LBMSDMExpDLL int lbmsdm_msg_add_timestamp(lbmsdm_msg_t * Message, const char * Name, const struct timeval * Value); 01264 01265 /*! \ingroup add 01266 \overload 01267 */ 01268 LBMSDMExpDLL int lbmsdm_msg_add_message(lbmsdm_msg_t * Message, const char * Name, const lbmsdm_msg_t * Value); 01269 01270 /*! \ingroup add 01271 \overload 01272 */ 01273 LBMSDMExpDLL int lbmsdm_msg_add_string(lbmsdm_msg_t * Message, const char * Name, const char * Value); 01274 01275 /*! \brief Add a unicode field to a message. 01276 \ingroup add 01277 \param Message The SDM message to which the field is to be added. 01278 \param Name Name of the field to be added. 01279 \param Value Value of the field to be added. 01280 \param Length Length of the unicode string, in <tt>wchar_t</tt>s. 01281 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01282 */ 01283 LBMSDMExpDLL int lbmsdm_msg_add_unicode(lbmsdm_msg_t * Message, const char * Name, const wchar_t * Value, size_t Length); 01284 01285 /*! \brief Add a BLOB field to a message. 01286 \ingroup add 01287 \param Message The SDM message to which the field is to be added. 01288 \param Name Name of the field to be added. 01289 \param Value Value of the field to be added. 01290 \param Length Length of the data, in bytes. 01291 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01292 */ 01293 LBMSDMExpDLL int lbmsdm_msg_add_blob(lbmsdm_msg_t * Message, const char * Name, const void * Value, size_t Length); 01294 01295 /*! \defgroup add_array Add an array field to a message 01296 The functions in this group allow array fields to be added to a message. 01297 */ 01298 /*! \brief Add an array field to a message. 01299 \ingroup add_array 01300 \param Message The SDM message to which the field is to be added. 01301 \param Name Name of the field to be added. 01302 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01303 */ 01304 LBMSDMExpDLL int lbmsdm_msg_add_boolean_array(lbmsdm_msg_t * Message, const char * Name); 01305 01306 /*! \ingroup add_array 01307 \overload 01308 */ 01309 LBMSDMExpDLL int lbmsdm_msg_add_int8_array(lbmsdm_msg_t * Message, const char * Name); 01310 01311 /*! \ingroup add_array 01312 \overload 01313 */ 01314 LBMSDMExpDLL int lbmsdm_msg_add_uint8_array(lbmsdm_msg_t * Message, const char * Name); 01315 01316 /*! \ingroup add_array 01317 \overload 01318 */ 01319 LBMSDMExpDLL int lbmsdm_msg_add_int16_array(lbmsdm_msg_t * Message, const char * Name); 01320 01321 /*! \ingroup add_array 01322 \overload 01323 */ 01324 LBMSDMExpDLL int lbmsdm_msg_add_uint16_array(lbmsdm_msg_t * Message, const char * Name); 01325 01326 /*! \ingroup add_array 01327 \overload 01328 */ 01329 LBMSDMExpDLL int lbmsdm_msg_add_int32_array(lbmsdm_msg_t * Message, const char * Name); 01330 01331 /*! \ingroup add_array 01332 \overload 01333 */ 01334 LBMSDMExpDLL int lbmsdm_msg_add_uint32_array(lbmsdm_msg_t * Message, const char * Name); 01335 01336 /*! \ingroup add_array 01337 \overload 01338 */ 01339 LBMSDMExpDLL int lbmsdm_msg_add_int64_array(lbmsdm_msg_t * Message, const char * Name); 01340 01341 /*! \ingroup add_array 01342 \overload 01343 */ 01344 LBMSDMExpDLL int lbmsdm_msg_add_uint64_array(lbmsdm_msg_t * Message, const char * Name); 01345 01346 /*! \ingroup add_array 01347 \overload 01348 */ 01349 LBMSDMExpDLL int lbmsdm_msg_add_float_array(lbmsdm_msg_t * Message, const char * Name); 01350 01351 /*! \ingroup add_array 01352 \overload 01353 */ 01354 LBMSDMExpDLL int lbmsdm_msg_add_double_array(lbmsdm_msg_t * Message, const char * Name); 01355 01356 /*! \ingroup add_array 01357 \overload 01358 */ 01359 LBMSDMExpDLL int lbmsdm_msg_add_decimal_array(lbmsdm_msg_t * Message, const char * Name); 01360 01361 /*! \ingroup add_array 01362 \overload 01363 */ 01364 LBMSDMExpDLL int lbmsdm_msg_add_timestamp_array(lbmsdm_msg_t * Message, const char * Name); 01365 01366 /*! \ingroup add_array 01367 \overload 01368 */ 01369 LBMSDMExpDLL int lbmsdm_msg_add_message_array(lbmsdm_msg_t * Message, const char * Name); 01370 01371 /*! \ingroup add_array 01372 \overload 01373 */ 01374 LBMSDMExpDLL int lbmsdm_msg_add_string_array(lbmsdm_msg_t * Message, const char * Name); 01375 01376 /*! \ingroup add_array 01377 \overload 01378 */ 01379 LBMSDMExpDLL int lbmsdm_msg_add_unicode_array(lbmsdm_msg_t * Message, const char * Name); 01380 01381 /*! \ingroup add_array 01382 \overload 01383 */ 01384 LBMSDMExpDLL int lbmsdm_msg_add_blob_array(lbmsdm_msg_t * Message, const char * Name); 01385 01386 /*! \defgroup add_elem_idx Add an element to an array field by field index 01387 The functions in this group allow an element to be added to an array field 01388 referenced by field index. 01389 */ 01390 /*! \brief Set the value of an array field element in a message by field index. 01391 \ingroup add_elem_idx 01392 \param Message The SDM message containing the field. 01393 \param Index Field index. 01394 \param Value Element value. 01395 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01396 */ 01397 LBMSDMExpDLL int lbmsdm_msg_add_boolean_elem_idx(lbmsdm_msg_t * Message, size_t Index, uint8_t Value); 01398 01399 /*! \ingroup add_elem_idx 01400 \overload 01401 */ 01402 LBMSDMExpDLL int lbmsdm_msg_add_int8_elem_idx(lbmsdm_msg_t * Message, size_t Index, int8_t Value); 01403 01404 /*! \ingroup add_elem_idx 01405 \overload 01406 */ 01407 LBMSDMExpDLL int lbmsdm_msg_add_uint8_elem_idx(lbmsdm_msg_t * Message, size_t Index, uint8_t Value); 01408 01409 /*! \ingroup add_elem_idx 01410 \overload 01411 */ 01412 LBMSDMExpDLL int lbmsdm_msg_add_int16_elem_idx(lbmsdm_msg_t * Message, size_t Index, int16_t Value); 01413 01414 /*! \ingroup add_elem_idx 01415 \overload 01416 */ 01417 LBMSDMExpDLL int lbmsdm_msg_add_uint16_elem_idx(lbmsdm_msg_t * Message, size_t Index, uint16_t Value); 01418 01419 /*! \ingroup add_elem_idx 01420 \overload 01421 */ 01422 LBMSDMExpDLL int lbmsdm_msg_add_int32_elem_idx(lbmsdm_msg_t * Message, size_t Index, int32_t Value); 01423 01424 /*! \ingroup add_elem_idx 01425 \overload 01426 */ 01427 LBMSDMExpDLL int lbmsdm_msg_add_uint32_elem_idx(lbmsdm_msg_t * Message, size_t Index, uint32_t Value); 01428 01429 /*! \ingroup add_elem_idx 01430 \overload 01431 */ 01432 LBMSDMExpDLL int lbmsdm_msg_add_int64_elem_idx(lbmsdm_msg_t * Message, size_t Index, int64_t Value); 01433 01434 /*! \ingroup add_elem_idx 01435 \overload 01436 */ 01437 LBMSDMExpDLL int lbmsdm_msg_add_uint64_elem_idx(lbmsdm_msg_t * Message, size_t Index, uint64_t Value); 01438 01439 /*! \ingroup add_elem_idx 01440 \overload 01441 */ 01442 LBMSDMExpDLL int lbmsdm_msg_add_float_elem_idx(lbmsdm_msg_t * Message, size_t Index, float Value); 01443 01444 /*! \ingroup add_elem_idx 01445 \overload 01446 */ 01447 LBMSDMExpDLL int lbmsdm_msg_add_double_elem_idx(lbmsdm_msg_t * Message, size_t Index, double Value); 01448 01449 /*! \ingroup add_elem_idx 01450 \overload 01451 */ 01452 LBMSDMExpDLL int lbmsdm_msg_add_decimal_elem_idx(lbmsdm_msg_t * Message, size_t Index, const lbmsdm_decimal_t * Value); 01453 01454 /*! \ingroup add_elem_idx 01455 \overload 01456 */ 01457 LBMSDMExpDLL int lbmsdm_msg_add_timestamp_elem_idx(lbmsdm_msg_t * Message, size_t Index, const struct timeval * Value); 01458 01459 /*! \ingroup add_elem_idx 01460 \overload 01461 */ 01462 LBMSDMExpDLL int lbmsdm_msg_add_message_elem_idx(lbmsdm_msg_t * Message, size_t Index, const lbmsdm_msg_t * Value); 01463 01464 /*! \ingroup add_elem_idx 01465 \overload 01466 */ 01467 LBMSDMExpDLL int lbmsdm_msg_add_string_elem_idx(lbmsdm_msg_t * Message, size_t Index, const char * Value); 01468 01469 /*! \brief Set the value of a unicode array field element in a message by field index. 01470 \ingroup add_elem_idx 01471 \param Message The SDM message containing the field. 01472 \param Index Field index. 01473 \param Value Element value. 01474 \param Length Length of the unicode string, in <tt>wchar_t</tt>s. 01475 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01476 */ 01477 LBMSDMExpDLL int lbmsdm_msg_add_unicode_elem_idx(lbmsdm_msg_t * Message, size_t Index, const wchar_t * Value, size_t Length); 01478 01479 /*! \brief Set the value of a blob array field element in a message by field index. 01480 \ingroup add_elem_idx 01481 \param Message The SDM message containing the field. 01482 \param Index Field index. 01483 \param Value Element value. 01484 \param Length Length of the BLOB value, in bytes. 01485 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01486 */ 01487 LBMSDMExpDLL int lbmsdm_msg_add_blob_elem_idx(lbmsdm_msg_t * Message, size_t Index, const void * Value, size_t Length); 01488 01489 /*! \defgroup add_elem_name Add an element to an array field by field name 01490 The functions in this group allow an element to be added to an array field 01491 referenced by field name. 01492 */ 01493 /*! \brief Add an array field element in a message by field name. 01494 \ingroup add_elem_name 01495 \param Message The SDM message containing the field. 01496 \param Name Field name. 01497 \param Value Element value. 01498 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01499 */ 01500 LBMSDMExpDLL int lbmsdm_msg_add_boolean_elem_name(lbmsdm_msg_t * Message, const char * Name, uint8_t Value); 01501 01502 /*! \ingroup add_elem_name 01503 \overload 01504 */ 01505 LBMSDMExpDLL int lbmsdm_msg_add_int8_elem_name(lbmsdm_msg_t * Message, const char * Name, int8_t Value); 01506 01507 /*! \ingroup add_elem_name 01508 \overload 01509 */ 01510 LBMSDMExpDLL int lbmsdm_msg_add_uint8_elem_name(lbmsdm_msg_t * Message, const char * Name, uint8_t Value); 01511 01512 /*! \ingroup add_elem_name 01513 \overload 01514 */ 01515 LBMSDMExpDLL int lbmsdm_msg_add_int16_elem_name(lbmsdm_msg_t * Message, const char * Name, int16_t Value); 01516 01517 /*! \ingroup add_elem_name 01518 \overload 01519 */ 01520 LBMSDMExpDLL int lbmsdm_msg_add_uint16_elem_name(lbmsdm_msg_t * Message, const char * Name, uint16_t Value); 01521 01522 /*! \ingroup add_elem_name 01523 \overload 01524 */ 01525 LBMSDMExpDLL int lbmsdm_msg_add_int32_elem_name(lbmsdm_msg_t * Message, const char * Name, int32_t Value); 01526 01527 /*! \ingroup add_elem_name 01528 \overload 01529 */ 01530 LBMSDMExpDLL int lbmsdm_msg_add_uint32_elem_name(lbmsdm_msg_t * Message, const char * Name, uint32_t Value); 01531 01532 /*! \ingroup add_elem_name 01533 \overload 01534 */ 01535 LBMSDMExpDLL int lbmsdm_msg_add_int64_elem_name(lbmsdm_msg_t * Message, const char * Name, int64_t Value); 01536 01537 /*! \ingroup add_elem_name 01538 \overload 01539 */ 01540 LBMSDMExpDLL int lbmsdm_msg_add_uint64_elem_name(lbmsdm_msg_t * Message, const char * Name, uint64_t Value); 01541 01542 /*! \ingroup add_elem_name 01543 \overload 01544 */ 01545 LBMSDMExpDLL int lbmsdm_msg_add_float_elem_name(lbmsdm_msg_t * Message, const char * Name, float Value); 01546 01547 /*! \ingroup add_elem_name 01548 \overload 01549 */ 01550 LBMSDMExpDLL int lbmsdm_msg_add_double_elem_name(lbmsdm_msg_t * Message, const char * Name, double Value); 01551 01552 /*! \ingroup add_elem_name 01553 \overload 01554 */ 01555 LBMSDMExpDLL int lbmsdm_msg_add_decimal_elem_name(lbmsdm_msg_t * Message, const char * Name, const lbmsdm_decimal_t * Value); 01556 01557 /*! \ingroup add_elem_name 01558 \overload 01559 */ 01560 LBMSDMExpDLL int lbmsdm_msg_add_timestamp_elem_name(lbmsdm_msg_t * Message, const char * Name, const struct timeval * Value); 01561 01562 /*! \ingroup add_elem_name 01563 \overload 01564 */ 01565 LBMSDMExpDLL int lbmsdm_msg_add_message_elem_name(lbmsdm_msg_t * Message, const char * Name, const lbmsdm_msg_t * Value); 01566 01567 /*! \ingroup add_elem_name 01568 \overload 01569 */ 01570 LBMSDMExpDLL int lbmsdm_msg_add_string_elem_name(lbmsdm_msg_t * Message, const char * Name, const char * Value); 01571 01572 /*! \brief Add a unicode array field element in a message by field name. 01573 \ingroup add_elem_name 01574 \param Message The SDM message containing the field. 01575 \param Name Field name. 01576 \param Value Element value. 01577 \param Length Length of the unicode string, in <tt>wchar_t</tt>s. 01578 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01579 */ 01580 LBMSDMExpDLL int lbmsdm_msg_add_unicode_elem_name(lbmsdm_msg_t * Message, const char * Name, const wchar_t * Value, size_t Length); 01581 01582 /*! \brief Add a BLOB array field element in a message by field name. 01583 \ingroup add_elem_name 01584 \param Message The SDM message containing the field. 01585 \param Name Field name. 01586 \param Value Element value. 01587 \param Length Length of the BLOB data, in bytes. 01588 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01589 */ 01590 LBMSDMExpDLL int lbmsdm_msg_add_blob_elem_name(lbmsdm_msg_t * Message, const char * Name, const void * Value, size_t Length); 01591 01592 /*! \defgroup add_elem_iter Add an element to an array field referenced by an iterator 01593 The functions in this group allow an element to be added to an array field 01594 referenced by an iterator. 01595 */ 01596 /*! \brief Add an array field element in a message referenced by an iterator. 01597 \ingroup add_elem_iter 01598 \param Iterator The iterator referencing the field. 01599 \param Value Element value. 01600 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01601 */ 01602 LBMSDMExpDLL int lbmsdm_iter_add_boolean_elem(lbmsdm_iter_t * Iterator, uint8_t Value); 01603 01604 /*! \ingroup add_elem_iter 01605 \overload 01606 */ 01607 LBMSDMExpDLL int lbmsdm_iter_add_int8_elem(lbmsdm_iter_t * Iterator, int8_t Value); 01608 01609 /*! \ingroup add_elem_iter 01610 \overload 01611 */ 01612 LBMSDMExpDLL int lbmsdm_iter_add_uint8_elem(lbmsdm_iter_t * Iterator, uint8_t Value); 01613 01614 /*! \ingroup add_elem_iter 01615 \overload 01616 */ 01617 LBMSDMExpDLL int lbmsdm_iter_add_int16_elem(lbmsdm_iter_t * Iterator, int16_t Value); 01618 01619 /*! \ingroup add_elem_iter 01620 \overload 01621 */ 01622 LBMSDMExpDLL int lbmsdm_iter_add_uint16_elem(lbmsdm_iter_t * Iterator, uint16_t Value); 01623 01624 /*! \ingroup add_elem_iter 01625 \overload 01626 */ 01627 LBMSDMExpDLL int lbmsdm_iter_add_int32_elem(lbmsdm_iter_t * Iterator, int32_t Value); 01628 01629 /*! \ingroup add_elem_iter 01630 \overload 01631 */ 01632 LBMSDMExpDLL int lbmsdm_iter_add_uint32_elem(lbmsdm_iter_t * Iterator, uint32_t Value); 01633 01634 /*! \ingroup add_elem_iter 01635 \overload 01636 */ 01637 LBMSDMExpDLL int lbmsdm_iter_add_int64_elem(lbmsdm_iter_t * Iterator, int64_t Value); 01638 01639 /*! \ingroup add_elem_iter 01640 \overload 01641 */ 01642 LBMSDMExpDLL int lbmsdm_iter_add_uint64_elem(lbmsdm_iter_t * Iterator, uint64_t Value); 01643 01644 /*! \ingroup add_elem_iter 01645 \overload 01646 */ 01647 LBMSDMExpDLL int lbmsdm_iter_add_float_elem(lbmsdm_iter_t * Iterator, float Value); 01648 01649 /*! \ingroup add_elem_iter 01650 \overload 01651 */ 01652 LBMSDMExpDLL int lbmsdm_iter_add_double_elem(lbmsdm_iter_t * Iterator, double Value); 01653 01654 /*! \ingroup add_elem_iter 01655 \overload 01656 */ 01657 LBMSDMExpDLL int lbmsdm_iter_add_decimal_elem(lbmsdm_iter_t * Iterator, const lbmsdm_decimal_t * Value); 01658 01659 /*! \ingroup add_elem_iter 01660 \overload 01661 */ 01662 LBMSDMExpDLL int lbmsdm_iter_add_timestamp_elem(lbmsdm_iter_t * Iterator, const struct timeval * Value); 01663 01664 /*! \ingroup add_elem_iter 01665 \overload 01666 */ 01667 LBMSDMExpDLL int lbmsdm_iter_add_message_elem(lbmsdm_iter_t * Iterator, const lbmsdm_msg_t * Value); 01668 01669 /*! \ingroup add_elem_iter 01670 \overload 01671 */ 01672 LBMSDMExpDLL int lbmsdm_iter_add_string_elem(lbmsdm_iter_t * Iterator, const char * Value); 01673 01674 /*! \brief Add a unicode array field element in a message referenced by an iterator. 01675 \ingroup add_elem_iter 01676 \param Iterator The iterator referencing the field. 01677 \param Value Element value. 01678 \param Length Length of the unicode string, in <tt>wchar_t</tt>s. 01679 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01680 */ 01681 LBMSDMExpDLL int lbmsdm_iter_add_unicode_elem(lbmsdm_iter_t * Iterator, const wchar_t * Value, size_t Length); 01682 01683 /*! \brief Add a BLOB array field element in a message referenced by an iterator. 01684 \ingroup add_elem_iter 01685 \param Iterator The iterator referencing the field. 01686 \param Value Element value. 01687 \param Length Length of the BLOB data, in bytes. 01688 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01689 */ 01690 LBMSDMExpDLL int lbmsdm_iter_add_blob_elem(lbmsdm_iter_t * Iterator, const void * Value, size_t Length); 01691 01692 /*! \brief Get the data buffer for a constructed message, 01693 after all fields have been added to the message. 01694 \param Message The SDM message. 01695 \return A pointer to the data buffer, 01696 or \c NULL if any error occurs. 01697 \note The pointer returned by ::lbmsdm_msg_get_data is invalidated when the message is deleted 01698 (via ::lbmsdm_msg_destroy), any field is added to the message, 01699 any field is deleted from the message, or any field in the message is changed 01700 (either the field value or type). 01701 In other words, any time the message is changed, the pointer returned is no longer valid. 01702 */ 01703 LBMSDMExpDLL const char * lbmsdm_msg_get_data(lbmsdm_msg_t * Message); 01704 01705 /*! \brief Get the length of the data buffer for a constructed message, 01706 after all fields have been added to the message. 01707 \param Message The SDM message. 01708 \return The length of the data buffer, 01709 or 0 if any error occurs. 01710 */ 01711 LBMSDMExpDLL size_t lbmsdm_msg_get_datalen(lbmsdm_msg_t * Message); 01712 01713 /*! \brief Get the number of fields in a message. 01714 \param Message The SDM message. 01715 \return The number of fields in the message, or -1 if an error occurs. 01716 \note Only top-level fields are counted. If a message field exists within the message, 01717 the number of fields in the contained message are not counted. Instead, the message 01718 field counts as one field. Likewise, array fields contribute only 1 to the field count, 01719 not the number of elements in the field. 01720 */ 01721 LBMSDMExpDLL int lbmsdm_msg_get_fldcnt(lbmsdm_msg_t * Message); 01722 01723 /*! \brief Create an SDM message iterator. 01724 \param Iterator A pointer to a pointer to an SDM iterator object. 01725 Will be filled in by this function to point to the newly created 01726 ::lbmsdm_iter_t object. 01727 \param Message SDM message on which the iterator is to operate. 01728 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01729 */ 01730 LBMSDMExpDLL int lbmsdm_iter_create(lbmsdm_iter_t * * Iterator, lbmsdm_msg_t * Message); 01731 01732 /*! \brief Destroy an SDM message iterator. 01733 \param Iterator The ::lbmsdm_iter_t object to destroy. 01734 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01735 */ 01736 LBMSDMExpDLL int lbmsdm_iter_destroy(lbmsdm_iter_t * Iterator); 01737 01738 /*! \brief Position an iterator to the first field in the message. 01739 \param Iterator The iterator to position. 01740 \retval ::LBMSDM_SUCCESS if successful 01741 \retval ::LBMSDM_NO_MORE_FIELDS if no fields exist in the message 01742 \retval ::LBMSDM_FAILURE if the operation failed 01743 */ 01744 LBMSDMExpDLL int lbmsdm_iter_first(lbmsdm_iter_t * Iterator); 01745 01746 /*! \brief Position an iterator to the next field in the message. 01747 \param Iterator The iterator to position. 01748 \retval ::LBMSDM_SUCCESS if successful 01749 \retval ::LBMSDM_NO_MORE_FIELDS if no fields exist in the message 01750 \retval ::LBMSDM_FAILURE if the operation failed 01751 */ 01752 LBMSDMExpDLL int lbmsdm_iter_next(lbmsdm_iter_t * Iterator); 01753 01754 /*! \brief Get the name of a field in a message by field index. 01755 \param Message The SDM message from which the field name is to be fetched. 01756 \param Index Field index. 01757 \return The field name, or \c NULL if an error occurred. 01758 */ 01759 LBMSDMExpDLL const char * lbmsdm_msg_get_name_idx(lbmsdm_msg_t * Message, size_t Index); 01760 01761 /*! \brief Get the index of a field in a message by field name. 01762 \param Message The SDM message from which the field name is to be fetched. 01763 \param Name Field name. 01764 \return The field index, or \c -1 if an error occurred. 01765 */ 01766 LBMSDMExpDLL int lbmsdm_msg_get_idx_name(lbmsdm_msg_t * Message, const char * Name); 01767 01768 /*! \brief Get the name of the current field for an iterator. 01769 \param Iterator The SDM iterator. 01770 \return The field name, or \c NULL if an error occurred. 01771 */ 01772 LBMSDMExpDLL const char * lbmsdm_iter_get_name(lbmsdm_iter_t * Iterator); 01773 01774 /*! \brief Get the type of a field in a message by field name. 01775 \param Message The SDM message from which the field type is to be fetched. 01776 \param Name Field name. 01777 \return The field type, or ::LBMSDM_TYPE_INVALID if an error occurred. 01778 */ 01779 LBMSDMExpDLL lbmsdm_field_type_t lbmsdm_msg_get_type_name(lbmsdm_msg_t * Message, const char * Name); 01780 01781 /*! \brief Get the type of a field in a message by field index. 01782 \param Message The SDM message from which the field type is to be fetched. 01783 \param Index Field index. 01784 \return The field type, or ::LBMSDM_TYPE_INVALID if an error occurred. 01785 */ 01786 LBMSDMExpDLL lbmsdm_field_type_t lbmsdm_msg_get_type_idx(lbmsdm_msg_t * Message, size_t Index); 01787 01788 /*! \brief Get the type of the current field for an iterator. 01789 \param Iterator The SDM iterator. 01790 \return The field type, or ::LBMSDM_TYPE_INVALID if an error occurred. 01791 */ 01792 LBMSDMExpDLL lbmsdm_field_type_t lbmsdm_iter_get_type(lbmsdm_iter_t * Iterator); 01793 01794 /*! \brief Determine if a field in a message is null, by field name. 01795 \param Message The SDM message containing the field. 01796 \param Name Field name. 01797 \retval 1 if the field is null. 01798 \retval 0 if the field is present and not null. 01799 \retval ::LBMSDM_FAILURE if an error occurred. 01800 */ 01801 LBMSDMExpDLL int lbmsdm_msg_is_null_name(lbmsdm_msg_t * Message, const char * Name); 01802 01803 /*! \brief Determine if a field in a message is null, by field index. 01804 \param Message The SDM message containing the field. 01805 \param Index Field index. 01806 \retval 1 if the field is null. 01807 \retval 0 if the field is present and not null. 01808 \retval ::LBMSDM_FAILURE if an error occurred. 01809 */ 01810 LBMSDMExpDLL int lbmsdm_msg_is_null_idx(lbmsdm_msg_t * Message, size_t Index); 01811 01812 /*! \brief Determine if the field referenced by an iterator is null. 01813 \param Iterator The SDM iterator. 01814 \retval 1 if the field is null. 01815 \retval 0 if the field is present and not null. 01816 \retval ::LBMSDM_FAILURE if an error occurred. 01817 */ 01818 LBMSDMExpDLL int lbmsdm_iter_is_null(lbmsdm_iter_t * Iterator); 01819 01820 /*! \brief Get the number of elements in an array field in a message by field name. 01821 \param Message The SDM message from which the array size is to be fetched. 01822 \param Name Field name. 01823 \return The number of elements in the array, or -1 if an error occurred. 01824 \note Calling this function for a non-array field will return 1 for the number 01825 of elements. 01826 */ 01827 LBMSDMExpDLL int lbmsdm_msg_get_elemcnt_name(lbmsdm_msg_t * Message, const char * Name); 01828 01829 /*! \brief Get the number of elements in an array field by field index. 01830 \param Message The SDM message from which the array size is to be fetched. 01831 \param Index Field index. 01832 \return The number of elements in the array, or -1 if an error occurred. 01833 \note Calling this function for a non-array field will return 1 for the number 01834 of elements. 01835 */ 01836 LBMSDMExpDLL int lbmsdm_msg_get_elemcnt_idx(lbmsdm_msg_t * Message, size_t Index); 01837 01838 /*! \brief Get the number of elements in the current array field for an iterator. 01839 \param Iterator The SDM iterator. 01840 \return The number of elements in the array, or -1 if an error occurred. 01841 \note Calling this function for a non-array field will return 1 for the number 01842 of elements. 01843 */ 01844 LBMSDMExpDLL int lbmsdm_iter_get_elemcnt(lbmsdm_iter_t * Iterator); 01845 01846 /*! \brief Get the length (in bytes) required for a field in a message by field name. 01847 \param Message The SDM message containing the field. 01848 \param Name Field name. 01849 \return The number of bytes required to store the field, or -1 if an error occurred. 01850 \note Calling this function for an array field will return -1. 01851 \sa lbmsdm_msg_get_field_array_size_name_elem() 01852 */ 01853 LBMSDMExpDLL int lbmsdm_msg_get_len_name(lbmsdm_msg_t * Message, const char * Name); 01854 01855 /*! \brief Get the length (in bytes) required for a field in a message by field index. 01856 \param Message The SDM message containing the field. 01857 \param Index Field index. 01858 \return The number of bytes required to store the field, or -1 if an error occurred. 01859 \note Calling this function for an array field will return -1. 01860 \sa lbmsdm_msg_get_field_array_size_index_elem() 01861 */ 01862 LBMSDMExpDLL int lbmsdm_msg_get_len_idx(lbmsdm_msg_t * Message, size_t Index); 01863 01864 /*! \brief Get the length (in bytes) required for the current field for an iterator. 01865 \param Iterator The SDM iterator. 01866 \return The number of bytes required to store the field, or -1 if an error occurred. 01867 \note Calling this function for an array field will return -1. 01868 \sa lbmsdm_iter_get_field_array_size_index_elem() 01869 */ 01870 LBMSDMExpDLL int lbmsdm_iter_get_len(lbmsdm_iter_t * Iterator); 01871 01872 /*! \brief Get the length (in bytes) required for an array field element in a message by field name. 01873 \param Message The SDM message containing the field. 01874 \param Name Field name. 01875 \param Element Element index (zero-based). 01876 \return The number of bytes required to store the field, or -1 if an error occurred. 01877 */ 01878 LBMSDMExpDLL int lbmsdm_msg_get_elemlen_name(lbmsdm_msg_t * Message, const char * Name, size_t Element); 01879 01880 /*! \brief Get the length (in bytes) required for an array field element in a message by field index. 01881 \param Message The SDM message containing the field. 01882 \param Index Field index. 01883 \param Element Element index (zero-based). 01884 \return The number of bytes required to store the field, or -1 if an error occurred. 01885 */ 01886 LBMSDMExpDLL int lbmsdm_msg_get_elemlen_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element); 01887 01888 /*! \brief Get the length (in bytes) required for an element of the current array field for an iterator. 01889 \param Iterator The SDM iterator. 01890 \param Element Element index (zero-based). 01891 \return The number of bytes required to store the field, or -1 if an error occurred. 01892 */ 01893 LBMSDMExpDLL int lbmsdm_iter_get_elemlen(lbmsdm_iter_t * Iterator, size_t Element); 01894 01895 /*! \defgroup get_scalar_idx Get scalar field values by field index 01896 The functions in this group allow the retrieval of the value of a scalar (non-array) field, 01897 referenced by field index. 01898 */ 01899 /*! \brief Fetch a field value from a message by field index. 01900 \ingroup get_scalar_idx 01901 \param Message The SDM message from which the field is to be fetched. 01902 \param Index Field index. 01903 \param Value Pointer to variable where the value is stored. 01904 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 01905 */ 01906 LBMSDMExpDLL int lbmsdm_msg_get_boolean_idx(lbmsdm_msg_t * Message, size_t Index, uint8_t * Value); 01907 01908 /*! \overload 01909 \ingroup get_scalar_idx 01910 */ 01911 LBMSDMExpDLL int lbmsdm_msg_get_int8_idx(lbmsdm_msg_t * Message, size_t Index, int8_t * Value); 01912 01913 /*! \overload 01914 \ingroup get_scalar_idx 01915 */ 01916 LBMSDMExpDLL int lbmsdm_msg_get_uint8_idx(lbmsdm_msg_t * Message, size_t Index, uint8_t * Value); 01917 01918 /*! \overload 01919 \ingroup get_scalar_idx 01920 */ 01921 LBMSDMExpDLL int lbmsdm_msg_get_int16_idx(lbmsdm_msg_t * Message, size_t Index, int16_t * Value); 01922 01923 /*! \overload 01924 \ingroup get_scalar_idx 01925 */ 01926 LBMSDMExpDLL int lbmsdm_msg_get_uint16_idx(lbmsdm_msg_t * Message, size_t Index, uint16_t * Value); 01927 01928 /*! \overload 01929 \ingroup get_scalar_idx 01930 */ 01931 LBMSDMExpDLL int lbmsdm_msg_get_int32_idx(lbmsdm_msg_t * Message, size_t Index, int32_t * Value); 01932 01933 /*! \overload 01934 \ingroup get_scalar_idx 01935 */ 01936 LBMSDMExpDLL int lbmsdm_msg_get_uint32_idx(lbmsdm_msg_t * Message, size_t Index, uint32_t * Value); 01937 01938 /*! \overload 01939 \ingroup get_scalar_idx 01940 */ 01941 LBMSDMExpDLL int lbmsdm_msg_get_int64_idx(lbmsdm_msg_t * Message, size_t Index, int64_t * Value); 01942 01943 /*! \overload 01944 \ingroup get_scalar_idx 01945 */ 01946 LBMSDMExpDLL int lbmsdm_msg_get_uint64_idx(lbmsdm_msg_t * Message, size_t Index, uint64_t * Value); 01947 01948 /*! \overload 01949 \ingroup get_scalar_idx 01950 */ 01951 LBMSDMExpDLL int lbmsdm_msg_get_float_idx(lbmsdm_msg_t * Message, size_t Index, float * Value); 01952 01953 /*! \overload 01954 \ingroup get_scalar_idx 01955 */ 01956 LBMSDMExpDLL int lbmsdm_msg_get_double_idx(lbmsdm_msg_t * Message, size_t Index, double * Value); 01957 01958 /*! \overload 01959 \ingroup get_scalar_idx 01960 */ 01961 LBMSDMExpDLL int lbmsdm_msg_get_decimal_idx(lbmsdm_msg_t * Message, size_t Index, lbmsdm_decimal_t * Value); 01962 01963 /*! \overload 01964 \ingroup get_scalar_idx 01965 */ 01966 LBMSDMExpDLL int lbmsdm_msg_get_timestamp_idx(lbmsdm_msg_t * Message, size_t Index, struct timeval * Value); 01967 01968 /*! \overload 01969 \ingroup get_scalar_idx 01970 */ 01971 LBMSDMExpDLL int lbmsdm_msg_get_message_idx(lbmsdm_msg_t * Message, size_t Index, lbmsdm_msg_t * * Value); 01972 01973 /*! \brief Fetch a string field value from a message by field index. 01974 \ingroup get_scalar_idx 01975 \param Message The SDM message from which the field is to be fetched. 01976 \param Index Field index. 01977 \param Value Pointer to variable where the value is stored. 01978 \param Size Pointer to a variable containing the maximum size of \a Value (including the 01979 terminating null character). 01980 On exit, it will contain the actual size of the string (including the terminating 01981 null character). 01982 \retval ::LBMSDM_SUCCESS if successful 01983 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 01984 \a Size will contain the length required. 01985 \retval ::LBMSDM_FAILURE otherwise. 01986 */ 01987 LBMSDMExpDLL int lbmsdm_msg_get_string_idx(lbmsdm_msg_t * Message, size_t Index, char * Value, size_t * Size); 01988 01989 /*! \brief Fetch a unicode field value from a message by field index. 01990 \ingroup get_scalar_idx 01991 \param Message The SDM message from which the field is to be fetched. 01992 \param Index Field index. 01993 \param Value Pointer to variable where the value is stored. 01994 \param Size Pointer to a variable containing the maximum size of \a Value in <tt>wchar_t</tt>s. 01995 On exit, it will contain the actual size of \a Value in <tt>wchar_t</tt>s. 01996 \retval ::LBMSDM_SUCCESS if successful 01997 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 01998 \a Size will contain the length required. 01999 \retval ::LBMSDM_FAILURE otherwise. 02000 */ 02001 LBMSDMExpDLL int lbmsdm_msg_get_unicode_idx(lbmsdm_msg_t * Message, size_t Index, wchar_t * Value, size_t * Size); 02002 02003 /*! \brief Fetch a BLOB field value from a message by field index. 02004 \ingroup get_scalar_idx 02005 \param Message The SDM message from which the field is to be fetched. 02006 \param Index Field index. 02007 \param Value Pointer to variable where the value is stored. 02008 \param Size Pointer to a variable containing the maximum size of \a Value in bytes. 02009 On exit, it will contain the actual size of \a Value. 02010 \retval ::LBMSDM_SUCCESS if successful 02011 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02012 \a Size will contain the length required. 02013 \retval ::LBMSDM_FAILURE otherwise. 02014 */ 02015 LBMSDMExpDLL int lbmsdm_msg_get_blob_idx(lbmsdm_msg_t * Message, size_t Index, void * Value, size_t * Size); 02016 02017 /*! \defgroup get_scalar_name Get scalar field values by field name 02018 The functions in this group allow the retrieval of the value of a scalar (non-array) field, 02019 referenced by field name. 02020 */ 02021 /*! \brief Fetch a field value from a message by field name. 02022 \ingroup get_scalar_name 02023 \param Message The SDM message from which the field is to be fetched. 02024 \param Name Field name. 02025 \param Value Pointer to variable where the value is stored. 02026 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02027 */ 02028 LBMSDMExpDLL int lbmsdm_msg_get_boolean_name(lbmsdm_msg_t * Message, const char * Name, uint8_t * Value); 02029 02030 /*! \overload 02031 \ingroup get_scalar_name 02032 */ 02033 LBMSDMExpDLL int lbmsdm_msg_get_int8_name(lbmsdm_msg_t * Message, const char * Name, int8_t * Value); 02034 02035 /*! \overload 02036 \ingroup get_scalar_name 02037 */ 02038 LBMSDMExpDLL int lbmsdm_msg_get_uint8_name(lbmsdm_msg_t * Message, const char * Name, uint8_t * Value); 02039 02040 /*! \overload 02041 \ingroup get_scalar_name 02042 */ 02043 LBMSDMExpDLL int lbmsdm_msg_get_int16_name(lbmsdm_msg_t * Message, const char * Name, int16_t * Value); 02044 02045 /*! \overload 02046 \ingroup get_scalar_name 02047 */ 02048 LBMSDMExpDLL int lbmsdm_msg_get_uint16_name(lbmsdm_msg_t * Message, const char * Name, uint16_t * Value); 02049 02050 /*! \overload 02051 \ingroup get_scalar_name 02052 */ 02053 LBMSDMExpDLL int lbmsdm_msg_get_int32_name(lbmsdm_msg_t * Message, const char * Name, int32_t * Value); 02054 02055 /*! \overload 02056 \ingroup get_scalar_name 02057 */ 02058 LBMSDMExpDLL int lbmsdm_msg_get_uint32_name(lbmsdm_msg_t * Message, const char * Name, uint32_t * Value); 02059 02060 /*! \overload 02061 \ingroup get_scalar_name 02062 */ 02063 LBMSDMExpDLL int lbmsdm_msg_get_int64_name(lbmsdm_msg_t * Message, const char * Name, int64_t * Value); 02064 02065 /*! \overload 02066 \ingroup get_scalar_name 02067 */ 02068 LBMSDMExpDLL int lbmsdm_msg_get_uint64_name(lbmsdm_msg_t * Message, const char * Name, uint64_t * Value); 02069 02070 /*! \overload 02071 \ingroup get_scalar_name 02072 */ 02073 LBMSDMExpDLL int lbmsdm_msg_get_float_name(lbmsdm_msg_t * Message, const char * Name, float * Value); 02074 02075 /*! \overload 02076 \ingroup get_scalar_name 02077 */ 02078 LBMSDMExpDLL int lbmsdm_msg_get_double_name(lbmsdm_msg_t * Message, const char * Name, double * Value); 02079 02080 /*! \overload 02081 \ingroup get_scalar_name 02082 */ 02083 LBMSDMExpDLL int lbmsdm_msg_get_decimal_name(lbmsdm_msg_t * Message, const char * Name, lbmsdm_decimal_t * Value); 02084 02085 /*! \overload 02086 \ingroup get_scalar_name 02087 */ 02088 LBMSDMExpDLL int lbmsdm_msg_get_timestamp_name(lbmsdm_msg_t * Message, const char * Name, struct timeval * Value); 02089 02090 /*! \overload 02091 \ingroup get_scalar_name 02092 */ 02093 LBMSDMExpDLL int lbmsdm_msg_get_message_name(lbmsdm_msg_t * Message, const char * Name, lbmsdm_msg_t * * Value); 02094 02095 /*! \brief Fetch a string field value from a message by field name. 02096 \ingroup get_scalar_name 02097 \param Message The SDM message from which the field is to be fetched. 02098 \param Name Field name. 02099 \param Value Pointer to variable where the value is stored. 02100 \param Size Pointer to a variable containing the maximum size of \a Value (including the 02101 terminating null character). 02102 On exit, it will contain the actual size of the string (including the terminating 02103 null character). 02104 \retval ::LBMSDM_SUCCESS if successful 02105 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02106 \a Size will contain the length required. 02107 \retval ::LBMSDM_FAILURE otherwise. 02108 */ 02109 LBMSDMExpDLL int lbmsdm_msg_get_string_name(lbmsdm_msg_t * Message, const char * Name, char * Value, size_t * Size); 02110 02111 /*! \brief Fetch a unicode field value from a message by field name. 02112 \ingroup get_scalar_name 02113 \param Message The SDM message from which the field is to be fetched. 02114 \param Name Field name. 02115 \param Value Pointer to variable where the value is stored. 02116 \param Size Pointer to a variable containing the maximum size of \a Value in <tt>wchar_t</tt>s. 02117 On exit, it will contain the actual size of the data in <tt>wchar_t</tt>s 02118 \retval ::LBMSDM_SUCCESS if successful 02119 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02120 \a Size will contain the length required in <tt>wchar_t</tt>s. 02121 \retval ::LBMSDM_FAILURE otherwise. 02122 */ 02123 LBMSDMExpDLL int lbmsdm_msg_get_unicode_name(lbmsdm_msg_t * Message, const char * Name, wchar_t * Value, size_t * Size); 02124 02125 /*! \brief Fetch a BLOB field value from a message by field name. 02126 \ingroup get_scalar_name 02127 \param Message The SDM message from which the field is to be fetched. 02128 \param Name Field name. 02129 \param Value Pointer to variable where the value is stored. 02130 \param Size Pointer to a variable containing the maximum size of \a Value in bytes. 02131 On exit, it will contain the actual size of the data. 02132 \retval ::LBMSDM_SUCCESS if successful 02133 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02134 \a Size will contain the length required in bytes. 02135 \retval ::LBMSDM_FAILURE otherwise. 02136 */ 02137 LBMSDMExpDLL int lbmsdm_msg_get_blob_name(lbmsdm_msg_t * Message, const char * Name, void * Value, size_t * Size); 02138 02139 /*! \defgroup get_scalar_iter Get a scalar field via an iterator 02140 The functions in this group allow the retrieval of the value of a scalar (non-array) field, 02141 referenced by an iterator. 02142 */ 02143 /*! \brief Fetch a field value from the field referenced by an iterator. 02144 \ingroup get_scalar_iter 02145 \param Iterator The SDM iterator to use. 02146 \param Value Pointer to variable where the value is stored. 02147 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02148 */ 02149 LBMSDMExpDLL int lbmsdm_iter_get_boolean(lbmsdm_iter_t * Iterator, uint8_t * Value); 02150 02151 /*! \overload 02152 \ingroup get_scalar_iter 02153 */ 02154 LBMSDMExpDLL int lbmsdm_iter_get_int8(lbmsdm_iter_t * Iterator, int8_t * Value); 02155 02156 /*! \overload 02157 \ingroup get_scalar_iter 02158 */ 02159 LBMSDMExpDLL int lbmsdm_iter_get_uint8(lbmsdm_iter_t * Iterator, uint8_t * Value); 02160 02161 /*! \overload 02162 \ingroup get_scalar_iter 02163 */ 02164 LBMSDMExpDLL int lbmsdm_iter_get_int16(lbmsdm_iter_t * Iterator, int16_t * Value); 02165 02166 /*! \overload 02167 \ingroup get_scalar_iter 02168 */ 02169 LBMSDMExpDLL int lbmsdm_iter_get_uint16(lbmsdm_iter_t * Iterator, uint16_t * Value); 02170 02171 /*! \overload 02172 \ingroup get_scalar_iter 02173 */ 02174 LBMSDMExpDLL int lbmsdm_iter_get_int32(lbmsdm_iter_t * Iterator, int32_t * Value); 02175 02176 /*! \overload 02177 \ingroup get_scalar_iter 02178 */ 02179 LBMSDMExpDLL int lbmsdm_iter_get_uint32(lbmsdm_iter_t * Iterator, uint32_t * Value); 02180 02181 /*! \overload 02182 \ingroup get_scalar_iter 02183 */ 02184 LBMSDMExpDLL int lbmsdm_iter_get_int64(lbmsdm_iter_t * Iterator, int64_t * Value); 02185 02186 /*! \overload 02187 \ingroup get_scalar_iter 02188 */ 02189 LBMSDMExpDLL int lbmsdm_iter_get_uint64(lbmsdm_iter_t * Iterator, uint64_t * Value); 02190 02191 /*! \overload 02192 \ingroup get_scalar_iter 02193 */ 02194 LBMSDMExpDLL int lbmsdm_iter_get_float(lbmsdm_iter_t * Iterator, float * Value); 02195 02196 /*! \overload 02197 \ingroup get_scalar_iter 02198 */ 02199 LBMSDMExpDLL int lbmsdm_iter_get_double(lbmsdm_iter_t * Iterator, double * Value); 02200 02201 /*! \overload 02202 \ingroup get_scalar_iter 02203 */ 02204 LBMSDMExpDLL int lbmsdm_iter_get_decimal(lbmsdm_iter_t * Iterator, lbmsdm_decimal_t * Value); 02205 02206 /*! \overload 02207 \ingroup get_scalar_iter 02208 */ 02209 LBMSDMExpDLL int lbmsdm_iter_get_timestamp(lbmsdm_iter_t * Iterator, struct timeval * Value); 02210 02211 /*! \overload 02212 \ingroup get_scalar_iter 02213 */ 02214 LBMSDMExpDLL int lbmsdm_iter_get_message(lbmsdm_iter_t * Iterator, lbmsdm_msg_t * * Value); 02215 02216 /*! \brief Fetch a string field value from the field referenced by an iterator. 02217 \ingroup get_scalar_iter 02218 \param Iterator The SDM iterator to use. 02219 \param Value Pointer to variable where the value is stored. 02220 \param Size Pointer to a variable containing the maximum size of \a Value (including the 02221 terminating null character). 02222 On exit, it will contain the actual size of the string (including the terminating 02223 null character). 02224 \retval ::LBMSDM_SUCCESS if successful 02225 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02226 \a Size will contain the length required. 02227 \retval ::LBMSDM_FAILURE otherwise. 02228 */ 02229 LBMSDMExpDLL int lbmsdm_iter_get_string(lbmsdm_iter_t * Iterator, char * Value, size_t * Size); 02230 02231 /*! \brief Fetch a unicode field value from the field referenced by an iterator. 02232 \ingroup get_scalar_iter 02233 \param Iterator The SDM iterator to use. 02234 \param Value Pointer to variable where the value is stored. 02235 \param Size Pointer to a variable containing the maximum size of \a Value in <tt>wchar_t</tt>s. 02236 On exit, it will contain the actual size of the data in <tt>wchar_t</tt>s. 02237 \retval ::LBMSDM_SUCCESS if successful 02238 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02239 \a Size will contain the length required in <tt>wchar_t</tt>s. 02240 \retval ::LBMSDM_FAILURE otherwise. 02241 */ 02242 LBMSDMExpDLL int lbmsdm_iter_get_unicode(lbmsdm_iter_t * Iterator, wchar_t * Value, size_t * Size); 02243 02244 /*! \brief Fetch a BLOB field value from the field referenced by an iterator. 02245 \ingroup get_scalar_iter 02246 \param Iterator The SDM iterator to use. 02247 \param Value Pointer to variable where the value is stored. 02248 \param Size Pointer to a variable containing the maximum size of \a Value in bytes. 02249 On exit, it will contain the actual size of the data. 02250 \retval ::LBMSDM_SUCCESS if successful 02251 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02252 \a Size will contain the length required in bytes. 02253 \retval ::LBMSDM_FAILURE otherwise. 02254 */ 02255 LBMSDMExpDLL int lbmsdm_iter_get_blob(lbmsdm_iter_t * Iterator, void * Value, size_t * Size); 02256 02257 /*! \defgroup get_elem_idx Get an element from an array field by field index 02258 The functions in this group allow the retrieval of an element value of an array field, 02259 referenced by field index. 02260 */ 02261 /*! \brief Fetch an array field element value from a message by field index. 02262 \ingroup get_elem_idx 02263 \param Message The SDM message from which the field is to be fetched. 02264 \param Index Field index. 02265 \param Element Element number (zero-based). 02266 \param Value Pointer to variable where the value is stored. 02267 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02268 */ 02269 LBMSDMExpDLL int lbmsdm_msg_get_boolean_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint8_t * Value); 02270 02271 /*! \overload 02272 \ingroup get_elem_idx 02273 */ 02274 LBMSDMExpDLL int lbmsdm_msg_get_int8_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int8_t * Value); 02275 02276 /*! \overload 02277 \ingroup get_elem_idx 02278 */ 02279 LBMSDMExpDLL int lbmsdm_msg_get_uint8_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint8_t * Value); 02280 02281 /*! \overload 02282 \ingroup get_elem_idx 02283 */ 02284 LBMSDMExpDLL int lbmsdm_msg_get_int16_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int16_t * Value); 02285 02286 /*! \overload 02287 \ingroup get_elem_idx 02288 */ 02289 LBMSDMExpDLL int lbmsdm_msg_get_uint16_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint16_t * Value); 02290 02291 /*! \overload 02292 \ingroup get_elem_idx 02293 */ 02294 LBMSDMExpDLL int lbmsdm_msg_get_int32_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int32_t * Value); 02295 02296 /*! \overload 02297 \ingroup get_elem_idx 02298 */ 02299 LBMSDMExpDLL int lbmsdm_msg_get_uint32_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint32_t * Value); 02300 02301 /*! \overload 02302 \ingroup get_elem_idx 02303 */ 02304 LBMSDMExpDLL int lbmsdm_msg_get_int64_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int64_t * Value); 02305 02306 /*! \overload 02307 \ingroup get_elem_idx 02308 */ 02309 LBMSDMExpDLL int lbmsdm_msg_get_uint64_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint64_t * Value); 02310 02311 /*! \overload 02312 \ingroup get_elem_idx 02313 */ 02314 LBMSDMExpDLL int lbmsdm_msg_get_float_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, float * Value); 02315 02316 /*! \overload 02317 \ingroup get_elem_idx 02318 */ 02319 LBMSDMExpDLL int lbmsdm_msg_get_double_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, double * Value); 02320 02321 /*! \overload 02322 \ingroup get_elem_idx 02323 */ 02324 LBMSDMExpDLL int lbmsdm_msg_get_decimal_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, lbmsdm_decimal_t * Value); 02325 02326 /*! \overload 02327 \ingroup get_elem_idx 02328 */ 02329 LBMSDMExpDLL int lbmsdm_msg_get_timestamp_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, struct timeval * Value); 02330 02331 /*! \overload 02332 \ingroup get_elem_idx 02333 */ 02334 LBMSDMExpDLL int lbmsdm_msg_get_message_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, lbmsdm_msg_t * * Value); 02335 02336 /*! \brief Fetch a string array field element value from a message by field index. 02337 \ingroup get_elem_idx 02338 \param Message The SDM message from which the field is to be fetched. 02339 \param Index Field index. 02340 \param Element Element number (zero-based). 02341 \param Value Pointer to variable where the value is stored. 02342 \param Size Pointer to a variable containing the maximum size of \a Value (including the 02343 terminating null character). 02344 On exit, it will contain the actual size of the string (including the terminating 02345 null character). 02346 \retval ::LBMSDM_SUCCESS if successful 02347 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02348 \a Size will contain the length required. 02349 \retval ::LBMSDM_FAILURE otherwise. 02350 */ 02351 LBMSDMExpDLL int lbmsdm_msg_get_string_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, char * Value, size_t * Size); 02352 02353 /*! \brief Fetch a unicode array field element value from a message by field index. 02354 \ingroup get_elem_idx 02355 \param Message The SDM message from which the field is to be fetched. 02356 \param Index Field index. 02357 \param Element Element number (zero-based). 02358 \param Value Pointer to variable where the value is stored. 02359 \param Size Pointer to a variable containing the maximum size of \a Value in <tt>wchar_t</tt>s. 02360 On exit, it will contain the actual size of the data in <tt>wchar_t</tt>s. 02361 \retval ::LBMSDM_SUCCESS if successful 02362 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02363 \a Size will contain the length required in <tt>wchar_t</tt>s. 02364 \retval ::LBMSDM_FAILURE otherwise. 02365 */ 02366 LBMSDMExpDLL int lbmsdm_msg_get_unicode_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, wchar_t * Value, size_t * Size); 02367 02368 /*! \brief Fetch a BLOB array field element value from a message by field index. 02369 \ingroup get_elem_idx 02370 \param Message The SDM message from which the field is to be fetched. 02371 \param Index Field index. 02372 \param Element Element number (zero-based). 02373 \param Value Pointer to variable where the value is stored. 02374 \param Size Pointer to a variable containing the maximum size of \a Value in bytes.. 02375 On exit, it will contain the actual size of the data. 02376 \retval ::LBMSDM_SUCCESS if successful 02377 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02378 \a Size will contain the length required in bytes. 02379 \retval ::LBMSDM_FAILURE otherwise. 02380 */ 02381 LBMSDMExpDLL int lbmsdm_msg_get_blob_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, void * Value, size_t * Size); 02382 02383 /*! \defgroup get_elem_name Get an element from an array field by field name 02384 The functions in this group allow the retrieval of an element value of an array field, 02385 referenced by field name. 02386 */ 02387 /*! \brief Fetch an array field element value from a message by field name. 02388 \ingroup get_elem_name 02389 \param Message The SDM message from which the field is to be fetched. 02390 \param Name Field name. 02391 \param Element Element number (zero-based). 02392 \param Value Pointer to variable where the value is stored. 02393 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02394 */ 02395 LBMSDMExpDLL int lbmsdm_msg_get_boolean_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint8_t * Value); 02396 02397 /*! \overload 02398 \ingroup get_elem_name 02399 */ 02400 LBMSDMExpDLL int lbmsdm_msg_get_int8_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int8_t * Value); 02401 02402 /*! \overload 02403 \ingroup get_elem_name 02404 */ 02405 LBMSDMExpDLL int lbmsdm_msg_get_uint8_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint8_t * Value); 02406 02407 /*! \overload 02408 \ingroup get_elem_name 02409 */ 02410 LBMSDMExpDLL int lbmsdm_msg_get_int16_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int16_t * Value); 02411 02412 /*! \overload 02413 \ingroup get_elem_name 02414 */ 02415 LBMSDMExpDLL int lbmsdm_msg_get_uint16_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint16_t * Value); 02416 02417 /*! \overload 02418 \ingroup get_elem_name 02419 */ 02420 LBMSDMExpDLL int lbmsdm_msg_get_int32_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int32_t * Value); 02421 02422 /*! \overload 02423 \ingroup get_elem_name 02424 */ 02425 LBMSDMExpDLL int lbmsdm_msg_get_uint32_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint32_t * Value); 02426 02427 /*! \overload 02428 \ingroup get_elem_name 02429 */ 02430 LBMSDMExpDLL int lbmsdm_msg_get_int64_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int64_t * Value); 02431 02432 /*! \overload 02433 \ingroup get_elem_name 02434 */ 02435 LBMSDMExpDLL int lbmsdm_msg_get_uint64_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint64_t * Value); 02436 02437 /*! \overload 02438 \ingroup get_elem_name 02439 */ 02440 LBMSDMExpDLL int lbmsdm_msg_get_float_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, float * Value); 02441 02442 /*! \overload 02443 \ingroup get_elem_name 02444 */ 02445 LBMSDMExpDLL int lbmsdm_msg_get_double_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, double * Value); 02446 02447 /*! \overload 02448 \ingroup get_elem_name 02449 */ 02450 LBMSDMExpDLL int lbmsdm_msg_get_decimal_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, lbmsdm_decimal_t * Value); 02451 02452 /*! \overload 02453 \ingroup get_elem_name 02454 */ 02455 LBMSDMExpDLL int lbmsdm_msg_get_timestamp_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, struct timeval * Value); 02456 02457 /*! \overload 02458 \ingroup get_elem_name 02459 */ 02460 LBMSDMExpDLL int lbmsdm_msg_get_message_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, lbmsdm_msg_t * * Value); 02461 02462 /*! \brief Fetch a string array field element value from a message by field name. 02463 \ingroup get_elem_name 02464 \param Message The SDM message from which the field is to be fetched. 02465 \param Name Field name. 02466 \param Element Element number (zero-based). 02467 \param Value Pointer to variable where the value is stored. 02468 \param Size Pointer to a variable containing the maximum size of \a Value (including the 02469 terminating null character). 02470 On exit, it will contain the actual size of the string (including the terminating 02471 null character). 02472 \retval ::LBMSDM_SUCCESS if successful 02473 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02474 \a Size will contain the length required. 02475 \retval ::LBMSDM_FAILURE otherwise. 02476 */ 02477 LBMSDMExpDLL int lbmsdm_msg_get_string_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, char * Value, size_t * Size); 02478 02479 /*! \brief Fetch a unicode array field element value from a message by field name. 02480 \ingroup get_elem_name 02481 \param Message The SDM message from which the field is to be fetched. 02482 \param Name Field name. 02483 \param Element Element number (zero-based). 02484 \param Value Pointer to variable where the value is stored. 02485 \param Size Pointer to a variable containing the maximum size of \a Value in <tt>wchar_t</tt>s. 02486 On exit, it will contain the actual size of the data. 02487 \retval ::LBMSDM_SUCCESS if successful 02488 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02489 \a Size will contain the length required in <tt>wchar_t</tt>s. 02490 \retval ::LBMSDM_FAILURE otherwise. 02491 */ 02492 LBMSDMExpDLL int lbmsdm_msg_get_unicode_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, wchar_t * Value, size_t * Size); 02493 02494 /*! \brief Fetch a BLOB array field element value from a message by field name. 02495 \ingroup get_elem_name 02496 \param Message The SDM message from which the field is to be fetched. 02497 \param Name Field name. 02498 \param Element Element number (zero-based). 02499 \param Value Pointer to variable where the value is stored. 02500 \param Size Pointer to a variable containing the maximum size of \a Value in bytes. 02501 On exit, it will contain the actual size of the data. 02502 \retval ::LBMSDM_SUCCESS if successful 02503 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02504 \a Size will contain the length required in bytes. 02505 \retval ::LBMSDM_FAILURE otherwise. 02506 */ 02507 LBMSDMExpDLL int lbmsdm_msg_get_blob_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, void * Value, size_t * Size); 02508 02509 02510 /*! \defgroup get_elem_iter Get an element from an array field referenced by an iterator 02511 The functions in this group allow the retrieval of an element value of an array field, 02512 referenced by an iterator. 02513 */ 02514 /*! \brief Fetch an array field element value from the field referenced by an iterator. 02515 \ingroup get_elem_iter 02516 \param Iterator The SDM iterator to use. 02517 \param Element Element number (zero-based). 02518 \param Value Pointer to variable where the value is stored. 02519 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02520 */ 02521 LBMSDMExpDLL int lbmsdm_iter_get_boolean_elem(lbmsdm_iter_t * Iterator, size_t Element, uint8_t * Value); 02522 02523 /*! \overload 02524 \ingroup get_elem_iter 02525 */ 02526 LBMSDMExpDLL int lbmsdm_iter_get_int8_elem(lbmsdm_iter_t * Iterator, size_t Element, int8_t * Value); 02527 02528 /*! \overload 02529 \ingroup get_elem_iter 02530 */ 02531 LBMSDMExpDLL int lbmsdm_iter_get_uint8_elem(lbmsdm_iter_t * Iterator, size_t Element, uint8_t * Value); 02532 02533 /*! \overload 02534 \ingroup get_elem_iter 02535 */ 02536 LBMSDMExpDLL int lbmsdm_iter_get_int16_elem(lbmsdm_iter_t * Iterator, size_t Element, int16_t * Value); 02537 02538 /*! \overload 02539 \ingroup get_elem_iter 02540 */ 02541 LBMSDMExpDLL int lbmsdm_iter_get_uint16_elem(lbmsdm_iter_t * Iterator, size_t Element, uint16_t * Value); 02542 02543 /*! \overload 02544 \ingroup get_elem_iter 02545 */ 02546 LBMSDMExpDLL int lbmsdm_iter_get_int32_elem(lbmsdm_iter_t * Iterator, size_t Element, int32_t * Value); 02547 02548 /*! \overload 02549 \ingroup get_elem_iter 02550 */ 02551 LBMSDMExpDLL int lbmsdm_iter_get_uint32_elem(lbmsdm_iter_t * Iterator, size_t Element, uint32_t * Value); 02552 02553 /*! \overload 02554 \ingroup get_elem_iter 02555 */ 02556 LBMSDMExpDLL int lbmsdm_iter_get_int64_elem(lbmsdm_iter_t * Iterator, size_t Element, int64_t * Value); 02557 02558 /*! \overload 02559 \ingroup get_elem_iter 02560 */ 02561 LBMSDMExpDLL int lbmsdm_iter_get_uint64_elem(lbmsdm_iter_t * Iterator, size_t Element, uint64_t * Value); 02562 02563 /*! \overload 02564 \ingroup get_elem_iter 02565 */ 02566 LBMSDMExpDLL int lbmsdm_iter_get_float_elem(lbmsdm_iter_t * Iterator, size_t Element, float * Value); 02567 02568 /*! \overload 02569 \ingroup get_elem_iter 02570 */ 02571 LBMSDMExpDLL int lbmsdm_iter_get_double_elem(lbmsdm_iter_t * Iterator, size_t Element, double * Value); 02572 02573 /*! \overload 02574 \ingroup get_elem_iter 02575 */ 02576 LBMSDMExpDLL int lbmsdm_iter_get_decimal_elem(lbmsdm_iter_t * Iterator, size_t Element, lbmsdm_decimal_t * Value); 02577 02578 /*! \overload 02579 \ingroup get_elem_iter 02580 */ 02581 LBMSDMExpDLL int lbmsdm_iter_get_timestamp_elem(lbmsdm_iter_t * Iterator, size_t Element, struct timeval * Value); 02582 02583 /*! \overload 02584 \ingroup get_elem_iter 02585 */ 02586 LBMSDMExpDLL int lbmsdm_iter_get_message_elem(lbmsdm_iter_t * Iterator, size_t Element, lbmsdm_msg_t * * Value); 02587 02588 /*! \brief Fetch a string array field element value from the field referenced by an iterator. 02589 \ingroup get_elem_iter 02590 \param Iterator The SDM iterator to use. 02591 \param Element Element number (zero-based). 02592 \param Value Pointer to variable where the value is stored. 02593 \param Size Pointer to a variable containing the maximum size of \a Value (including the 02594 terminating null character). 02595 On exit, it will contain the actual size of the string (including the terminating 02596 null character). 02597 \retval ::LBMSDM_SUCCESS if successful 02598 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the string. 02599 \a Size will contain the length required. 02600 \retval ::LBMSDM_FAILURE otherwise. 02601 */ 02602 LBMSDMExpDLL int lbmsdm_iter_get_string_elem(lbmsdm_iter_t * Iterator, size_t Element, char * Value, size_t * Size); 02603 02604 /*! \brief Fetch a unicode array field element value from the field referenced by an iterator. 02605 \ingroup get_elem_iter 02606 \param Iterator The SDM iterator to use. 02607 \param Element Element number (zero-based). 02608 \param Value Pointer to variable where the value is stored. 02609 \param Size Pointer to a variable containing the maximum size of \a Value in <tt>wchar_t</tt>s. 02610 On exit, it will contain the actual size of the data. 02611 \retval ::LBMSDM_SUCCESS if successful 02612 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02613 \a Size will contain the length required in <tt>wchar_t</tt>s. 02614 \retval ::LBMSDM_FAILURE otherwise. 02615 */ 02616 LBMSDMExpDLL int lbmsdm_iter_get_unicode_elem(lbmsdm_iter_t * Iterator, size_t Element, wchar_t * Value, size_t * Size); 02617 02618 /*! \brief Fetch a blob array field element value from the field referenced by an iterator. 02619 \ingroup get_elem_iter 02620 \param Iterator The SDM iterator to use. 02621 \param Element Element number (zero-based). 02622 \param Value Pointer to variable where the value is stored. 02623 \param Size Pointer to a variable containing the maximum size of \a Value in bytes. 02624 On exit, it will contain the actual size of the data. 02625 \retval ::LBMSDM_SUCCESS if successful 02626 \retval ::LBMSDM_INSUFFICIENT_BUFFER_LENGTH if \a Size is not large enough for the data. 02627 \a Size will contain the length required in bytes. 02628 \retval ::LBMSDM_FAILURE otherwise. 02629 */ 02630 LBMSDMExpDLL int lbmsdm_iter_get_blob_elem(lbmsdm_iter_t * Iterator, size_t Element, void * Value, size_t * Size); 02631 02632 /*! \brief Set a field in a message to null, by field name. 02633 \param Message The SDM message containing the field. 02634 \param Name Field name. 02635 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02636 */ 02637 LBMSDMExpDLL int lbmsdm_msg_set_null_name(lbmsdm_msg_t * Message, const char * Name); 02638 02639 /*! \brief Set a field in a message to null, by field index. 02640 \param Message The SDM message containing the field. 02641 \param Index Field index. 02642 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02643 */ 02644 LBMSDMExpDLL int lbmsdm_msg_set_null_idx(lbmsdm_msg_t * Message, size_t Index); 02645 02646 /*! \brief Set the field referenced by an iterator to null. 02647 \param Iterator The SDM iterator. 02648 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02649 */ 02650 LBMSDMExpDLL int lbmsdm_iter_set_null(lbmsdm_iter_t * Iterator); 02651 02652 02653 /*! \defgroup set_idx Set a field value in a message by field index 02654 The functions in this group allow the value of a field to be set, 02655 and the type of the field to be set to a scalar type, 02656 for a field referenced by field index. 02657 */ 02658 /*! \brief Set a field value in a message by field index. 02659 \ingroup set_idx 02660 \param Message The SDM message containing the field. 02661 \param Index Field index. 02662 \param Value Pointer to variable containing the value. 02663 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02664 */ 02665 LBMSDMExpDLL int lbmsdm_msg_set_boolean_idx(lbmsdm_msg_t * Message, size_t Index, uint8_t Value); 02666 02667 /*! \overload 02668 \ingroup set_idx 02669 */ 02670 LBMSDMExpDLL int lbmsdm_msg_set_int8_idx(lbmsdm_msg_t * Message, size_t Index, int8_t Value); 02671 02672 /*! \overload 02673 \ingroup set_idx 02674 */ 02675 LBMSDMExpDLL int lbmsdm_msg_set_uint8_idx(lbmsdm_msg_t * Message, size_t Index, uint8_t Value); 02676 02677 /*! \overload 02678 \ingroup set_idx 02679 */ 02680 LBMSDMExpDLL int lbmsdm_msg_set_int16_idx(lbmsdm_msg_t * Message, size_t Index, int16_t Value); 02681 02682 /*! \overload 02683 \ingroup set_idx 02684 */ 02685 LBMSDMExpDLL int lbmsdm_msg_set_uint16_idx(lbmsdm_msg_t * Message, size_t Index, uint16_t Value); 02686 02687 /*! \overload 02688 \ingroup set_idx 02689 */ 02690 LBMSDMExpDLL int lbmsdm_msg_set_int32_idx(lbmsdm_msg_t * Message, size_t Index, int32_t Value); 02691 02692 /*! \overload 02693 \ingroup set_idx 02694 */ 02695 LBMSDMExpDLL int lbmsdm_msg_set_uint32_idx(lbmsdm_msg_t * Message, size_t Index, uint32_t Value); 02696 02697 /*! \overload 02698 \ingroup set_idx 02699 */ 02700 LBMSDMExpDLL int lbmsdm_msg_set_int64_idx(lbmsdm_msg_t * Message, size_t Index, int64_t Value); 02701 02702 /*! \overload 02703 \ingroup set_idx 02704 */ 02705 LBMSDMExpDLL int lbmsdm_msg_set_uint64_idx(lbmsdm_msg_t * Message, size_t Index, uint64_t Value); 02706 02707 /*! \overload 02708 \ingroup set_idx 02709 */ 02710 LBMSDMExpDLL int lbmsdm_msg_set_float_idx(lbmsdm_msg_t * Message, size_t Index, float Value); 02711 02712 /*! \overload 02713 \ingroup set_idx 02714 */ 02715 LBMSDMExpDLL int lbmsdm_msg_set_double_idx(lbmsdm_msg_t * Message, size_t Index, double Value); 02716 02717 /*! \overload 02718 \ingroup set_idx 02719 */ 02720 LBMSDMExpDLL int lbmsdm_msg_set_decimal_idx(lbmsdm_msg_t * Message, size_t Index, const lbmsdm_decimal_t * Value); 02721 02722 /*! \overload 02723 \ingroup set_idx 02724 */ 02725 LBMSDMExpDLL int lbmsdm_msg_set_timestamp_idx(lbmsdm_msg_t * Message, size_t Index, const struct timeval * Value); 02726 02727 /*! \overload 02728 \ingroup set_idx 02729 */ 02730 LBMSDMExpDLL int lbmsdm_msg_set_message_idx(lbmsdm_msg_t * Message, size_t Index, const lbmsdm_msg_t * Value); 02731 02732 /*! \overload 02733 \ingroup set_idx 02734 */ 02735 LBMSDMExpDLL int lbmsdm_msg_set_string_idx(lbmsdm_msg_t * Message, size_t Index, const char * Value); 02736 02737 /*! \brief Set a unicode field value in a message by field index. 02738 \ingroup set_idx 02739 \param Message The SDM message containing the field. 02740 \param Index Field index. 02741 \param Value Pointer to variable containing the value. 02742 \param Length Length of \a Value in <tt>wchar_t</tt>s. 02743 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02744 */ 02745 LBMSDMExpDLL int lbmsdm_msg_set_unicode_idx(lbmsdm_msg_t * Message, size_t Index, const wchar_t * Value, size_t Length); 02746 02747 /*! \brief Set a BLOB field value in a message by field index. 02748 \ingroup set_idx 02749 \param Message The SDM message containing the field. 02750 \param Index Field index. 02751 \param Value Pointer to variable containing the value. 02752 \param Length Length of \a Value in bytes. 02753 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02754 */ 02755 LBMSDMExpDLL int lbmsdm_msg_set_blob_idx(lbmsdm_msg_t * Message, size_t Index, const void * Value, size_t Length); 02756 02757 /*! \defgroup set_name Set a field value in a message by field name 02758 The functions in this group allow the value of a field to be set, 02759 and the type of the field to be set to a scalar type, 02760 for a field referenced by field name. 02761 */ 02762 /*! \brief Set a field value in a message by field name. 02763 \ingroup set_name 02764 \param Message The SDM message containing the field. 02765 \param Name Field name. 02766 \param Value New field value. 02767 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02768 */ 02769 LBMSDMExpDLL int lbmsdm_msg_set_boolean_name(lbmsdm_msg_t * Message, const char * Name, uint8_t Value); 02770 02771 /*! \overload 02772 \ingroup set_name 02773 */ 02774 LBMSDMExpDLL int lbmsdm_msg_set_int8_name(lbmsdm_msg_t * Message, const char * Name, int8_t Value); 02775 02776 /*! \overload 02777 \ingroup set_name 02778 */ 02779 LBMSDMExpDLL int lbmsdm_msg_set_uint8_name(lbmsdm_msg_t * Message, const char * Name, uint8_t Value); 02780 02781 /*! \overload 02782 \ingroup set_name 02783 */ 02784 LBMSDMExpDLL int lbmsdm_msg_set_int16_name(lbmsdm_msg_t * Message, const char * Name, int16_t Value); 02785 02786 /*! \overload 02787 \ingroup set_name 02788 */ 02789 LBMSDMExpDLL int lbmsdm_msg_set_uint16_name(lbmsdm_msg_t * Message, const char * Name, uint16_t Value); 02790 02791 /*! \overload 02792 \ingroup set_name 02793 */ 02794 LBMSDMExpDLL int lbmsdm_msg_set_int32_name(lbmsdm_msg_t * Message, const char * Name, int32_t Value); 02795 02796 /*! \overload 02797 \ingroup set_name 02798 */ 02799 LBMSDMExpDLL int lbmsdm_msg_set_uint32_name(lbmsdm_msg_t * Message, const char * Name, uint32_t Value); 02800 02801 /*! \overload 02802 \ingroup set_name 02803 */ 02804 LBMSDMExpDLL int lbmsdm_msg_set_int64_name(lbmsdm_msg_t * Message, const char * Name, int64_t Value); 02805 02806 /*! \overload 02807 \ingroup set_name 02808 */ 02809 LBMSDMExpDLL int lbmsdm_msg_set_uint64_name(lbmsdm_msg_t * Message, const char * Name, uint64_t Value); 02810 02811 /*! \overload 02812 \ingroup set_name 02813 */ 02814 LBMSDMExpDLL int lbmsdm_msg_set_float_name(lbmsdm_msg_t * Message, const char * Name, float Value); 02815 02816 /*! \overload 02817 \ingroup set_name 02818 */ 02819 LBMSDMExpDLL int lbmsdm_msg_set_double_name(lbmsdm_msg_t * Message, const char * Name, double Value); 02820 02821 /*! \overload 02822 \ingroup set_name 02823 */ 02824 LBMSDMExpDLL int lbmsdm_msg_set_decimal_name(lbmsdm_msg_t * Message, const char * Name, const lbmsdm_decimal_t * Value); 02825 02826 /*! \overload 02827 \ingroup set_name 02828 */ 02829 LBMSDMExpDLL int lbmsdm_msg_set_timestamp_name(lbmsdm_msg_t * Message, const char * Name, const struct timeval * Value); 02830 02831 /*! \overload 02832 \ingroup set_name 02833 */ 02834 LBMSDMExpDLL int lbmsdm_msg_set_message_name(lbmsdm_msg_t * Message, const char * Name, const lbmsdm_msg_t * Value); 02835 02836 /*! \overload 02837 \ingroup set_name 02838 */ 02839 LBMSDMExpDLL int lbmsdm_msg_set_string_name(lbmsdm_msg_t * Message, const char * Name, const char * Value); 02840 02841 /*! \brief Set a unicode field value in a message by field name. 02842 \ingroup set_name 02843 \param Message The SDM message containing the field. 02844 \param Name Field name. 02845 \param Value New value. 02846 \param Length Length of \a Value in <tt>wchar_t</tt>s. 02847 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02848 */ 02849 LBMSDMExpDLL int lbmsdm_msg_set_unicode_name(lbmsdm_msg_t * Message, const char * Name, const wchar_t * Value, size_t Length); 02850 02851 /*! \brief Set a BLOB field value in a message by field name. 02852 \ingroup set_name 02853 \param Message The SDM message containing the field. 02854 \param Name Field name. 02855 \param Value New value. 02856 \param Length Length of \a Value in bytes. 02857 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02858 */ 02859 LBMSDMExpDLL int lbmsdm_msg_set_blob_name(lbmsdm_msg_t * Message, const char * Name, const void * Value, size_t Length); 02860 02861 /*! \defgroup set_iter Set a field value in a message referenced by an iterator 02862 The functions in this group allow the value of a field to be set, 02863 and the type of the field to be set to a scalar type, 02864 for a field referenced by an iterator. 02865 */ 02866 /*! \brief Set a field value in the field referenced by an iterator. 02867 \ingroup set_iter 02868 \param Iterator The SDM iterator to use. 02869 \param Value The new field value. 02870 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02871 */ 02872 LBMSDMExpDLL int lbmsdm_iter_set_boolean(lbmsdm_iter_t * Iterator, uint8_t Value); 02873 02874 /*! \overload 02875 \ingroup set_iter 02876 */ 02877 LBMSDMExpDLL int lbmsdm_iter_set_int8(lbmsdm_iter_t * Iterator, int8_t Value); 02878 02879 /*! \overload 02880 \ingroup set_iter 02881 */ 02882 LBMSDMExpDLL int lbmsdm_iter_set_uint8(lbmsdm_iter_t * Iterator, uint8_t Value); 02883 02884 /*! \overload 02885 \ingroup set_iter 02886 */ 02887 LBMSDMExpDLL int lbmsdm_iter_set_int16(lbmsdm_iter_t * Iterator, int16_t Value); 02888 02889 /*! \overload 02890 \ingroup set_iter 02891 */ 02892 LBMSDMExpDLL int lbmsdm_iter_set_uint16(lbmsdm_iter_t * Iterator, uint16_t Value); 02893 02894 /*! \overload 02895 \ingroup set_iter 02896 */ 02897 LBMSDMExpDLL int lbmsdm_iter_set_int32(lbmsdm_iter_t * Iterator, int32_t Value); 02898 02899 /*! \overload 02900 \ingroup set_iter 02901 */ 02902 LBMSDMExpDLL int lbmsdm_iter_set_uint32(lbmsdm_iter_t * Iterator, uint32_t Value); 02903 02904 /*! \overload 02905 \ingroup set_iter 02906 */ 02907 LBMSDMExpDLL int lbmsdm_iter_set_int64(lbmsdm_iter_t * Iterator, int64_t Value); 02908 02909 /*! \overload 02910 \ingroup set_iter 02911 */ 02912 LBMSDMExpDLL int lbmsdm_iter_set_uint64(lbmsdm_iter_t * Iterator, uint64_t Value); 02913 02914 /*! \overload 02915 \ingroup set_iter 02916 */ 02917 LBMSDMExpDLL int lbmsdm_iter_set_float(lbmsdm_iter_t * Iterator, float Value); 02918 02919 /*! \overload 02920 \ingroup set_iter 02921 */ 02922 LBMSDMExpDLL int lbmsdm_iter_set_double(lbmsdm_iter_t * Iterator, double Value); 02923 02924 /*! \overload 02925 \ingroup set_iter 02926 */ 02927 LBMSDMExpDLL int lbmsdm_iter_set_decimal(lbmsdm_iter_t * Iterator, const lbmsdm_decimal_t * Value); 02928 02929 /*! \overload 02930 \ingroup set_iter 02931 */ 02932 LBMSDMExpDLL int lbmsdm_iter_set_timestamp(lbmsdm_iter_t * Iterator, const struct timeval * Value); 02933 02934 /*! \overload 02935 \ingroup set_iter 02936 */ 02937 LBMSDMExpDLL int lbmsdm_iter_set_message(lbmsdm_iter_t * Iterator, const lbmsdm_msg_t * Value); 02938 02939 /*! \overload 02940 \ingroup set_iter 02941 */ 02942 LBMSDMExpDLL int lbmsdm_iter_set_string(lbmsdm_iter_t * Iterator, const char * Value); 02943 02944 /*! \brief Set a unicode field value in the field referenced by an iterator. 02945 \ingroup set_iter 02946 \param Iterator The SDM iterator to use. 02947 \param Value New value. 02948 \param Length Length of \a Value in <tt>wchar_t</tt>s. 02949 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02950 */ 02951 LBMSDMExpDLL int lbmsdm_iter_set_unicode(lbmsdm_iter_t * Iterator, const wchar_t * Value, size_t Length); 02952 02953 /*! \brief Set a BLOB field value in the field referenced by an iterator. 02954 \ingroup set_iter 02955 \param Iterator The SDM iterator to use. 02956 \param Value New value. 02957 \param Length Length of \a Value in bytes. 02958 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02959 */ 02960 LBMSDMExpDLL int lbmsdm_iter_set_blob(lbmsdm_iter_t * Iterator, const void * Value, size_t Length); 02961 02962 /*! \defgroup set_array_idx Set a field value in a message by field index to an array field 02963 The functions in this group allow the type of the field to be set to an array type, 02964 for a field referenced by field index. 02965 */ 02966 /*! \brief Set a field in a message by field index to an array field. 02967 \ingroup set_array_idx 02968 \param Message The SDM message containing the field. 02969 \param Index Field index. 02970 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 02971 */ 02972 LBMSDMExpDLL int lbmsdm_msg_set_boolean_array_idx(lbmsdm_msg_t * Message, size_t Index); 02973 02974 /*! \overload 02975 \ingroup set_array_idx 02976 */ 02977 LBMSDMExpDLL int lbmsdm_msg_set_int8_array_idx(lbmsdm_msg_t * Message, size_t Index); 02978 02979 /*! \overload 02980 \ingroup set_array_idx 02981 */ 02982 LBMSDMExpDLL int lbmsdm_msg_set_uint8_array_idx(lbmsdm_msg_t * Message, size_t Index); 02983 02984 /*! \overload 02985 \ingroup set_array_idx 02986 */ 02987 LBMSDMExpDLL int lbmsdm_msg_set_int16_array_idx(lbmsdm_msg_t * Message, size_t Index); 02988 02989 /*! \overload 02990 \ingroup set_array_idx 02991 */ 02992 LBMSDMExpDLL int lbmsdm_msg_set_uint16_array_idx(lbmsdm_msg_t * Message, size_t Index); 02993 02994 /*! \overload 02995 \ingroup set_array_idx 02996 */ 02997 LBMSDMExpDLL int lbmsdm_msg_set_int32_array_idx(lbmsdm_msg_t * Message, size_t Index); 02998 02999 /*! \overload 03000 \ingroup set_array_idx 03001 */ 03002 LBMSDMExpDLL int lbmsdm_msg_set_uint32_array_idx(lbmsdm_msg_t * Message, size_t Index); 03003 03004 /*! \overload 03005 \ingroup set_array_idx 03006 */ 03007 LBMSDMExpDLL int lbmsdm_msg_set_int64_array_idx(lbmsdm_msg_t * Message, size_t Index); 03008 03009 /*! \overload 03010 \ingroup set_array_idx 03011 */ 03012 LBMSDMExpDLL int lbmsdm_msg_set_uint64_array_idx(lbmsdm_msg_t * Message, size_t Index); 03013 03014 /*! \overload 03015 \ingroup set_array_idx 03016 */ 03017 LBMSDMExpDLL int lbmsdm_msg_set_float_array_idx(lbmsdm_msg_t * Message, size_t Index); 03018 03019 /*! \overload 03020 \ingroup set_array_idx 03021 */ 03022 LBMSDMExpDLL int lbmsdm_msg_set_double_array_idx(lbmsdm_msg_t * Message, size_t Index); 03023 03024 /*! \overload 03025 \ingroup set_array_idx 03026 */ 03027 LBMSDMExpDLL int lbmsdm_msg_set_decimal_array_idx(lbmsdm_msg_t * Message, size_t Index); 03028 03029 /*! \overload 03030 \ingroup set_array_idx 03031 */ 03032 LBMSDMExpDLL int lbmsdm_msg_set_timestamp_array_idx(lbmsdm_msg_t * Message, size_t Index); 03033 03034 /*! \overload 03035 \ingroup set_array_idx 03036 */ 03037 LBMSDMExpDLL int lbmsdm_msg_set_message_array_idx(lbmsdm_msg_t * Message, size_t Index); 03038 03039 /*! \overload 03040 \ingroup set_array_idx 03041 */ 03042 LBMSDMExpDLL int lbmsdm_msg_set_string_array_idx(lbmsdm_msg_t * Message, size_t Index); 03043 03044 /*! \overload 03045 \ingroup set_array_idx 03046 */ 03047 LBMSDMExpDLL int lbmsdm_msg_set_unicode_array_idx(lbmsdm_msg_t * Message, size_t Index); 03048 03049 /*! \overload 03050 \ingroup set_array_idx 03051 */ 03052 LBMSDMExpDLL int lbmsdm_msg_set_blob_array_idx(lbmsdm_msg_t * Message, size_t Index); 03053 03054 /*! \defgroup set_array_name Set a field value in a message by field name to an array field 03055 The functions in this group allow the type of the field to be set to an array type, 03056 for a field referenced by field name. 03057 */ 03058 /*! \brief Set a field in a message by field name to an array field. 03059 \ingroup set_array_name 03060 \param Message The SDM message containing the field. 03061 \param Name Field name. 03062 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03063 */ 03064 LBMSDMExpDLL int lbmsdm_msg_set_boolean_array_name(lbmsdm_msg_t * Message, const char * Name); 03065 03066 /*! \overload 03067 \ingroup set_array_name 03068 */ 03069 LBMSDMExpDLL int lbmsdm_msg_set_int8_array_name(lbmsdm_msg_t * Message, const char * Name); 03070 03071 /*! \overload 03072 \ingroup set_array_name 03073 */ 03074 LBMSDMExpDLL int lbmsdm_msg_set_uint8_array_name(lbmsdm_msg_t * Message, const char * Name); 03075 03076 /*! \overload 03077 \ingroup set_array_name 03078 */ 03079 LBMSDMExpDLL int lbmsdm_msg_set_int16_array_name(lbmsdm_msg_t * Message, const char * Name); 03080 03081 /*! \overload 03082 \ingroup set_array_name 03083 */ 03084 LBMSDMExpDLL int lbmsdm_msg_set_uint16_array_name(lbmsdm_msg_t * Message, const char * Name); 03085 03086 /*! \overload 03087 \ingroup set_array_name 03088 */ 03089 LBMSDMExpDLL int lbmsdm_msg_set_int32_array_name(lbmsdm_msg_t * Message, const char * Name); 03090 03091 /*! \overload 03092 \ingroup set_array_name 03093 */ 03094 LBMSDMExpDLL int lbmsdm_msg_set_uint32_array_name(lbmsdm_msg_t * Message, const char * Name); 03095 03096 /*! \overload 03097 \ingroup set_array_name 03098 */ 03099 LBMSDMExpDLL int lbmsdm_msg_set_int64_array_name(lbmsdm_msg_t * Message, const char * Name); 03100 03101 /*! \overload 03102 \ingroup set_array_name 03103 */ 03104 LBMSDMExpDLL int lbmsdm_msg_set_uint64_array_name(lbmsdm_msg_t * Message, const char * Name); 03105 03106 /*! \overload 03107 \ingroup set_array_name 03108 */ 03109 LBMSDMExpDLL int lbmsdm_msg_set_float_array_name(lbmsdm_msg_t * Message, const char * Name); 03110 03111 /*! \overload 03112 \ingroup set_array_name 03113 */ 03114 LBMSDMExpDLL int lbmsdm_msg_set_double_array_name(lbmsdm_msg_t * Message, const char * Name); 03115 03116 /*! \overload 03117 \ingroup set_array_name 03118 */ 03119 LBMSDMExpDLL int lbmsdm_msg_set_decimal_array_name(lbmsdm_msg_t * Message, const char * Name); 03120 03121 /*! \overload 03122 \ingroup set_array_name 03123 */ 03124 LBMSDMExpDLL int lbmsdm_msg_set_timestamp_array_name(lbmsdm_msg_t * Message, const char * Name); 03125 03126 /*! \overload 03127 \ingroup set_array_name 03128 */ 03129 LBMSDMExpDLL int lbmsdm_msg_set_message_array_name(lbmsdm_msg_t * Message, const char * Name); 03130 03131 /*! \overload 03132 \ingroup set_array_name 03133 */ 03134 LBMSDMExpDLL int lbmsdm_msg_set_string_array_name(lbmsdm_msg_t * Message, const char * Name); 03135 03136 /*! \overload 03137 \ingroup set_array_name 03138 */ 03139 LBMSDMExpDLL int lbmsdm_msg_set_unicode_array_name(lbmsdm_msg_t * Message, const char * Name); 03140 03141 /*! \overload 03142 \ingroup set_array_name 03143 */ 03144 LBMSDMExpDLL int lbmsdm_msg_set_blob_array_name(lbmsdm_msg_t * Message, const char * Name); 03145 03146 /*! \defgroup set_array_iter Set a field value in a message, referenced by an iterator, to an array field. 03147 The functions in this group allow the type of the field to be set to an array type, 03148 for a field referenced by an iterator. 03149 */ 03150 /*! \brief Set a field in a message by field name to an array field. 03151 \ingroup set_array_iter 03152 \param Iterator The iterator referencing the field. 03153 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03154 */ 03155 LBMSDMExpDLL int lbmsdm_iter_set_boolean_array(lbmsdm_iter_t * Iterator); 03156 03157 /*! \overload 03158 \ingroup set_array_iter 03159 */ 03160 LBMSDMExpDLL int lbmsdm_iter_set_int8_array(lbmsdm_iter_t * Iterator); 03161 03162 /*! \overload 03163 \ingroup set_array_iter 03164 */ 03165 LBMSDMExpDLL int lbmsdm_iter_set_uint8_array(lbmsdm_iter_t * Iterator); 03166 03167 /*! \overload 03168 \ingroup set_array_iter 03169 */ 03170 LBMSDMExpDLL int lbmsdm_iter_set_int16_array(lbmsdm_iter_t * Iterator); 03171 03172 /*! \overload 03173 \ingroup set_array_iter 03174 */ 03175 LBMSDMExpDLL int lbmsdm_iter_set_uint16_array(lbmsdm_iter_t * Iterator); 03176 03177 /*! \overload 03178 \ingroup set_array_iter 03179 */ 03180 LBMSDMExpDLL int lbmsdm_iter_set_int32_array(lbmsdm_iter_t * Iterator); 03181 03182 /*! \overload 03183 \ingroup set_array_iter 03184 */ 03185 LBMSDMExpDLL int lbmsdm_iter_set_uint32_array(lbmsdm_iter_t * Iterator); 03186 03187 /*! \overload 03188 \ingroup set_array_iter 03189 */ 03190 LBMSDMExpDLL int lbmsdm_iter_set_int64_array(lbmsdm_iter_t * Iterator); 03191 03192 /*! \overload 03193 \ingroup set_array_iter 03194 */ 03195 LBMSDMExpDLL int lbmsdm_iter_set_uint64_array(lbmsdm_iter_t * Iterator); 03196 03197 /*! \overload 03198 \ingroup set_array_iter 03199 */ 03200 LBMSDMExpDLL int lbmsdm_iter_set_float_array(lbmsdm_iter_t * Iterator); 03201 03202 /*! \overload 03203 \ingroup set_array_iter 03204 */ 03205 LBMSDMExpDLL int lbmsdm_iter_set_double_array(lbmsdm_iter_t * Iterator); 03206 03207 /*! \overload 03208 \ingroup set_array_iter 03209 */ 03210 LBMSDMExpDLL int lbmsdm_iter_set_decimal_array(lbmsdm_iter_t * Iterator); 03211 03212 /*! \overload 03213 \ingroup set_array_iter 03214 */ 03215 LBMSDMExpDLL int lbmsdm_iter_set_timestamp_array(lbmsdm_iter_t * Iterator); 03216 03217 /*! \overload 03218 \ingroup set_array_iter 03219 */ 03220 LBMSDMExpDLL int lbmsdm_iter_set_message_array(lbmsdm_iter_t * Iterator); 03221 03222 /*! \overload 03223 \ingroup set_array_iter 03224 */ 03225 LBMSDMExpDLL int lbmsdm_iter_set_string_array(lbmsdm_iter_t * Iterator); 03226 03227 /*! \overload 03228 \ingroup set_array_iter 03229 */ 03230 LBMSDMExpDLL int lbmsdm_iter_set_unicode_array(lbmsdm_iter_t * Iterator); 03231 03232 /*! \overload 03233 \ingroup set_array_iter 03234 */ 03235 LBMSDMExpDLL int lbmsdm_iter_set_blob_array(lbmsdm_iter_t * Iterator); 03236 03237 /*! \defgroup set_elem_idx Set an array field element value by field index 03238 The functions in this group allow the value of an element of an array field to be set, 03239 for a field referenced by field index. 03240 */ 03241 /*! \brief Set the value of an array field element in a message by field index. 03242 \ingroup set_elem_idx 03243 \param Message The SDM message containing the field. 03244 \param Index Field index. 03245 \param Element Array element (zero-based). 03246 \param Value Pointer to variable containing the element value. 03247 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03248 */ 03249 LBMSDMExpDLL int lbmsdm_msg_set_boolean_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint8_t Value); 03250 03251 /*! \ingroup set_elem_idx 03252 \overload 03253 */ 03254 LBMSDMExpDLL int lbmsdm_msg_set_int8_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int8_t Value); 03255 03256 /*! \ingroup set_elem_idx 03257 \overload 03258 */ 03259 LBMSDMExpDLL int lbmsdm_msg_set_uint8_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint8_t Value); 03260 03261 /*! \ingroup set_elem_idx 03262 \overload 03263 */ 03264 LBMSDMExpDLL int lbmsdm_msg_set_int16_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int16_t Value); 03265 03266 /*! \ingroup set_elem_idx 03267 \overload 03268 */ 03269 LBMSDMExpDLL int lbmsdm_msg_set_uint16_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint16_t Value); 03270 03271 /*! \ingroup set_elem_idx 03272 \overload 03273 */ 03274 LBMSDMExpDLL int lbmsdm_msg_set_int32_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int32_t Value); 03275 03276 /*! \ingroup set_elem_idx 03277 \overload 03278 */ 03279 LBMSDMExpDLL int lbmsdm_msg_set_uint32_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint32_t Value); 03280 03281 /*! \ingroup set_elem_idx 03282 \overload 03283 */ 03284 LBMSDMExpDLL int lbmsdm_msg_set_int64_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, int64_t Value); 03285 03286 /*! \ingroup set_elem_idx 03287 \overload 03288 */ 03289 LBMSDMExpDLL int lbmsdm_msg_set_uint64_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, uint64_t Value); 03290 03291 /*! \ingroup set_elem_idx 03292 \overload 03293 */ 03294 LBMSDMExpDLL int lbmsdm_msg_set_float_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, float Value); 03295 03296 /*! \ingroup set_elem_idx 03297 \overload 03298 */ 03299 LBMSDMExpDLL int lbmsdm_msg_set_double_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, double Value); 03300 03301 /*! \ingroup set_elem_idx 03302 \overload 03303 */ 03304 LBMSDMExpDLL int lbmsdm_msg_set_decimal_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, const lbmsdm_decimal_t * Value); 03305 03306 /*! \ingroup set_elem_idx 03307 \overload 03308 */ 03309 LBMSDMExpDLL int lbmsdm_msg_set_timestamp_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, const struct timeval * Value); 03310 03311 /*! \ingroup set_elem_idx 03312 \overload 03313 */ 03314 LBMSDMExpDLL int lbmsdm_msg_set_message_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, const lbmsdm_msg_t * Value); 03315 03316 /*! \ingroup set_elem_idx 03317 \overload 03318 */ 03319 LBMSDMExpDLL int lbmsdm_msg_set_string_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, const char * Value); 03320 03321 /*! \brief Set the value of a unicode array field element in a message by field index. 03322 \ingroup set_elem_idx 03323 \param Message The SDM message containing the field. 03324 \param Index Field index. 03325 \param Element Array element (zero-based). 03326 \param Value Pointer to variable containing the element value. 03327 \param Length Length of \a Value in <tt>wchar_t</tt>s. 03328 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03329 */ 03330 LBMSDMExpDLL int lbmsdm_msg_set_unicode_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, const wchar_t * Value, size_t Length); 03331 03332 /*! \brief Set the value of a BLOB array field element in a message by field index. 03333 \ingroup set_elem_idx 03334 \param Message The SDM message containing the field. 03335 \param Index Field index. 03336 \param Element Array element (zero-based). 03337 \param Value Pointer to variable containing the element value. 03338 \param Length Length of \a Value in bytes. 03339 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03340 */ 03341 LBMSDMExpDLL int lbmsdm_msg_set_blob_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element, const void * Value, size_t Length); 03342 03343 /*! \defgroup set_elem_name Set an array field element value by field name 03344 The functions in this group allow the value of an element of an array field to be set, 03345 for a field referenced by field name. 03346 */ 03347 /*! \brief Set the value of an array field element in a message by field name. 03348 \ingroup set_elem_name 03349 \param Message The SDM message containing the field. 03350 \param Name Field name. 03351 \param Element Array element (zero-based). 03352 \param Value Pointer to variable where the value is stored. 03353 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03354 */ 03355 LBMSDMExpDLL int lbmsdm_msg_set_boolean_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint8_t Value); 03356 03357 /*! \ingroup set_elem_name 03358 \overload 03359 */ 03360 LBMSDMExpDLL int lbmsdm_msg_set_int8_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int8_t Value); 03361 03362 /*! \ingroup set_elem_name 03363 \overload 03364 */ 03365 LBMSDMExpDLL int lbmsdm_msg_set_uint8_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint8_t Value); 03366 03367 /*! \ingroup set_elem_name 03368 \overload 03369 */ 03370 LBMSDMExpDLL int lbmsdm_msg_set_int16_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int16_t Value); 03371 03372 /*! \ingroup set_elem_name 03373 \overload 03374 */ 03375 LBMSDMExpDLL int lbmsdm_msg_set_uint16_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint16_t Value); 03376 03377 /*! \ingroup set_elem_name 03378 \overload 03379 */ 03380 LBMSDMExpDLL int lbmsdm_msg_set_int32_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int32_t Value); 03381 03382 /*! \ingroup set_elem_name 03383 \overload 03384 */ 03385 LBMSDMExpDLL int lbmsdm_msg_set_uint32_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint32_t Value); 03386 03387 /*! \ingroup set_elem_name 03388 \overload 03389 */ 03390 LBMSDMExpDLL int lbmsdm_msg_set_int64_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, int64_t Value); 03391 03392 /*! \ingroup set_elem_name 03393 \overload 03394 */ 03395 LBMSDMExpDLL int lbmsdm_msg_set_uint64_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, uint64_t Value); 03396 03397 /*! \ingroup set_elem_name 03398 \overload 03399 */ 03400 LBMSDMExpDLL int lbmsdm_msg_set_float_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, float Value); 03401 03402 /*! \ingroup set_elem_name 03403 \overload 03404 */ 03405 LBMSDMExpDLL int lbmsdm_msg_set_double_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, double Value); 03406 03407 /*! \ingroup set_elem_name 03408 \overload 03409 */ 03410 LBMSDMExpDLL int lbmsdm_msg_set_decimal_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, const lbmsdm_decimal_t * Value); 03411 03412 /*! \ingroup set_elem_name 03413 \overload 03414 */ 03415 LBMSDMExpDLL int lbmsdm_msg_set_timestamp_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, const struct timeval * Value); 03416 03417 /*! \ingroup set_elem_name 03418 \overload 03419 */ 03420 LBMSDMExpDLL int lbmsdm_msg_set_message_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, const lbmsdm_msg_t * Value); 03421 03422 /*! \ingroup set_elem_name 03423 \overload 03424 */ 03425 LBMSDMExpDLL int lbmsdm_msg_set_string_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, const char * Value); 03426 03427 /*! \brief Set the value of a unicode array field element in a message by field name. 03428 \ingroup set_elem_name 03429 \param Message The SDM message containing the field. 03430 \param Name Field name. 03431 \param Element Array element (zero-based). 03432 \param Value New value. 03433 \param Length Length of \a Value in <tt>wchar_t</tt>s. 03434 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03435 */ 03436 LBMSDMExpDLL int lbmsdm_msg_set_unicode_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, const wchar_t * Value, size_t Length); 03437 03438 /*! \brief Set the value of a BLOB array field element in a message by field name. 03439 \ingroup set_elem_name 03440 \param Message The SDM message containing the field. 03441 \param Name Field name. 03442 \param Element Array element (zero-based). 03443 \param Value New value. 03444 \param Length Length of \a Value in bytes. 03445 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03446 */ 03447 LBMSDMExpDLL int lbmsdm_msg_set_blob_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element, const void * Value, size_t Length); 03448 03449 /*! \defgroup set_elem_iter Set an array field element value for a field referenced by an iterator 03450 The functions in this group allow the value of an element of an array field to be set, 03451 for a field referenced by an iterator. 03452 */ 03453 /*! \brief Set the value of an array field element in the field referenced by an iterator. 03454 \ingroup set_elem_iter 03455 \param Iterator The SDM iterator to use. 03456 \param Element Array element (zero-based). 03457 \param Value New field value. 03458 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03459 */ 03460 LBMSDMExpDLL int lbmsdm_iter_set_boolean_elem(lbmsdm_iter_t * Iterator, size_t Element, uint8_t Value); 03461 03462 /*! \ingroup set_elem_iter 03463 \overload 03464 */ 03465 LBMSDMExpDLL int lbmsdm_iter_set_int8_elem(lbmsdm_iter_t * Iterator, size_t Element, int8_t Value); 03466 03467 /*! \ingroup set_elem_iter 03468 \overload 03469 */ 03470 LBMSDMExpDLL int lbmsdm_iter_set_uint8_elem(lbmsdm_iter_t * Iterator, size_t Element, uint8_t Value); 03471 03472 /*! \ingroup set_elem_iter 03473 \overload 03474 */ 03475 LBMSDMExpDLL int lbmsdm_iter_set_int16_elem(lbmsdm_iter_t * Iterator, size_t Element, int16_t Value); 03476 03477 /*! \ingroup set_elem_iter 03478 \overload 03479 */ 03480 LBMSDMExpDLL int lbmsdm_iter_set_uint16_elem(lbmsdm_iter_t * Iterator, size_t Element, uint16_t Value); 03481 03482 /*! \ingroup set_elem_iter 03483 \overload 03484 */ 03485 LBMSDMExpDLL int lbmsdm_iter_set_int32_elem(lbmsdm_iter_t * Iterator, size_t Element, int32_t Value); 03486 03487 /*! \ingroup set_elem_iter 03488 \overload 03489 */ 03490 LBMSDMExpDLL int lbmsdm_iter_set_uint32_elem(lbmsdm_iter_t * Iterator, size_t Element, uint32_t Value); 03491 03492 /*! \ingroup set_elem_iter 03493 \overload 03494 */ 03495 LBMSDMExpDLL int lbmsdm_iter_set_int64_elem(lbmsdm_iter_t * Iterator, size_t Element, int64_t Value); 03496 03497 /*! \ingroup set_elem_iter 03498 \overload 03499 */ 03500 LBMSDMExpDLL int lbmsdm_iter_set_uint64_elem(lbmsdm_iter_t * Iterator, size_t Element, uint64_t Value); 03501 03502 /*! \ingroup set_elem_iter 03503 \overload 03504 */ 03505 LBMSDMExpDLL int lbmsdm_iter_set_float_elem(lbmsdm_iter_t * Iterator, size_t Element, float Value); 03506 03507 /*! \ingroup set_elem_iter 03508 \overload 03509 */ 03510 LBMSDMExpDLL int lbmsdm_iter_set_double_elem(lbmsdm_iter_t * Iterator, size_t Element, double Value); 03511 03512 /*! \ingroup set_elem_iter 03513 \overload 03514 */ 03515 LBMSDMExpDLL int lbmsdm_iter_set_decimal_elem(lbmsdm_iter_t * Iterator, size_t Element, const lbmsdm_decimal_t * Value); 03516 03517 /*! \ingroup set_elem_iter 03518 \overload 03519 */ 03520 LBMSDMExpDLL int lbmsdm_iter_set_timestamp_elem(lbmsdm_iter_t * Iterator, size_t Element, const struct timeval * Value); 03521 03522 /*! \ingroup set_elem_iter 03523 \overload 03524 */ 03525 LBMSDMExpDLL int lbmsdm_iter_set_message_elem(lbmsdm_iter_t * Iterator, size_t Element, const lbmsdm_msg_t * Value); 03526 03527 /*! \ingroup set_elem_iter 03528 \overload 03529 */ 03530 LBMSDMExpDLL int lbmsdm_iter_set_string_elem(lbmsdm_iter_t * Iterator, size_t Element, const char * Value); 03531 03532 /*! \brief Set the value of a unicode array field element in the field referenced by an iterator. 03533 \ingroup set_elem_iter 03534 \param Iterator The SDM iterator to use. 03535 \param Element Array element (zero-based). 03536 \param Value New field value. 03537 \param Length Length of \a Value in <tt>wchar_t</tt>s. 03538 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03539 */ 03540 LBMSDMExpDLL int lbmsdm_iter_set_unicode_elem(lbmsdm_iter_t * Iterator, size_t Element, const wchar_t * Value, size_t Length); 03541 03542 /*! \brief Set the value of a BLOB array field element in the field referenced by an iterator. 03543 \ingroup set_elem_iter 03544 \param Iterator The SDM iterator to use. 03545 \param Element Array element (zero-based). 03546 \param Value New field value. 03547 \param Length Length of \a Value in bytes. 03548 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03549 */ 03550 LBMSDMExpDLL int lbmsdm_iter_set_blob_elem(lbmsdm_iter_t * Iterator, size_t Element, const void * Value, size_t Length); 03551 03552 /*! \brief Delete a field from a message by field index. 03553 \param Message The SDM message containing the field. 03554 \param Index Field index. 03555 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03556 */ 03557 LBMSDMExpDLL int lbmsdm_msg_del_idx(lbmsdm_msg_t * Message, size_t Index); 03558 03559 /*! \brief Delete a field from a message by field name. 03560 \param Message The SDM message containing the field. 03561 \param Name Field name. 03562 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03563 */ 03564 LBMSDMExpDLL int lbmsdm_msg_del_name(lbmsdm_msg_t * Message, const char * Name); 03565 03566 /*! \brief Delete a field referenced by an iterator. 03567 \param Iterator The SDM iterator to use. 03568 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03569 */ 03570 LBMSDMExpDLL int lbmsdm_iter_del(lbmsdm_iter_t * Iterator); 03571 03572 /*! \brief Delete an element from an array field by field index. 03573 \param Message The SDM message containing the field. 03574 \param Index Field index. 03575 \param Element Element to be deleted. 03576 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03577 */ 03578 LBMSDMExpDLL int lbmsdm_msg_del_elem_idx(lbmsdm_msg_t * Message, size_t Index, size_t Element); 03579 03580 /*! \brief Delete an element from an array field by field name. 03581 \param Message The SDM message containing the field. 03582 \param Name Field name. 03583 \param Element Element to be deleted. 03584 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03585 */ 03586 LBMSDMExpDLL int lbmsdm_msg_del_elem_name(lbmsdm_msg_t * Message, const char * Name, size_t Element); 03587 03588 /*! \brief Delete an element from an array field referenced by an iterator. 03589 \param Iterator The SDM iterator to use. 03590 \param Element Element to be deleted. 03591 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03592 */ 03593 LBMSDMExpDLL int lbmsdm_iter_del_elem(lbmsdm_iter_t * Iterator, size_t Element); 03594 03595 /*! \brief Create and fill an SDM message attribute object with the default values. 03596 03597 The attribute object is allocated and filled in with the default values that 03598 are used by ::lbmsdm_msg_t objects. 03599 03600 \param Attributes Pointer to a pointer to an SDM message attribute structure. 03601 Will be filled in by this function to point to the newly created 03602 ::lbmsdm_msg_attr_t object. 03603 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03604 */ 03605 LBMSDMExpDLL int lbmsdm_msg_attr_create(lbmsdm_msg_attr_t * * Attributes); 03606 03607 /*! \brief Delete an SDM message attribute object. 03608 03609 The attribute object is cleaned up and deleted. 03610 03611 \param Attributes Pointer to an SDM message attribute structure as returned 03612 by ::lbmsdm_msg_attr_create or ::lbmsdm_msg_attr_dup. 03613 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03614 */ 03615 LBMSDMExpDLL int lbmsdm_msg_attr_delete(lbmsdm_msg_attr_t * Attributes); 03616 03617 /*! \brief Duplicate an SDM message attribute object. 03618 03619 A new attribute object is created as a copy of an existing object. 03620 03621 \param Attributes Pointer to a pointer to an SDM message attribute structure. 03622 Will be filled in by this function to point to the newly created 03623 ::lbmsdm_msg_attr_t object. 03624 \param Original Pointer to an SDM message attribute structure as returned 03625 by ::lbmsdm_msg_attr_create or ::lbmsdm_msg_attr_dup, 03626 from which \a Attributes is initialized. 03627 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03628 */ 03629 LBMSDMExpDLL int lbmsdm_msg_attr_dup(lbmsdm_msg_attr_t * * Attributes, lbmsdm_msg_attr_t * Original); 03630 03631 /*! \brief Set an option for the given SDM message attribute object. 03632 03633 Used before the message is created. 03634 NOTE: the attribute object must first be created with ::lbmsdm_msg_attr_create or 03635 ::lbmsdm_msg_attr_dup. 03636 03637 \param Attributes Pointer to an SDM message attribute structure. 03638 \param Option String containing the option name. 03639 \param Value Pointer to the option value structure. 03640 The structure of the option value is specific to the option itself. 03641 \param Length Length (in bytes) of the \Value structure. 03642 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03643 */ 03644 LBMSDMExpDLL int lbmsdm_msg_attr_setopt(lbmsdm_msg_attr_t * Attributes, const char * Option, void * Value, size_t Length); 03645 03646 /*! \brief Set an option for the given SDM message attribute object using a string. 03647 03648 Used before the message is created. 03649 NOTE: the attribute object must first be created with ::lbmsdm_msg_attr_create or 03650 ::lbmsdm_msg_attr_dup. 03651 03652 \param Attributes Pointer to an SDM message attribute structure. 03653 \param Option String containing the option name. 03654 \param Value String containing the option value. 03655 The format of the string is specific to the option itself. 03656 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03657 */ 03658 LBMSDMExpDLL int lbmsdm_msg_attr_str_setopt(lbmsdm_msg_attr_t * Attributes, const char * Option, const char * Value); 03659 03660 /*! \brief Retrieve the value of an option for the given SDM message attribute. 03661 03662 \param Attributes Pointer to an SDM message attribute structure. 03663 \param Option String containing the option name. 03664 \param Value Pointer to the option value structure to be filled. 03665 The structure of the option value is specific to the option itself. 03666 \param Length Length (in bytes) of the \a Value structure when passed in. 03667 Upon return, this is set to the actual size of the filled-in structure. 03668 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03669 */ 03670 LBMSDMExpDLL int lbmsdm_msg_attr_getopt(lbmsdm_msg_attr_t * Attributes, const char * Option, void * Value, size_t * Length); 03671 03672 /*! \brief Retrieve the value of an option for the given SDM message attribute as a string. 03673 03674 \param Attributes Pointer to an SDM message attribute structure. 03675 \param Option String containing the option name. 03676 \param Value Pointer to the string to be filled in. 03677 \param Length Maximum length (in bytes) of the \a Value string when passed in. 03678 Upon return, this is set to the size of the formatted string. 03679 \return ::LBMSDM_SUCCESS if successful, ::LBMSDM_FAILURE otherwise. 03680 */ 03681 LBMSDMExpDLL int lbmsdm_msg_attr_str_getopt(lbmsdm_msg_attr_t * Attributes, const char * Option, char * Value, size_t * Length); 03682 03683 #if defined(__cplusplus) 03684 } 03685 #endif 03686 03687 #endif 03688