lbmsdm.h

Go to the documentation of this file.
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 

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