lbmmon.h

Go to the documentation of this file.
00001 /** \file lbmmon.h
00002         \brief Ultra Messaging (UM) Monitoring API
00003         \author David K. Ameiss - Informatica Corporation 
00004         \version $Id: //UMprod/REL_6_7_1/29West/lbm/src/mon/lbm/lbmmon.h#1 $
00005         
00006         The Ultra Messaging (UM) Monitoring API Description. Included
00007         are types, constants, and functions related to the API. Contents are
00008         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) 2006-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 Monitoring API provides a framework to allow the convenient
00031         gathering of LBM statistics.
00032 
00033 
00034 */
00035 
00036 /** \page lbmmon_examples LBMMON Example source code
00037 
00038         Select one of the following for LBMMON example source code.
00039 
00040         - \subpage lbmmon_lbm_transport "LBMMON LBM transport module"
00041         - \subpage lbmmon_udp_transport "LBMMON UDP transport module"
00042         - \subpage lbmmon_csv_format "LBMMON CSV format module"
00043         - \subpage lbmmon_lbmsnmp_transport "LBMMON LBMSNMP transport module"
00044         
00045         \page lbmmon_lbm_transport LBMMON LBM transport module
00046 
00047         - \subpage lbmmontrlbm_h_page "lbmmontrlbm.h"
00048         - \subpage lbmmontrlbm_c_page "lbmmontrlbm.c"
00049 
00050         \page lbmmontrlbm_h_page Source code for lbmmontrlbm.h
00051 
00052         \include lbmmontrlbm.exh
00053 
00054         \page lbmmontrlbm_c_page Source code for lbmmontrlbm.c
00055 
00056         \include lbmmontrlbm.c
00057 
00058         \page lbmmon_udp_transport LBMMON UDP transport module
00059 
00060         - \subpage lbmmontrudp_h_page "lbmmontrudp.h"
00061         - \subpage lbmmontrudp_c_page "lbmmontrudp.c"
00062 
00063         \page lbmmontrudp_h_page Source code for lbmmontrudp.h
00064 
00065         \include lbmmontrudp.exh
00066 
00067         \page lbmmontrudp_c_page Source code for lbmmontrudp.c
00068 
00069         \include lbmmontrudp.c
00070 
00071         \page lbmmon_csv_format LBMMON CSV format module
00072 
00073         - \subpage lbmmonfmtcsv_h_page "lbmmonfmtcsv.h"
00074         - \subpage lbmmonfmtcsv_c_page "lbmmonfmtcsv.c"
00075 
00076         \page lbmmonfmtcsv_h_page Source code for lbmmonfmtcsv.h
00077         \include lbmmonfmtcsv.exh
00078 
00079         \page lbmmonfmtcsv_c_page Source code for lbmmonfmtcsv.c
00080         \include lbmmonfmtcsv.c
00081         
00082         \page lbmmon_lbmsnmp_transport LBMMON LBMSNMP transport module
00083 
00084         - \subpage lbmmontrlbmsnmp_h_page "lbmmontrlbmsnmp.h"
00085         - \subpage lbmmontrlbmsnmp_c_page "lbmmontrlbmsnmp.c"
00086 
00087         \page lbmmontrlbmsnmp_h_page Source code for lbmmontrlbmsnmp.h
00088 
00089         \include lbmmontrlbmsnmp.exh
00090 
00091         \page lbmmontrlbmsnmp_c_page Source code for lbmmontrlbmsnmp.c
00092 
00093         \include lbmmontrlbmsnmp.c
00094 
00095 */
00096 
00097 #ifndef LBMMON_H
00098 #define LBMMON_H
00099 
00100 #include <stdlib.h>
00101 #ifdef _WIN32
00102         #include <winsock2.h>
00103 #endif
00104 #include <lbm/lbm.h>
00105 
00106 #if defined(__cplusplus)
00107 extern "C" {
00108 #endif /* __cplusplus */
00109 
00110 /*! Base value for LBMMON error codes. */
00111 #define LBMMON_ERROR_BASE 4096
00112 /*! lbmmon_errnum() value. An invalid argument was passed. */
00113 #define LBMMON_EINVAL (LBMMON_ERROR_BASE + 1)
00114 /*! lbmmon_errnum() value. Out of memory. */
00115 #define LBMMON_ENOMEM (LBMMON_ERROR_BASE + 2)
00116 /*! lbmmon_errnum() value. A call to a module function failed. */
00117 #define LBMMON_EMODFAIL (LBMMON_ERROR_BASE + 3)
00118 /*! lbmmon_errnum() value. A call to an LBM function failed. */
00119 #define LBMMON_ELBMFAIL (LBMMON_ERROR_BASE + 4)
00120 /*! lbmmon_errnum() value. Insufficient resources. */
00121 #define LBMMON_EAGAIN (LBMMON_ERROR_BASE + 5)
00122 /*! lbmmon_errnum() value. Resource already registered. */
00123 #define LBMMON_EALREADY (LBMMON_ERROR_BASE + 6)
00124 /*! lbmmon_errnum() value. Internal operation error. */
00125 #define LBMMON_EOP (LBMMON_ERROR_BASE + 7)
00126 
00127 /*! Packet signature value */
00128 #define LBMMON_PACKET_SIGNATURE 0x1b33041b
00129 
00130 /*! Packet contains source statistics */
00131 #define LBMMON_PACKET_TYPE_SOURCE 0
00132 /*! Packet contains receiver statistics */
00133 #define LBMMON_PACKET_TYPE_RECEIVER 1
00134 /*! Packet contains event queue statistics */
00135 #define LBMMON_PACKET_TYPE_EVENT_QUEUE 2
00136 /*! Packet contains context statistics */
00137 #define LBMMON_PACKET_TYPE_CONTEXT 3
00138 /*! Packet contains receiver topic statistics. */
00139 #define LBMMON_PACKET_TYPE_RECEIVER_TOPIC 4
00140 /*! Packet contains wildcard receiver statistics. */
00141 #define LBMMON_PACKET_TYPE_WILDCARD_RECEIVER 5
00142 
00143 /*!     \brief Statistics packet header layout.
00144 
00145         A statistics packet consists of four fixed-length and fixed-position fields,
00146         as documented below.
00147         It is followed by two variable-length fields.
00148         The option block is located at packet + sizeof(lbmmon_packet_hdr_t), and is
00149         mOptionBlockLength (when properly interpreted) bytes in length (which may be zero).
00150         The statistics data block is located immediately following the option block.
00151 */
00152 typedef struct lbmmon_packet_hdr_t_stct
00153 {
00154         /*! Packet signature in network order. Must be ::LBMMON_PACKET_SIGNATURE. */
00155         lbm_uint_t mSignature;
00156         /*! Type of statistics, in network order. See LBMMON_PACKET_TYPE_*. */
00157         lbm_ushort_t mType;
00158         /*! Length of optional, variable-length attribute block in network order. */
00159         lbm_ushort_t mAttributeBlockLength;
00160         /*! Length of variable-length statistics data in network order. */
00161         lbm_ushort_t mDataLength;
00162         /*! Filler to assure proper alignment of the structure. */
00163         lbm_ushort_t mFiller;
00164 } lbmmon_packet_hdr_t;
00165 
00166 /*!     \brief Statistics attribute block layout.
00167         Associated with each statistics message is a set of optional attributes.
00168         Any attributes present will immediately follow the packet header.
00169 */
00170 typedef struct lbmmon_attr_block_t_stct
00171 {
00172         /*! Number of attribute entries in network order. */
00173         lbm_ushort_t mEntryCount;
00174         /*! Total length of the attribute block in network order. */
00175         lbm_ushort_t mEntryLength;
00176 } lbmmon_attr_block_t;
00177 
00178 /*! Attribute block entry contains the sender IPV4 address. */
00179 #define LBMMON_ATTR_SENDER_IPV4 0
00180 /*! Attribute block entry contains the timestamp. */
00181 #define LBMMON_ATTR_TIMESTAMP 1
00182 /*! Attribute block entry contains the application source ID string. */
00183 #define LBMMON_ATTR_APPSOURCEID 2
00184 /*! Attribute block entry contains the format module ID. */
00185 #define LBMMON_ATTR_FORMAT_MODULEID 3
00186 /*! Attribute block contains the object ID. */
00187 #define LBMMON_ATTR_OBJECTID 4
00188 /*! Attribute block entry contains the context ID.
00189         @deprecated Use ::LBMMON_ATTR_OBJECTID instead.
00190 */
00191 #define LBMMON_ATTR_CONTEXTID LBMMON_ATTR_OBJECTID
00192 /*! Attribute block entry contains the process ID. */
00193 #define LBMMON_ATTR_PROCESSID 5
00194 /*!
00195         Attribute block entry contains the source flag. See LBMMON_ATTR_SOURCE_* for possible values.
00196         Used to distinguish between MIM source/receiver statistics and normal transport
00197         source/receiver statistics.
00198 */
00199 #define LBMMON_ATTR_SOURCE 6
00200 /*! Attribute block entry contains the context instance. */
00201 #define LBMMON_ATTR_CTXINST 7
00202 /*! Attribute block entry contains the domain ID. */
00203 #define LBMMON_ATTR_DOMAINID 8
00204 
00205 /*! Source/receiver statistics are from a normal transport session. */
00206 #define LBMMON_ATTR_SOURCE_NORMAL 0
00207 /*! Source/receiver statistics are from a MIM transport session. */
00208 #define LBMMON_ATTR_SOURCE_IM 1
00209 
00210 /*!     \brief Statistics attribute entry layout.
00211         Each attribute entry within the attributes block consists of an entry header,
00212         followed immediately by the attribute data.
00213 */
00214 typedef struct lbmmon_attr_entry_t_stct
00215 {
00216         /*! Attribute type in network order. */
00217         lbm_ushort_t mType;
00218         /*! Length of attribute data for this entry in network order. */
00219         lbm_ushort_t mLength;
00220 } lbmmon_attr_entry_t;
00221 
00222 /*!     \brief Function to initialize a format module.
00223 
00224         This function should perform any initialization required by the format
00225         module.
00226         While, depending on the module, initialization may not be required,
00227         representative tasks include allocating a block of format-specific data,
00228         parsing options from the supplied options string,
00229         and initializing any operating parameters for the module.
00230 
00231         This function is called by lbmmon_sctl_create() and lbmmon_rctl_create().
00232 
00233         \param FormatClientData A pointer which may be filled in (by this function)
00234                 with a pointer to format-specific client data.
00235                 A pointer to the format-specific data is passed to each function in the
00236                 module,
00237                 to be used as the module sees fit.
00238         \param FormatOptions The FormatOptions argument originally passed to
00239                 lbmmon_sctl_create() or lbmmon_rctl_create().
00240         \return Zero if successful, -1 otherwise.
00241                 If -1 is returned,
00242                 no further calls to the format module will be made, and the calling
00243                 function (lbmmon_sctl_create() or lbmmon_rctl_create()) will return -1.
00244 */
00245 typedef int (*lbmmon_format_init_t)(void * * FormatClientData,
00246                                                                         const void * FormatOptions);
00247 
00248 /*!     \brief Function to serialize an lbm_rcv_transport_stats_t structure.
00249 
00250         This function should transform the lbm_rcv_transport_stat_t structure into
00251         a form which can be deserialized by the corresponding
00252         ::lbmmon_rcv_format_deserialize_t function.
00253 
00254         \sa lbmmon_src_format_serialize_t
00255         \sa lbmmon_rcv_format_deserialize_t
00256         \sa lbmmon_src_format_deserialize_t
00257         \param Destination A pointer to a buffer to receive the serialized format
00258                 of the lbm_rcv_transport_stats_t statistics.
00259         \param Size A pointer to a \c size_t.
00260                 On entry,
00261                 it will contain the maximum allowed size of the serialized statistics.
00262                 On exit,
00263                 it must contain the actual size of the serialized statistics.
00264         \param ModuleID A pointer to an \c unsigned \c short,
00265                 into which the module may write a module identification value.
00266                 This value is included in the transmitted packet,
00267                 and may be used by the receiver to verify and differentiate between
00268                 different version of the module (and thus the format of the data it expects).
00269         \param Statistics A pointer to the lbm_rcv_transport_stats_t structure
00270                 to be serialized.
00271         \param FormatClientData A pointer to format-specific client data as
00272                 returned by the ::lbmmon_format_init_t function.
00273         \return Zero if successful, -1 otherwise.
00274                 If -1 is returned,
00275                 the serialized data will not be sent.
00276 */
00277 typedef int (*lbmmon_rcv_format_serialize_t)(char * Destination,
00278                                                                                          size_t * Size,
00279                                                                                          unsigned short * ModuleID,
00280                                                                                          const lbm_rcv_transport_stats_t * Statistics,
00281                                                                                          void * FormatClientData);
00282 
00283 /*!     \brief Function to serialize an lbm_src_transport_stats_t structure.
00284 
00285         \sa lbmmon_rcv_format_serialize_t
00286         \sa lbmmon_rcv_format_deserialize_t
00287         \sa lbmmon_src_format_deserialize_t
00288         \param Destination A pointer to a buffer to receive the serialized format
00289                 of the lbm_src_transport_stats_t statistics.
00290         \param Size A pointer to a size_t.
00291                 On entry,
00292                 it contains the maximum allowed size of the serialized statistics.
00293                 On exit,
00294                 it must contain the actual size of the serialized statistics.
00295         \param ModuleID A pointer to an \c unsigned \c short,
00296                 into which the module may write a module identification value.
00297                 This value is included in the transmitted packet,
00298                 and may be used by the receiver to verify and differentiate between
00299                 different version of the module (and thus the format of the data it expects).
00300         \param Statistics A pointer to an lbm_src_transport_stats_t structure to be
00301                 serialized.
00302         \param FormatClientData A pointer to format-specific client data as
00303                 returned by the ::lbmmon_format_init_t function.
00304         \return Zero if successful, -1 otherwise.
00305                 If -1 is returned,
00306                 the serialized data will not be sent.
00307 */
00308 typedef int (*lbmmon_src_format_serialize_t)(char * Destination,
00309                                                                                          size_t * Size,
00310                                                                                          unsigned short * ModuleID,
00311                                                                                          const lbm_src_transport_stats_t * Statistics,
00312                                                                                          void * FormatClientData);
00313 
00314 /*!     \brief Function to serialize an lbm_event_queue_stats_t structure.
00315 
00316         This function should transform the lbm_event_queue_stats_t structure into
00317         a form which can be deserialized by the corresponding
00318         ::lbmmon_evq_format_deserialize_t function.
00319 
00320         \sa lbmmon_evq_format_deserialize_t
00321         \param Destination A pointer to a buffer to receive the serialized format
00322                 of the lbm_event_queue_stats_t statistics.
00323         \param Size A pointer to a \c size_t.
00324                 On entry,
00325                 it will contain the maximum allowed size of the serialized statistics.
00326                 On exit,
00327                 it must contain the actual size of the serialized statistics.
00328         \param ModuleID A pointer to an \c unsigned \c short,
00329                 into which the module may write a module identification value.
00330                 This value is included in the transmitted packet,
00331                 and may be used by the receiver to verify and differentiate between
00332                 different version of the module (and thus the format of the data it expects).
00333         \param Statistics A pointer to the lbm_event_queue_stats_t structure
00334                 to be serialized.
00335         \param FormatClientData A pointer to format-specific client data as
00336                 returned by the ::lbmmon_format_init_t function.
00337         \return Zero if successful, -1 otherwise.
00338                 If -1 is returned,
00339                 the serialized data will not be sent.
00340 */
00341 typedef int (*lbmmon_evq_format_serialize_t)(char * Destination,
00342                                                                                          size_t * Size,
00343                                                                                          unsigned short * ModuleID,
00344                                                                                          const lbm_event_queue_stats_t * Statistics,
00345                                                                                          void * FormatClientData);
00346 
00347 /*!     \brief Function to serialize an lbm_context_stats_t structure.
00348 
00349         This function should transform the lbm_context_stats_t structure into
00350         a form which can be deserialized by the corresponding
00351         ::lbmmon_ctx_format_deserialize_t function.
00352 
00353         \sa lbmmon_ctx_format_deserialize_t
00354         \param Destination A pointer to a buffer to receive the serialized format
00355                 of the lbm_context_stats_t statistics.
00356         \param Size A pointer to a \c size_t.
00357                 On entry,
00358                 it will contain the maximum allowed size of the serialized statistics.
00359                 On exit,
00360                 it must contain the actual size of the serialized statistics.
00361         \param ModuleID A pointer to an \c unsigned \c short,
00362                 into which the module may write a module identification value.
00363                 This value is included in the transmitted packet,
00364                 and may be used by the receiver to verify and differentiate between
00365                 different version of the module (and thus the format of the data it expects).
00366         \param Statistics A pointer to the lbm_context_stats_t structure
00367                 to be serialized.
00368         \param FormatClientData A pointer to format-specific client data as
00369                 returned by the ::lbmmon_format_init_t function.
00370         \return Zero if successful, -1 otherwise.
00371                 If -1 is returned,
00372                 the serialized data will not be sent.
00373 */
00374 typedef int (*lbmmon_ctx_format_serialize_t)(char * Destination,
00375                                                                                          size_t * Size,
00376                                                                                          unsigned short * ModuleID,
00377                                                                                          const lbm_context_stats_t * Statistics,
00378                                                                                          void * FormatClientData);
00379 
00380 /*!     \brief Function to deserialize a buffer into an
00381         lbm_rcv_transport_stats_t structure.
00382 
00383         Transform a block of data serialized by the ::lbmmon_rcv_format_serialize_t
00384         function into a lbm_rcv_transport_stats_t structure.
00385 
00386         \sa lbmmon_rcv_format_serialize_t
00387         \sa lbmmon_src_format_serialize_t
00388         \sa lbmmon_src_format_deserialize_t
00389         \param Statistics A pointer to an lbm_rcv_transport_stats_t structure into
00390                 which the data is deserialized.
00391         \param Source A pointer to a buffer containing the serialized data.
00392         \param Length The length of the serialized data.
00393         \param ModuleID The module ID received in the packet.
00394                 It may be used to verify and differentiate between different version of
00395                 the module (and thus the format of the data it expects).
00396         \param FormatClientData A pointer to format-specific client data as
00397                 returned by the ::lbmmon_format_init_t function.
00398         \return Zero if successful, -1 otherwise.
00399                 If -1 is returned,
00400                 the deserialized data will not be delivered to the application.
00401 */
00402 typedef int (*lbmmon_rcv_format_deserialize_t)(lbm_rcv_transport_stats_t * Statistics,
00403                                                                                            const char * Source,
00404                                                                                            size_t Length,
00405                                                                                            unsigned short ModuleID,
00406                                                                                            void * FormatClientData);
00407 
00408 /*!     \brief Function to deserialize a buffer into an lbm_src_transport_stats_t
00409         structure.
00410 
00411         \sa lbmmon_rcv_format_serialize_t
00412         \sa lbmmon_src_format_serialize_t
00413         \sa lbmmon_rcv_format_deserialize_t
00414         \param Statistics A pointer to an lbm_src_transport_stats_t structure into
00415                 which the data is deserialized.
00416         \param Source A pointer to a buffer containing the serialized data.
00417         \param Length The length of the serialized data.
00418         \param ModuleID The module ID received in the packet.
00419                 It may be used to verify and differentiate between different version of
00420                 the module (and thus the format of the data it expects).
00421         \param FormatClientData A pointer to format-specific client data as
00422                 returned by the ::lbmmon_format_init_t function.
00423         \return Zero if successful, -1 otherwise.
00424                 If -1 is returned,
00425                 the deserialized data will not be delivered to the application.
00426 */
00427 typedef int (*lbmmon_src_format_deserialize_t)(lbm_src_transport_stats_t * Statistics,
00428                                                                                            const char * Source,
00429                                                                                            size_t Length,
00430                                                                                            unsigned short ModuleID,
00431                                                                                            void * FormatClientData);
00432 
00433 /*!     \brief Function to deserialize a buffer into an
00434         lbm_event_queue_stats_t structure.
00435 
00436         Transform a block of data serialized by the ::lbmmon_evq_format_serialize_t
00437         function into a lbm_event_queue_stats_t structure.
00438 
00439         \sa lbmmon_evq_format_serialize_t
00440         \param Statistics A pointer to an lbm_event_queue_stats_t structure into
00441                 which the data is deserialized.
00442         \param Source A pointer to a buffer containing the serialized data.
00443         \param Length The length of the serialized data.
00444         \param ModuleID The module ID received in the packet.
00445                 It may be used to verify and differentiate between different version of
00446                 the module (and thus the format of the data it expects).
00447         \param FormatClientData A pointer to format-specific client data as
00448                 returned by the ::lbmmon_format_init_t function.
00449         \return Zero if successful, -1 otherwise.
00450                 If -1 is returned,
00451                 the deserialized data will not be delivered to the application.
00452 */
00453 typedef int (*lbmmon_evq_format_deserialize_t)(lbm_event_queue_stats_t * Statistics,
00454                                                                                            const char * Source,
00455                                                                                            size_t Length,
00456                                                                                            unsigned short ModuleID,
00457                                                                                            void * FormatClientData);
00458 
00459 /*!     \brief Function to deserialize a buffer into an
00460         lbm_context_stats_t structure.
00461 
00462         Transform a block of data serialized by the ::lbmmon_ctx_format_serialize_t
00463         function into a lbm_context_stats_t structure.
00464 
00465         \sa lbmmon_ctx_format_serialize_t
00466         \param Statistics A pointer to an lbm_context_stats_t structure into
00467                 which the data is deserialized.
00468         \param Source A pointer to a buffer containing the serialized data.
00469         \param Length The length of the serialized data.
00470         \param ModuleID The module ID received in the packet.
00471                 It may be used to verify and differentiate between different version of
00472                 the module (and thus the format of the data it expects).
00473         \param FormatClientData A pointer to format-specific client data as
00474                 returned by the ::lbmmon_format_init_t function.
00475         \return Zero if successful, -1 otherwise.
00476                 If -1 is returned,
00477                 the deserialized data will not be delivered to the application.
00478 */
00479 typedef int (*lbmmon_ctx_format_deserialize_t)(lbm_context_stats_t * Statistics,
00480                                                                                            const char * Source,
00481                                                                                            size_t Length,
00482                                                                                            unsigned short ModuleID,
00483                                                                                            void * FormatClientData);
00484 
00485 /*!     \brief Function to serialize receiver topic statistics.
00486 
00487         This function should transform the topic, source count, and array of
00488         sources into a form which can be deserialized by the corresponding
00489         ::lbmmon_rcv_topic_format_deserialize_t function.
00490 
00491         \sa lbmmon_rcv_topic_format_deserialize_t
00492         \param Destination A pointer to a buffer to receive the serialized format
00493                 of the lbm_context_stats_t statistics.
00494         \param Size A pointer to a \c size_t.
00495                 On entry,
00496                 it will contain the maximum allowed size of the serialized statistics.
00497                 On exit,
00498                 it must contain the actual size of the serialized statistics.
00499         \param ModuleID A pointer to an \c unsigned \c short,
00500                 into which the module may write a module identification value.
00501                 This value is included in the transmitted packet,
00502                 and may be used by the receiver to verify and differentiate between
00503                 different version of the module (and thus the format of the data it expects).
00504         \param Topic A NUL-terminated string containing the topic.
00505         \param SourceCount The number of sources in the \a Sources array.
00506         \param Sources An array of ::lbm_rcv_topic_stats_t structures containing
00507                 the sources to which the receiver is joined.
00508         \param FormatClientData A pointer to format-specific client data as
00509                 returned by the ::lbmmon_format_init_t function.
00510         \return Zero if successful, -1 otherwise.
00511                 If -1 is returned,
00512                 the serialized data will not be sent.
00513 */
00514 typedef int (*lbmmon_rcv_topic_format_serialize_t)(char * Destination,
00515                                                                                                    size_t * Size,
00516                                                                                                    unsigned short * ModuleID,
00517                                                                                                    const char * Topic,
00518                                                                                                    lbm_ulong_t SourceCount,
00519                                                                                                    const lbm_rcv_topic_stats_t * Sources,
00520                                                                                                    void * FormatClientData);
00521 
00522 /*!     \brief Function to deserialize a buffer into an ::lbm_rcv_topic_stats_t structure.
00523 
00524         Transform a block of data serialized by the ::lbmmon_rcv_topic_format_serialize_t
00525         function into a ::lbm_rcv_topic_stats_t structure.
00526 
00527         \sa lbmmon_rcv_topic_format_deserialize_t
00528         \param Count A pointer to an integer containing the number of elements in the
00529                 \a Statistics array. On exit, it will contain the actual number of elements parsed.
00530         \param Statistics An array of ::lbm_rcv_topic_stats_t elements into which is written the
00531                 actual deserialized data.
00532         \param Source A pointer to a buffer containing the serialized data.
00533         \param Length The length of the serialized data.
00534         \param ModuleID The module ID received in the packet.
00535                 It may be used to verify and differentiate between different version of
00536                 the module (and thus the format of the data it expects).
00537         \param FormatClientData A pointer to format-specific client data as
00538                 returned by the ::lbmmon_format_init_t function.
00539         \return Zero if successful, -2 if \a Count is not large enough for all elements, -1 otherwise.
00540                 If -2 is returned, \a Count will contain the number of elements required.
00541                 If -1 is returned,
00542                 the deserialized data will not be delivered to the application.
00543 */
00544 typedef int (*lbmmon_rcv_topic_format_deserialize_t)(size_t * Count,
00545                                                                                                          lbm_rcv_topic_stats_t * Statistics,
00546                                                                                                          const char * Source,
00547                                                                                                          size_t Length,
00548                                                                                                          unsigned short ModuleID,
00549                                                                                                          void * FormatClientData);
00550 
00551 /*!     \brief Function to serialize wildcard receiver statistics.
00552 
00553         This function should transform the lbm_wildcard_receiver_stats_t structure into
00554         a form which can be deserialized by the corresponding
00555         ::lbmmon_wildcard_rcv_format_deserialize function.
00556 
00557         \sa lbmmon_wildcard_rcv_format_deserialize_t
00558         \param Destination A pointer to a buffer to receive the serialized format
00559                 of the lbm_wildcard_rcv_stats_t statistics.
00560         \param Size A pointer to a \c size_t.
00561                 On entry,
00562                 it will contain the maximum allowed size of the serialized statistics.
00563                 On exit,
00564                 it must contain the actual size of the serialized statistics.
00565         \param ModuleID A pointer to an \c unsigned \c short,
00566                 into which the module may write a module identification value.
00567                 This value is included in the transmitted packet,
00568                 and may be used by the receiver to verify and differentiate between
00569                 different version of the module (and thus the format of the data it expects).
00570         \param Statistics A pointer to an lbm_wildcard_rcv_stats_t structure to
00571                 be serialized.
00572         \param FormatClientData A pointer to format-specific client data as
00573                 returned by the ::lbmmon_format_init_t function.
00574         \return Zero if successful, -1 otherwise.
00575                 If -1 is returned,
00576                 the serialized data will not be sent.
00577 */
00578 typedef int (*lbmmon_wildcard_rcv_format_serialize_t)(char * Destination,
00579                                                                                                           size_t * Size,
00580                                                                                                           unsigned short * ModuleID,
00581                                                                                                           const lbm_wildcard_rcv_stats_t * Statistics,
00582                                                                                                           void * FormatClientData);
00583 
00584 /*!     \brief Function to deserialize a buffer into an ::lbm_wildcard_rcv_stats_t structure.
00585 
00586         Transform a block of data serialized by the ::lbmmon_wildcard_rcv_format_serialize_t
00587         function into a ::lbm_wildcard_rcv_stats_t structure.
00588 
00589         \sa lbmmon_wildcard_rcv_format_deserialize_t
00590         \param Statistics A pointer to an lbm_wildcard_rcv_stats_t structure into
00591                 which the data is deserialized.
00592         \param Source A pointer to a buffer containing the serialized data.
00593         \param Length The length of the serialized data.
00594         \param ModuleID The module ID received in the packet.
00595                 It may be used to verify and differentiate between different version of
00596                 the module (and thus the format of the data it expects).
00597         \param FormatClientData A pointer to format-specific client data as
00598                 returned by the ::lbmmon_format_init_t function.
00599         \return Zero if successful, -1 otherwise.
00600                 If -1 is returned,
00601                 the deserialized data will not be delivered to the application.
00602 */
00603 typedef int (*lbmmon_wildcard_rcv_format_deserialize_t)(lbm_wildcard_rcv_stats_t * Statistics,
00604                                                                                                                 const char * Source,
00605                                                                                                                 size_t Length,
00606                                                                                                                 unsigned short ModuleID,
00607                                                                                                                 void * FormatClientData);
00608 
00609 /*!     \brief Function to finish format module processing.
00610 
00611         Perform any required format module cleanup processing.
00612         If format-specific client data was allocated in the ::lbmmon_format_init_t
00613         function,
00614         it should be freed in this function.
00615 
00616         This function is called by lbmmon_sctl_destroy() and lbmmon_rctl_destroy().
00617 
00618         \param FormatClientData A pointer to format-specific client data.
00619                 This pointer should be freed if it was allocated previously.
00620         \return Zero if successful, -1 otherwise.
00621 */
00622 typedef int (*lbmmon_format_finish_t)(void * FormatClientData);
00623 
00624 /*!     \brief Function to return the last error message from a format module.
00625 
00626         \return A string containing a description of the last error encountered by the module.
00627 */
00628 typedef const char * (*lbmmon_format_errmsg_t)(void);
00629 
00630 /*!     \brief Format module function pointer container.
00631 */
00632 typedef struct lbmmon_format_func_t_stct
00633 {
00634         /*! Initialization function. */
00635         lbmmon_format_init_t mInit;
00636         /*! Function to serialize receiver statistics (lbm_rcv_transport_stats_t). */
00637         lbmmon_rcv_format_serialize_t mRcvSerialize;
00638         /*! Function to serialize source statistics (lbm_src_transport_stats_t). */
00639         lbmmon_src_format_serialize_t mSrcSerialize;
00640         /*! Function to deserialize receiver statistics (lbm_rcv_transport_stats_t). */
00641         lbmmon_rcv_format_deserialize_t mRcvDeserialize;
00642         /*! Function to deserialize source statistics (lbm_src_transport_stats_t). */
00643         lbmmon_src_format_deserialize_t mSrcDeserialize;
00644         /*! Format-specific cleanup function. */
00645         lbmmon_format_finish_t mFinish;
00646         /*! Function to return a message describing the last error encountered. */
00647         lbmmon_format_errmsg_t mErrorMessage;
00648         /*! Function to serialize event queue statistics (lbm_event_queue_stats_t). */
00649         lbmmon_evq_format_serialize_t mEvqSerialize;
00650         /*! Function to deserialize event queue statistics (lbm_event_queue_stats_t). */
00651         lbmmon_evq_format_deserialize_t mEvqDeserialize;
00652         /*! Function to serialize context statistics (lbm_context_stats_t). */
00653         lbmmon_ctx_format_serialize_t mCtxSerialize;
00654         /*! Function to deserialize context statistics (lbm_context_stats_t). */
00655         lbmmon_ctx_format_deserialize_t mCtxDeserialize;
00656         /*! Function to serialize receiver topic statistics. */
00657         lbmmon_rcv_topic_format_serialize_t mRcvTopicSerialize;
00658         /*! Function to deserialize receiver topic statistics. */
00659         lbmmon_rcv_topic_format_deserialize_t mRcvTopicDeserialize;
00660         /*! Function to serialize wildcard receiver statistics. */
00661         lbmmon_wildcard_rcv_format_serialize_t mWildcardRcvSerialize;
00662         /*! Function to deserialize wildcard receiver statistics. */
00663         lbmmon_wildcard_rcv_format_deserialize_t mWildcardRcvDeserialize;
00664 } lbmmon_format_func_t;
00665 
00666 /*!     \brief Client callback function to process a received receiver statistics
00667                 packet.
00668 
00669         \param AttributeBlock Pointer to the statistics packet attribute block.
00670         \param Statistics Pointer to the receiver statistics.
00671         \param ClientData Pointer to client-specific data as passed to lbmmon_rctl_create().
00672 */
00673 typedef void (*lbmmon_rcv_statistics_cb)(const void * AttributeBlock,
00674                                                                                  const lbm_rcv_transport_stats_t * Statistics,
00675                                                                                  void * ClientData);
00676 
00677 /*!     \brief A structure that holds the callback information for receiver statistics.
00678 
00679          A structure used with receive controller options to get/set specific callback information.
00680 */
00681 typedef struct lbmmon_rcv_statistics_func_t_stct
00682 {
00683         /*! Receiver statistics callback function. */
00684         lbmmon_rcv_statistics_cb cbfunc;
00685 } lbmmon_rcv_statistics_func_t;
00686 
00687 /*!     \brief Client callback function to process a received source statistics
00688                 packet.
00689 
00690         \param AttributeBlock Pointer to the statistics packet attribute block.
00691         \param Statistics Pointer to the source statistics.
00692         \param ClientData Pointer to client-specific data as passed to lbmmon_rctl_create().
00693 */
00694 typedef void (*lbmmon_src_statistics_cb)(const void * AttributeBlock,
00695                                                                                  const lbm_src_transport_stats_t * Statistics,
00696                                                                                  void * ClientData);
00697 
00698 /*!     \brief A structure that holds the callback information for source statistics.
00699 
00700          A structure used with receive controller options to get/set specific callback information.
00701 */
00702 typedef struct lbmmon_src_statistics_func_t_stct
00703 {
00704         /*! Source statistics callback function. */
00705         lbmmon_src_statistics_cb cbfunc;
00706 } lbmmon_src_statistics_func_t;
00707 
00708 /*!     \brief Client callback function to process a received event queue statistics
00709                 packet.
00710 
00711         \param AttributeBlock Pointer to the statistics packet attribute block.
00712         \param Statistics Pointer to the event queue statistics.
00713         \param ClientData Pointer to client-specific data as passed to lbmmon_rctl_create().
00714 */
00715 typedef void (*lbmmon_evq_statistics_cb)(const void * AttributeBlock,
00716                                                                                  const lbm_event_queue_stats_t * Statistics,
00717                                                                                  void * ClientData);
00718 
00719 /*!     \brief A structure that holds the callback information for event queue statistics.
00720 
00721          A structure used with receive controller options to get/set specific callback information.
00722 */
00723 typedef struct lbmmon_evq_statistics_func_t_stct
00724 {
00725         /*! Event queue statistics callback function. */
00726         lbmmon_evq_statistics_cb cbfunc;
00727 } lbmmon_evq_statistics_func_t;
00728 
00729 /*!     \brief Client callback function to process a received context statistics
00730                 packet.
00731 
00732         \param AttributeBlock Pointer to the statistics packet attribute block.
00733         \param Statistics Pointer to the context statistics.
00734         \param ClientData Pointer to client-specific data as passed to lbmmon_rctl_create().
00735 */
00736 typedef void (*lbmmon_ctx_statistics_cb)(const void * AttributeBlock,
00737                                                                                  const lbm_context_stats_t * Statistics,
00738                                                                                  void * ClientData);
00739 
00740 /*!     \brief A structure that holds the callback information for context statistics.
00741 
00742          A structure used with receive controller options to get/set specific callback information.
00743 */
00744 typedef struct lbmmon_ctx_statistics_func_t_stct
00745 {
00746         /*! Context statistics callback function. */
00747         lbmmon_ctx_statistics_cb cbfunc;
00748 } lbmmon_ctx_statistics_func_t;
00749 
00750 /*!     \brief For internal use only. Client callback function to process a received receiver topic statistics
00751                 packet.
00752 
00753         \param AttributeBlock Pointer to the statistics packet attribute block.
00754         \param Statistics Pointer to the receiver topic statistics.
00755         \param ClientData Pointer to client-specific data as passed to lbmmon_rctl_create().
00756 */
00757 typedef void (*lbmmon_rcv_topic_statistics_cb)(const void * AttributeBlock,
00758                                                                                            const lbm_rcv_topic_stats_t * Statistics,
00759                                                                                            void * ClientData);
00760 
00761 /*!     \brief For internal use only. A structure that holds the callback information for receiver topic statistics.
00762 
00763          A structure used with receive controller options to get/set specific callback information.
00764 */
00765 typedef struct lbmmon_rcv_topic_statistics_func_t_stct
00766 {
00767         /*! Receiver topic statistics callback function. */
00768         lbmmon_rcv_topic_statistics_cb cbfunc;
00769 } lbmmon_rcv_topic_statistics_func_t;
00770 
00771 /*!     \brief For internal use only. Client callback function to process a received wildcard receiver statistics
00772                 packet.
00773 
00774         \param AttributeBlock Pointer to the statistics packet attribute block.
00775         \param Statistics Pointer to the wildcard receiver statistics.
00776         \param ClientData Pointer to client-specific data as passed to lbmmon_rctl_create().
00777 */
00778 typedef void (*lbmmon_wildcard_rcv_statistics_cb)(const void * AttributeBlock,
00779                                                                                                   const lbm_wildcard_rcv_stats_t * Statistics,
00780                                                                                                   void * ClientData);
00781 
00782 /*!     \brief A structure that holds the callback information for wildcard receiver statistics.
00783 
00784          A structure used with receive controller options to get/set specific callback information.
00785 */
00786 typedef struct lbmmon_wildcard_rcv_statistics_func_t_stct
00787 {
00788         /*! Wildcard receiver statistics callback function. */
00789         lbmmon_wildcard_rcv_statistics_cb cbfunc;
00790 } lbmmon_wildcard_rcv_statistics_func_t;
00791 
00792 /*! Receive controller attribute option: Receiver statistics callback. */
00793 #define LBMMON_RCTL_RECEIVER_CALLBACK 0
00794 /*! Receive controller attribute option: Source statistics callback. */
00795 #define LBMMON_RCTL_SOURCE_CALLBACK 1
00796 /*! Receive controller attribute option: Event queue statistics callback. */
00797 #define LBMMON_RCTL_EVENT_QUEUE_CALLBACK 2
00798 /*! Receive controller attribute option: Context statistics callback. */
00799 #define LBMMON_RCTL_CONTEXT_CALLBACK 3
00800 /*! Receive controller attribute option: Receiver topic statistics callback. */
00801 #define LBMMON_RCTL_RECEIVER_TOPIC_CALLBACK 4
00802 /*! Receive controller attribute option: Wildcard receiver statistics callback. */
00803 #define LBMMON_RCTL_WILDCARD_RECEIVER_CALLBACK 5
00804 
00805 /*!     \brief Function to initialize a transport module to serve as a source
00806                 of statistics.
00807 
00808         \param TransportClientData A pointer which may be filled in
00809                 (by this function)
00810                 with a pointer to transport-specific client data.
00811         \param TransportOptions The TransportOptions argument originally passed to
00812                 lbmmon_sctl_create().
00813         \return Zero if successful, -1 otherwise.
00814 */
00815 typedef int (*lbmmon_transport_initsrc_t)(void * * TransportClientData,
00816                                                                                   const void * TransportOptions);
00817 
00818 /*!     \brief Function to initialize a transport module to serve as a receiver
00819                 of statistics.
00820 
00821         \param TransportClientData A pointer which may be filled in
00822                 (by this function)
00823                 with a pointer to transport-specific client data.
00824         \param TransportOptions The TransportOptions argument originally passed to
00825                 lbmmon_rctl_create().
00826         \return Zero if successful, -1 otherwise.
00827 */
00828 typedef int (*lbmmon_transport_initrcv_t)(void * * TransportClientData,
00829                                                                                   const void * TransportOptions);
00830 
00831 /*!     \brief Send a statistics packet.
00832 
00833         \param Data Pointer to the serialized statistics data.
00834         \param Length Length of the serialized statistics data.
00835         \param TransportClientData A pointer to transport-specific client data
00836                 as returned by the ::lbmmon_transport_initsrc_t function.
00837         \return Zero if successful, -1 otherwise.
00838 */
00839 typedef int (*lbmmon_transport_send_t)(const char * Data,
00840                                                                            size_t Length,
00841                                                                            void * TransportClientData);
00842 
00843 /*!     \brief Receive statistics data.
00844 
00845         \param Data Pointer to a buffer into which the received
00846                 (serialized) data is to be placed.
00847         \param Length Pointer to a size_t variable.
00848                 On entry,
00849                 it contains the maximum number of bytes to read.
00850                 On exit,
00851                 it must contain the actual number of bytes read.
00852         \param TimeoutMS Maximum time,
00853                 in milliseconds,
00854                 the function may wait for incoming data before returning a
00855                 timeout indicator.
00856         \param TransportClientData A pointer to transport-specific client data
00857                 as returned by the ::lbmmon_transport_initrcv_t function.
00858         \return Zero if successful, >0 if timeout exceeded, -1 otherwise.
00859 */
00860 typedef int (*lbmmon_transport_receive_t)(char * Data,
00861                                                                                   size_t * Length,
00862                                                                                   unsigned int TimeoutMS,
00863                                                                                   void * TransportClientData);
00864 
00865 /*!     \brief Finish processing for a source transport.
00866 
00867         \param TransportClientData A pointer to transport-specific client data
00868                 as returned by the ::lbmmon_transport_initsrc_t function.
00869                 If previously allocated by the ::lbmmon_transport_initsrc_t function,
00870                 it must be freed in this function.
00871         \return Zero if successful, -1 otherwise.
00872 */
00873 typedef int (*lbmmon_transport_finishsrc_t)(void * TransportClientData);
00874 
00875 /*!     \brief Finish processing for a receiver transport.
00876 
00877         \param TransportClientData A pointer to transport-specific client data
00878                 as returned by the ::lbmmon_transport_initrcv_t function.
00879                 If previously allocated by the ::lbmmon_transport_initrcv_t function,
00880                 it must be freed in this function.
00881         \return Zero if successful, -1 otherwise.
00882 */
00883 typedef int (*lbmmon_transport_finishrcv_t)(void * TransportClientData);
00884 
00885 /*!     \brief Function to return the last error message from a transport module.
00886 
00887         \return A string containing a description of the last error encountered by the module.
00888 */
00889 typedef const char * (*lbmmon_transport_errmsg_t)(void);
00890 
00891 /*!     \brief Transport module function pointer container.
00892 */
00893 typedef struct lbmmon_transport_func_t_stct
00894 {
00895         /*! Initialize module as a statistics source. */
00896         lbmmon_transport_initsrc_t mInitSource;
00897         /*! Initialize module as a statistics receiver. */
00898         lbmmon_transport_initrcv_t mInitReceiver;
00899         /*! Send a statistics packet. */
00900         lbmmon_transport_send_t mSend;
00901         /*! Receive statistics data. */
00902         lbmmon_transport_receive_t mReceive;
00903         /*! Finish processing for a source transport. */
00904         lbmmon_transport_finishsrc_t mFinishSource;
00905         /*! Finish processing for a receiver transport. */
00906         lbmmon_transport_finishrcv_t mFinishReceiver;
00907         /*! Function to return a message describing the last error encountered. */
00908         lbmmon_transport_errmsg_t mErrorMessage;
00909 } lbmmon_transport_func_t;
00910 
00911 /*!     \brief LBM Monitoring Source Controller object (opaque).
00912 */
00913 struct lbmmon_sctl_t_stct;
00914 typedef struct lbmmon_sctl_t_stct lbmmon_sctl_t;
00915 
00916 /*!     \brief LBM Monitoring Receiver Controller Attribute object (opaque).
00917 */
00918 struct lbmmon_rctl_attr_t_stct;
00919 typedef struct lbmmon_rctl_attr_t_stct lbmmon_rctl_attr_t;
00920 
00921 /*!     \brief LBM Monitoring Receiver Controller object (opaque).
00922 */
00923 struct lbmmon_rctl_t_stct;
00924 typedef struct lbmmon_rctl_t_stct lbmmon_rctl_t;
00925 
00926 /*!     \brief Create an LBM Monitoring Source Controller.
00927 
00928         This creates an instance of an LBM Monitoring Source Controller.
00929 
00930         \param Control A pointer to a pointer to an LBM Monitoring Source Control
00931                 object.
00932                 It will be filled in by this function to point to the newly created
00933                 ::lbmmon_sctl_t object.
00934         \param Format A pointer to an lbmmon_format_func_t object which has been
00935                 filled in with the appropriate function pointers.
00936         \param FormatOptions A block of data which is passed to the format module's
00937                 initialization function.
00938                 This may be used to pass configuration options to the format module.
00939         \param Transport A pointer to an lbmmon_transport_func_t object which has
00940                 been filled in with the appropriate function pointers.
00941         \param TransportOptions A block of data which is passed to the transport
00942                 module's initialization function.
00943                 This may be used to pass configuration options to the transport module.
00944         \return 0 if successful, -1 otherwise.
00945 */
00946 LBMExpDLL int lbmmon_sctl_create(lbmmon_sctl_t * * Control,
00947                                                                  const lbmmon_format_func_t * Format,
00948                                                                  const void * FormatOptions,
00949                                                                  const lbmmon_transport_func_t * Transport,
00950                                                                  const void * TransportOptions);
00951 
00952 /*!     \brief Create an LBM Monitoring Receive Controller attribute object.
00953 
00954         The attribute object is created and initialized.
00955 
00956         \param Attributes A pointer to a pointer to an LBMMON receive controller attribute
00957                 structure. Will be filled in by the function to point to the newly created
00958                 lbmmon_rctl_attr_t object.
00959         \return 0 if successful, -1 otherwise.
00960 */
00961 LBMExpDLL int lbmmon_rctl_attr_create(lbmmon_rctl_attr_t * * Attributes);
00962 
00963 /*!     \brief Delete an LBM Monitoring Receive Controller attribute object.
00964 
00965         The attribute object is cleaned up and deleted.
00966 
00967         \param Attributes A pointer to an LBMMON receive controller attribute
00968                 structure as created by ::lbmmon_rctl_attr_create.
00969         \return 0 if successful, -1 otherwise.
00970 */
00971 LBMExpDLL int lbmmon_rctl_attr_delete(lbmmon_rctl_attr_t * Attributes);
00972 
00973 /*!
00974         \brief Set an LBMMON receive controller attribute option value.
00975 
00976         \param Attributes The attributes object to set the option value for.
00977         \param Option The option to set. See LBMMON_RCTL_ATTR_*.
00978         \param Value The value to set for the option.
00979         \param Length The size (in bytes) of \a Value.
00980         \return 0 if successful, -1 otherwise.
00981  */
00982 LBMExpDLL int lbmmon_rctl_attr_setopt(lbmmon_rctl_attr_t * Attributes, int Option, void * Value, size_t Length);
00983 
00984 /*!
00985         \brief Get an LBMMON receive controller attribute option value.
00986 
00987         \param Attributes The attributes object to get the option value for.
00988         \param Option The option to get. See LBMMON_RCTL_ATTR_*.
00989         \param Value Pointer to the option value structure to be filled.
00990         \param Length Length (in bytes) of the \a Value structure when passed in.
00991                 Upon return, this is set to the actual size of the \a Value structure filled in.
00992         \return 0 if successful, -1 otherwise.
00993  */
00994 LBMExpDLL int lbmmon_rctl_attr_getopt(lbmmon_rctl_attr_t * Attributes, int Option, void * Value, size_t * Length);
00995 
00996 /*!     \brief Create an LBM Monitoring Receive Controller.
00997 
00998         This creates an instance of an LBM Monitoring Receive Controller.
00999 
01000         \param Control A pointer to a pointer to an LBM Monitoring Receive Control
01001                 object.
01002                 Will be filled in by this function to point to the newly created
01003                 ::lbmmon_rctl_t object.
01004         \param Format A pointer to an lbmmon_format_func_t object which has been
01005                 filled in with the appropriate function pointers.
01006         \param FormatOptions A block of data which is passed to the format module's
01007                 initialization function.
01008                 This may be used to pass configuration options to the format module.
01009         \param Transport A pointer to an lbmmon_transport_func_t object which has
01010                 been filled in with the appropriate function pointers.
01011         \param TransportOptions A block of data which is passed to the transport
01012                 module's initialization function.
01013                 This may be used to pass configuration options to the transport module.
01014         \param Attributes A pointer to an ::lbmmon_rctl_attr_t object which has been
01015                 filled in with the appropriate options.
01016         \param ClientData A pointer to a block of memory which can be used for
01017                 client-specific data. It is passed to all callback functions.
01018         \return 0 if successful, -1 otherwise.
01019 */
01020 LBMExpDLL int lbmmon_rctl_create(lbmmon_rctl_t * * Control,
01021                                                                  const lbmmon_format_func_t * Format,
01022                                                                  const void * FormatOptions,
01023                                                                  const lbmmon_transport_func_t * Transport,
01024                                                                  const void * TransportOptions,
01025                                                                  lbmmon_rctl_attr_t * Attributes,
01026                                                                  void * ClientData);
01027 
01028 /*!     \brief Register a context for monitoring.
01029 
01030         When a context is monitored,
01031         statistics are gathered for all transports on that context,
01032         broken out by transport.
01033         Monitoring may be done at regular intervals,
01034         specified by the \a Seconds parameter.
01035         As an alternative,
01036         passing zero for \a Seconds will not automatically monitor the context,
01037         but instead require an explicit call to lbmmon_sctl_sample().
01038 
01039         If monitoring is to be used as a form of heartbeat,
01040         the preferred method is to call lbmmon_sctl_sample() from a context
01041         thread or event queue timer callback.
01042         This ensures that the object actually processing the messages is the
01043         one generating the monitoring statistics,
01044         guaranteeing that it is truly acting as a heartbeat mechanism.
01045 
01046         \param Control Pointer to an ::lbmmon_sctl_t which is to be used to
01047                 monitor the context.
01048         \param Context Pointer to an ::lbm_context_t which will be monitored.
01049         \param ApplicationSourceID Null-terminated string containing an
01050                 application-specified source identifier.
01051                 If a NULL pointer or an empty string is passed,
01052                 the application name will be used.
01053         \param Seconds Interval (in seconds) at which monitoring information
01054                 will be gathered and sent.
01055                 If zero,
01056                 the context will not be automatically monitored,
01057                 but instead will be monitored upon a call to lbmmon_ctl_sample().
01058         \return Zero if successful, -1 otherwise.
01059 */ 
01060 LBMExpDLL int lbmmon_context_monitor(lbmmon_sctl_t * Control,
01061                                                                          lbm_context_t * Context,
01062                                                                          const char * ApplicationSourceID,
01063                                                                          unsigned int Seconds);
01064 
01065 /*!     \brief Terminate monitoring for a context.
01066 
01067         Unregister a context to prevent further monitoring of that context.
01068 
01069         \param Control Pointer to an ::lbmmon_sctl_t which is used to monitor
01070                 the context.
01071         \param Context Pointer to an previously registered ::lbm_context_t.
01072         \return Zero if successful, -1 otherwise.
01073 */
01074 LBMExpDLL int lbmmon_context_unmonitor(lbmmon_sctl_t * Control,
01075                                                                            lbm_context_t * Context);
01076 
01077 /*!     \brief Register a source for monitoring.
01078 
01079         Monitoring may be done at regular intervals,
01080         specified by the \a Seconds parameter.
01081         As an alternative,
01082         passing zero for \a Seconds will not automatically monitor the source,
01083         but instead require an explicit call to lbmmon_sctl_sample().
01084 
01085         If monitoring is to be used as a form of heartbeat,
01086         the preferred method is to call lbmmon_ctl_sample() from a context
01087         thread or event queue timer callback.
01088         This ensures that the object actually processing the messages is the
01089         one generating the monitoring statistics,
01090         guaranteeing that it is truly acting as a heartbeat mechanism.
01091 
01092         \param Control Pointer to an ::lbmmon_sctl_t which is to be used to
01093                 monitor the context.
01094         \param Source Pointer to an ::lbm_src_t which will be monitored.
01095         \param ApplicationSourceID Null-terminated string containing an
01096                 application-specified source identifier.
01097                 If a NULL pointer or an empty string is passed,
01098                 the application name will be used.
01099         \param Seconds Interval (in seconds) at which monitoring information
01100                 will be gathered and sent.
01101                 If zero,
01102                 the source will not be automatically monitored,
01103                 but instead will be monitored upon a call to lbmmon_sctl_sample().
01104         \return Zero if successful, -1 otherwise.
01105 */ 
01106 LBMExpDLL int lbmmon_src_monitor(lbmmon_sctl_t * Control,
01107                                                                  lbm_src_t * Source,
01108                                                                  const char * ApplicationSourceID,
01109                                                                  unsigned int Seconds);
01110 
01111 /*!     \brief Terminate monitoring for a source.
01112 
01113         Unregister a source to prevent further monitoring of that source.
01114 
01115         \param Control Pointer to an ::lbmmon_sctl_t which is used to monitor
01116                 the context.
01117         \param Source Pointer to an previously registered ::lbm_src_t.
01118         \return Zero if successful, -1 otherwise.
01119 */
01120 LBMExpDLL int lbmmon_src_unmonitor(lbmmon_sctl_t * Control,
01121                                                                    lbm_src_t * Source);
01122 
01123 /*!     \brief Register a receiver for monitoring.
01124 
01125         Monitoring may be done at regular intervals,
01126         specified by the \a Seconds parameter.
01127         As an alternative,
01128         passing zero for \a Seconds will not automatically monitor the receiver,
01129         but instead require an explicit call to lbmmon_ctl_sample().
01130 
01131         If monitoring is to be used as a form of heartbeat,
01132         the preferred method is to call lbmmon_ctl_sample() from a context
01133         thread or event queue timer callback.
01134         This ensures that the object actually processing the messages is the
01135         one generating the monitoring statistics,
01136         guaranteeing that it is truly acting as a heartbeat mechanism.
01137 
01138         \param Control Pointer to an ::lbmmon_sctl_t which is to be used to
01139                 monitor the context.
01140         \param Receiver Pointer to an lbm_rcv_t which will be monitored.
01141         \param ApplicationSourceID Null-terminated string containing an
01142                 application-specified source identifier.
01143                 If a NULL pointer or an empty string is passed,
01144                 the application name will be used.
01145         \param Seconds Interval (in seconds) at which monitoring information
01146                 will be gathered and sent.
01147                 If zero, the receiver will not be automatically monitored,
01148                 but instead will be monitored upon a call to lbmmon_sctl_sample().
01149         \return Zero if successful, -1 otherwise.
01150 */ 
01151 LBMExpDLL int lbmmon_rcv_monitor(lbmmon_sctl_t * Control,
01152                                                                  lbm_rcv_t * Receiver,
01153                                                                  const char * ApplicationSourceID,
01154                                                                  unsigned int Seconds);
01155 
01156 /*!     \brief Terminate monitoring for a receiver.
01157 
01158         Unregister a receiver to prevent further monitoring of that receiver.
01159 
01160         \param Control Pointer to an ::lbmmon_sctl_t which is used to monitor
01161                 the context.
01162         \param Receiver Pointer to an previously registered ::lbm_rcv_t.
01163         \return Zero if successful, -1 otherwise.
01164 */
01165 LBMExpDLL int lbmmon_rcv_unmonitor(lbmmon_sctl_t * Control,
01166                                                                    lbm_rcv_t * Receiver);
01167 
01168 /*!     \brief Register an event queue for monitoring.
01169 
01170         Monitoring may be done at regular intervals,
01171         specified by the \a Seconds parameter.
01172         As an alternative,
01173         passing zero for \a Seconds will not automatically monitor the receiver,
01174         but instead require an explicit call to lbmmon_ctl_sample().
01175 
01176         If monitoring is to be used as a form of heartbeat,
01177         the preferred method is to call lbmmon_ctl_sample() from a context
01178         thread or event queue timer callback.
01179         This ensures that the object actually processing the messages is the
01180         one generating the monitoring statistics,
01181         guaranteeing that it is truly acting as a heartbeat mechanism.
01182 
01183         \param Control Pointer to an ::lbmmon_sctl_t which is to be used to
01184                 monitor the context.
01185         \param Receiver Pointer to an lbm_event_queue_t which will be monitored.
01186         \param ApplicationSourceID Null-terminated string containing an
01187                 application-specified source identifier.
01188                 If a NULL pointer or an empty string is passed,
01189                 the application name will be used.
01190         \param Seconds Interval (in seconds) at which monitoring information
01191                 will be gathered and sent.
01192                 If zero, the receiver will not be automatically monitored,
01193                 but instead will be monitored upon a call to lbmmon_sctl_sample().
01194         \return Zero if successful, -1 otherwise.
01195 */ 
01196 LBMExpDLL int lbmmon_evq_monitor(lbmmon_sctl_t * Control,
01197                                                                  lbm_event_queue_t * EventQueue,
01198                                                                  const char * ApplicationSourceID,
01199                                                                  unsigned int Seconds);
01200 
01201 /*!     \brief Terminate monitoring for an event queue.
01202 
01203         Unregister an event queue to prevent further monitoring of that receiver.
01204 
01205         \param Control Pointer to an ::lbmmon_sctl_t which is used to monitor
01206                 the context.
01207         \param EventQueue Pointer to an previously registered ::lbm_event_queue_t.
01208         \return Zero if successful, -1 otherwise.
01209 */
01210 LBMExpDLL int lbmmon_evq_unmonitor(lbmmon_sctl_t * Control,
01211                                                                    lbm_event_queue_t * EventQueue);
01212 
01213 /*!     \brief Destroy a source monitoring controller.
01214 
01215         Destroys a monitoring controller. Any contexts, sources, or receivers
01216         currently registered to the controller will be automatically unregistered.
01217 
01218         \param Control Pointer to an ::lbmmon_sctl_t to be destroyed.
01219         \return Zero if successful, -1 otherwise.
01220 */
01221 LBMExpDLL int lbmmon_sctl_destroy(lbmmon_sctl_t * Control);
01222 
01223 /*!     \brief Destroy a statistics receive controller.
01224 
01225         Destroys a monitoring controller.
01226 
01227         \param Control Pointer to an ::lbmmon_rctl_t to be destroyed.
01228         \return Zero if successful, -1 otherwise.
01229 */
01230 LBMExpDLL int lbmmon_rctl_destroy(lbmmon_rctl_t * Control);
01231 
01232 /*!     \brief Gather statistics for on-demand objects.
01233 
01234         \param Control Pointer to an existing ::lbmmon_sctl_t controller.
01235         \return Zero if successful, -1 otherwise.
01236 */      
01237 LBMExpDLL int lbmmon_sctl_sample(lbmmon_sctl_t * Control);
01238 
01239 /*!     \brief Extended gather statistics for on-demand objects.
01240 
01241         \param Control Pointer to an existing ::lbmmon_sctl_t controller.
01242         \param ApplicationSourceID Null-terminated string containing an
01243                 application-specified source identifier.
01244                 This overrides any application source ID passed to any of
01245                 the lbmmon_*_monitor() functions for this call only.
01246                 If a NULL pointer or an empty string is passed,
01247                 the original application source ID will be used.
01248         \return Zero if successful, -1 otherwise.
01249 */      
01250 LBMExpDLL int lbmmon_sctl_sample_ex(lbmmon_sctl_t * Control, const char * ApplicationSourceID);
01251 
01252 /*!     \brief Retrieve the IPV4 sender address attribute from the statistics
01253                 attribute block.
01254 
01255         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01256         \param Address Pointer to a 32-bit integer to receive the IPV4 address in network
01257                 order.
01258         \return 0 if successful, -1 if the attribute does not exist.
01259 */
01260 LBMExpDLL int lbmmon_attr_get_ipv4sender(const void * AttributeBlock,
01261                                                                                  lbm_uint_t * Address);
01262 
01263 /*!     \brief Retrieve the timestamp attribute from the statistics attribute block.
01264 
01265         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01266         \param Timestamp Pointer to a \c time_t to receive the timestamp.
01267         \return 0 if successful, -1 if the attribute does not exist.
01268 */
01269 LBMExpDLL int lbmmon_attr_get_timestamp(const void * AttributeBlock,
01270                                                                                 time_t * Timestamp);
01271 
01272 /*!     \brief Retrieve the application source ID attribute from the statistics attribute block.
01273 
01274         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01275         \param ApplicationSourceID Pointer to a buffer to receive the application source ID as
01276                 a null-terminated string.
01277         \param Length Maximum length of \a ApplicationSourceID
01278         \return 0 if successful, -1 if the attribute does not exist.
01279 */
01280 LBMExpDLL int lbmmon_attr_get_appsourceid(const void * AttributeBlock,
01281                                                                                   char * ApplicationSourceID,
01282                                                                                   size_t Length);
01283 
01284 /*!     \brief Retrieve the object ID attribute from the statistics attribute block.
01285 
01286         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01287         \param ObjectID Pointer to a variable to receive the object ID.
01288         \return 0 if successful, -1 if the attribute does not exist.
01289 */
01290 LBMExpDLL int lbmmon_attr_get_objectid(const void * AttributeBlock,
01291                                                                            lbm_ulong_t * ObjectID);
01292 
01293 /*!     \brief Retrieve the context ID attribute from the statistics attribute block.
01294 
01295         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01296         \param ContextID Pointer to a variable to receive the context ID.
01297         \return 0 if successful, -1 if the attribute does not exist.
01298         \deprecated Use ::lbmmon_attr_get_objectid instead.
01299 */
01300 LBMExpDLL int lbmmon_attr_get_contextid(const void * AttributeBlock,
01301                                                                                 lbm_ulong_t * ContextID);
01302 
01303 /*!     \brief Retrieve the process ID attribute from the statistics attribute block.
01304 
01305         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01306         \param ProcessID Pointer to a variable to receive the process ID.
01307         \return 0 if successful, -1 if the attribute does not exist.
01308 */
01309 LBMExpDLL int lbmmon_attr_get_processid(const void * AttributeBlock,
01310                                                                                 lbm_ulong_t * ProcessID);
01311 
01312 /*!     \brief Retrieve the source attribute from the statistics attribute block.
01313 
01314         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01315         \param Source Pointer to a variable to receive the source flag.
01316         \return 0 if successful, -1 if the attribute does not exist.
01317 */
01318 LBMExpDLL int lbmmon_attr_get_source(const void * AttributeBlock,
01319                                                                          lbm_ulong_t * Source);
01320 
01321 /*!     \brief For internal use only. Retrieve the context instance attribute from the statistics attribute block.
01322 
01323         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01324         \param ContextInstance Pointer to a buffer to receive the context instance.
01325         \param Length Maximum length of \a ContextInstance.
01326         \return 0 if successful, -1 if the attribute does not exist.
01327 */
01328 LBMExpDLL int lbmmon_attr_get_ctxinst(const void * AttributeBlock,
01329                                                                           lbm_uint8_t * ContextInstance,
01330                                                                           size_t Length);
01331 
01332 /*!     \brief For internal use only. Retrieve the domain ID attribute from the statistics attribute block.
01333 
01334         \param AttributeBlock Pointer to the attribute block as passed to the callback function.
01335         \param DomainID Pointer to a variable to receive the domain ID.
01336         \return 0 if successful, -1 if the attribute does not exist.
01337 */
01338 LBMExpDLL int lbmmon_attr_get_domainid(const void * AttributeBlock,
01339                                                                            lbm_uint32_t * DomainID);
01340 
01341 /*!     \brief Retrieve the error number for the last error encountered.
01342 
01343         \return The last error encountered. See LBMMON_ERR_*.
01344 */
01345 LBMExpDLL int lbmmon_errnum(void);
01346 
01347 /*!     \brief Retrieve the error message for the last error encountered.
01348 
01349         \return A pointer to a static character array containing the last error message.
01350 */
01351 LBMExpDLL const char * lbmmon_errmsg(void);
01352 
01353 /*!     \brief Retrieve the next key/value pair from a semicolon-separated list.
01354 
01355         This is a convenience utility function to facilitate processing of a
01356         semicolon-separated list of key/value pairs. Each pair is of the form "key=value".
01357         \param String A pointer to the unprocessed part of the semicolon-separated list.
01358         \param Key Pointer to a character string into which is written the null-terminated key.
01359         \param KeySize Maximum length of \a Key.
01360         \param Value Pointer to a character string into which is written the null-terminated value.
01361         \param ValueSize Maximum length of \a Value.
01362         \return \c NULL if no key/value pair is found.
01363                 Otherwise a pointer to the remainder of the string, to be passed to subsequent
01364                 calls to lbmmon_next_key_value_pair().
01365 */
01366 const char * lbmmon_next_key_value_pair(const char * String,
01367                                                                                 char * Key,
01368                                                                                 size_t KeySize,
01369                                                                                 char * Value,
01370                                                                                 size_t ValueSize);
01371 
01372 #if defined(__cplusplus)
01373 }
01374 #endif /* __cplusplus */
01375 
01376 #include <lbm/lbmmonfmtcsv.h>
01377 #include <lbm/lbmmontrlbm.h>
01378 #include <lbm/lbmmontrudp.h>
01379 #include <lbm/lbmmontrlbmsnmp.h>
01380 
01381 #endif
01382 

Generated on Wed Jul 16 15:57:56 2014 for LBM API by  doxygen 1.4.7