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