lbm.h

Go to the documentation of this file.
00001 /**     \mainpage Informatica Ultra Messaging (UM) API
00002         \image html UM-logo.png
00003         \par
00004         <a href="globals.html">Browse UM API Functions and constants</a>
00005 */
00006 /** \file lbm.h
00007         \brief Ultra Messaging (UM) API
00008         \author Todd L. Montgomery - Informatica Corporation.
00009         \version $Id: //UMprod/REL_6_7_1/29West/lbm/src/lib/lbm/lbm.h#2 $
00010 
00011         The Ultra Messaging (UM) API Description. Included are
00012         types, constants, and functions related to the API. Contents are
00013         subject to change.
00014 
00015         All of the documentation and software included in this and any
00016         other Informatica Ultra Messaging Releases
00017         Copyright (C) Informatica. All rights reserved.
00018 
00019         Redistribution and use in source and binary forms, with or without
00020         modification, are permitted only as covered by the terms of a
00021         valid software license agreement with Informatica.
00022 
00023         Copyright (C) 2004-2014, Informatica Corporation. All Rights Reserved.
00024 
00025         THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES
00026         EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF
00027         NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
00028         PURPOSE.  INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE
00029         UNINTERRUPTED OR ERROR-FREE.  INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE
00030         LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR
00031         INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE
00032         TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF
00033         THE LIKELIHOOD OF SUCH DAMAGES.
00034 */
00035 #ifndef LBM_H
00036 #define LBM_H
00037 
00038 #if defined(__cplusplus)
00039 extern "C" {
00040 #endif /* __cplusplus */
00041 
00042 #define LBM_VERS_MAJOR  6
00043 #define LBM_VERS_MINOR  7
00044 #define LBM_VERS_MAINT  1
00045 #define LBM_VERS_SFX  0
00046 #define LBM_VERS_TAG  ""
00047 #define LBM_VERS        (LBM_VERS_MAJOR*10000+LBM_VERS_MINOR*100+LBM_VERS_MAINT)
00048 
00049 #if defined(_WIN32)
00050 #if !defined(DONT_TYPEDEF_INT_T)
00051         typedef __int8 int8_t;
00052         typedef __int16 int16_t;
00053         typedef __int32 int32_t;
00054         typedef __int64 int64_t;
00055 #endif
00056         typedef unsigned __int8 uint8_t;
00057         typedef unsigned __int16 uint16_t;
00058         typedef unsigned __int32 uint32_t;
00059         typedef unsigned __int64 uint64_t;
00060         /* C99 printf format macros missing from VC. */
00061         #define PRId8 "d"
00062         #define PRId16 "d"
00063         #define PRId32 "d"
00064         #define PRId64 "I64d"
00065         #define PRIu8 "u"
00066         #define PRIu16 "u"
00067         #define PRIu32 "u"
00068         #define PRIu64 "I64u"
00069         #define PRIx8 "x"
00070         #define PRIx16 "x"
00071         #define PRIx32 "x"
00072         #define PRIx64 "I64x"
00073         #define PRIuSZ "Iu"
00074         /* C99 scanf format macros missing from VC. */
00075         #define SCNd8 "d"
00076         #define SCNd16 "hd"
00077         #define SCNd32 "ld"
00078         #define SCNd64 "I64d"
00079         #define SCNu8 "u"
00080         #define SCNu16 "hu"
00081         #define SCNu32 "lu"
00082         #define SCNu64 "I64u"
00083         #define SCNx64 "I64x"
00084         #define SCNuSZ "Iu"
00085         #define SCNuSZcast(x) (size_t * )(x)
00086 #elif defined(__VMS)
00087         #include <inttypes.h>
00088         /* C99 printf format macros missing from OpenVMS. */
00089         #define PRId8 "d"
00090         #define PRId16 "d"
00091         #define PRId32 "d"
00092         #define PRId64 "lld"
00093         #define PRIu8 "u"
00094         #define PRIu16 "u"
00095         #define PRIu32 "u"
00096         #define PRIu64 "llu"
00097         #define PRIuSZ "zu"
00098         #define PRIx8 "x"
00099         #define PRIx16 "x"
00100         #define PRIx32 "x"
00101         #define PRIx64 "llx"
00102         #define PRIuSZcast(x)  (size_t)(x)
00103         /* C99 scanf format macros missing from OpenVMS. */
00104         #define SCNd8 "hhd"
00105         #define SCNd16 "hd"
00106         #define SCNd32 "d"
00107         #define SCNd64 "lld"
00108         #define SCNu8 "hhu"
00109         #define SCNu16 "hu"
00110         #define SCNu32 "u"
00111         #define SCNu64 "llu"
00112         #define SCNx64 "llx"
00113         #define SCNuSZ "lu"
00114         #define SCNuSZcast(x) (size_t * )(x)
00115 #else
00116         #include <inttypes.h>
00117         #ifndef PRIuSZ
00118                 #define PRIuSZ "zu"
00119                 #define PRIuSZcast(x) (size_t)(x)
00120         #endif
00121         #ifndef SCNuSZ
00122                 #define SCNuSZ "zu"
00123                 #define SCNuSZcast(x) (size_t * )(x)
00124         #endif
00125 #endif
00126 
00127 /* Directives to show how we treat exporting functions with Windows from the DLL */
00128 #if defined(_WIN32)
00129 #   if defined(_DLL) && defined(LBM_EXPORT_SYMS)
00130 #      define LBMExpDLL __declspec(dllexport)
00131 #   elif defined(LBM_STATIC_LIB)
00132 #      define LBMExpDLL
00133 #   else
00134 #      define LBMExpDLL __declspec(dllimport)
00135 #   endif /* _DLL && LBM_EXPORT_SYMS */
00136 #elif defined(__TANDEM)
00137 #   if defined(LBM_EXPORT_SYMS)
00138 #      define LBMExpDLL export$
00139 #   else
00140 #      define LBMExpDLL import$
00141 #   endif
00142 #else
00143 #   define LBMExpDLL
00144 #endif /* _WIN32 */
00145 
00146 /* Constants */
00147 /*! lbm_errnum() value. An invalid argument was passed. */
00148 #define LBM_EINVAL 1
00149 /*! lbm_errnum() value. Function would block, but object is set to be nonblocking. */
00150 #define LBM_EWOULDBLOCK 2
00151 /*! lbm_errnum() value. Operation could not be completed due to memory allocation error. */
00152 #define LBM_ENOMEM 3
00153 /*! lbm_errnum() value. Operation was invalid due to error in internal processing. */
00154 #define LBM_EOP 4
00155 /*! lbm_errnum() value. Operation failed due to unrecoverable OS system call error. */
00156 #define LBM_EOS 5
00157 /*! lbm_errnum() value. Operation timed out waiting to complete. */
00158 #define LBM_ETIMEDOUT 6
00159 /*! lbm_errnum() value. UM daemon connection not connected. */
00160 #define LBM_EDAEMONCONN 7
00161 /*! lbm_errnum() value. Registration not completed. */
00162 #define LBM_EUMENOREG 8
00163 /*! lbm_errnum() value. Operation is not supported. */
00164 #define LBM_EOPNOTSUPP 9
00165 /*! lbm_errnum() value. Operation in progress. */
00166 #define LBM_EINPROGRESS 10
00167 /*! lbm_errnum() The queue is not fully registered. */
00168 #define LBM_ENO_QUEUE_REG 11
00169 /*! lbm_errnum() The store is not fully registered. */
00170 #define LBM_ENO_STORE_REG 12
00171 /*! lbm_errnum() Error parsing message selector. */
00172 #define LBM_EMSG_SELECTOR 14
00173         
00174 /* lbm_msg_t types */
00175 /*! lbm_msg_t type. Data message, Message is composed of user data. */
00176 #define LBM_MSG_DATA 0
00177 /*! lbm_msg_t type. End of Transport Session (connection closed to source) (no further data). */
00178 #define LBM_MSG_EOS 1
00179 /*! lbm_msg_t type. Request message from source. */
00180 #define LBM_MSG_REQUEST 2
00181 /*! lbm_msg_t type. Response message from requestee */
00182 #define LBM_MSG_RESPONSE 3
00183 /*! lbm_msg_t type. Missing message detected and not recovered in given time. */
00184 #define LBM_MSG_UNRECOVERABLE_LOSS 4
00185 /*! lbm_msg_t type. Missing burst of messages detected and not recovered. */
00186 #define LBM_MSG_UNRECOVERABLE_LOSS_BURST 5
00187 /*! lbm_msg_t type. Notification that no source has been found for topic. Still querying for topic source. */
00188 #define LBM_MSG_NO_SOURCE_NOTIFICATION 6
00189 /*! lbm_msg_t type. UMP receiver registration encountered an error. Data holds error message. */
00190 #define LBM_MSG_UME_REGISTRATION_ERROR 7
00191 /*! lbm_msg_t type. UMP receiver registration successful. Data holds registration IDs. */
00192 #define LBM_MSG_UME_REGISTRATION_SUCCESS 8
00193 /*! lbm_msg_t type. UMP receiver notification of source registration change. Data holds info message. */
00194 #define LBM_MSG_UME_REGISTRATION_CHANGE 9
00195 /*! lbm_msg_t type. UMP receiver registration successful for a store (extended form). Data holds registration IDs, etc. */
00196 #define LBM_MSG_UME_REGISTRATION_SUCCESS_EX 10
00197 /*! lbm_msg_t type. UMP receiver notification of registration completion. Data holds sequence number and flags, etc. */
00198 #define LBM_MSG_UME_REGISTRATION_COMPLETE_EX 11
00199 /*! lbm_msg_t type. UMP receiver notification of deregistration success. Data holds registration IDs, etc. */
00200 #define LBM_MSG_UME_DEREGISTRATION_SUCCESS_EX 12
00201 /*! lbm_msg_t type. UMP receiver notification of deregistration complete. */
00202 #define LBM_MSG_UME_DEREGISTRATION_COMPLETE_EX 13
00203 
00204 /*! lbm_msg_t type. UMQ receiver registration encountered an error. Data holds error message. */
00205 #define LBM_MSG_UMQ_REGISTRATION_ERROR 16
00206 /*! lbm_msg_t type. UMQ receiver notification of registration completion. Data holds Queue information, assignment ID, etc. */
00207 #define LBM_MSG_UMQ_REGISTRATION_COMPLETE_EX 18
00208 /*! lbm_msg_t type. UMQ receiver notification of de-registration completion. Data holds Queue information, etc. */
00209 #define LBM_MSG_UMQ_DEREGISTRATION_COMPLETE_EX 19
00210 /*! lbm_msg_t type. Beginning of Transport Session (source connection established) (data received). */
00211 #define LBM_MSG_BOS 20
00212 /*! lbm_msg_t type. UMQ receiver index assignment start/stop encountered an error.  Data holds error message. */
00213 #define LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_ERROR 21
00214 /*! lbm_msg_t type. UMQ receiver notification of beginning of index assignment eligibility or index assignment. Data holds index information, etc. */
00215 #define LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX 22
00216 /*! lbm_msg_t type. UMQ receiver notification of end of index assignment eligibility or index assignment. Data holds index information, etc. */
00217 #define LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX 23
00218 /*! lbm_msg_t type. UMQ receiver notification of beginning of index. */
00219 #define LBM_MSG_UMQ_INDEX_ASSIGNED_EX 24
00220 /*! lbm_msg_t type. UMQ receiver notification of end of index. */
00221 #define LBM_MSG_UMQ_INDEX_RELEASED_EX 25
00222 /*! lbm_msg_t type. UMQ receiver notification of an index assignment error. */
00223 #define LBM_MSG_UMQ_INDEX_ASSIGNMENT_ERROR 26
00224 /*! lbm_msg_t type. Hot-failover reset message was handled. UMS is now expecting msg->hf_sequence_number as the next non-reset hot-failover message. */
00225 #define LBM_MSG_HF_RESET 27
00226 
00227 /* Flags to sending/receiving routines. */
00228 /*! Flag passed to a source send call E.G. (lbm_src_send(), lbm_src_send_ex() etc) : Message starts a batch */
00229 #define LBM_MSG_START_BATCH 0x1
00230 /*! Flag passed to a source send call E.G. (lbm_src_send(), lbm_src_send_ex() etc) : Message ends a batch of messages */
00231 #define LBM_MSG_END_BATCH 0x2
00232 /*! Flag passed to a source send call E.G. (lbm_src_send(), lbm_src_send_ex() etc) : Message constitutes a complete batch
00233           and should be sent to the implicit batching buffer. */
00234 #define LBM_MSG_COMPLETE_BATCH 0x3 /* same as START | END */
00235 /*! Flag passed to a source send call E.G. (lbm_src_send(), lbm_src_send_ex() etc) : Message is to be sent ASAP (not implicitly or explicitly batched).
00236           This also flushes waiting messages that were explicitly or implicitly batched. */
00237 #define LBM_MSG_FLUSH 0x4
00238 /*! Flag passed to a source send call E.G. (lbm_src_send(), lbm_src_send_ex() etc) : If message could not be sent immediately return
00239           and error and signal LBM_EWOULDBLOCK. */
00240 #define LBM_SRC_NONBLOCK 0x8
00241 /*! reserved for future use */
00242 #define LBM_SRC_BLOCK_TEMP 0x10
00243 /*! Flag passed to a source send call E.G. (lbm_src_send(), lbm_src_send_ex() etc) : Block the caller indefinitely until the message
00244           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
00245           nor LBM_SRC_BLOCK are supplied.) */
00246 #define LBM_SRC_BLOCK 0x20
00247 /*! Flag passed to a source send vectored call E.G. (lbm_src_sendv(), lbm_src_sendv_ex() etc) : iovec elements should be gather into a single message */
00248 #define LBM_MSG_IOV_GATHER 0x40
00249 /*! reserved for future use */
00250 #define LBM_RCV_NONBLOCK 0x8
00251 /*! reserved for future use */
00252 #define LBM_RCV_BLOCK_TEMP 0x10
00253 /*! reserved for future use */
00254 #define LBM_RCV_BLOCK 0x20
00255 
00256 /*! Receiving flag only */
00257 /*! lbm_msg_t flags. Message starts a batch. */
00258 #define LBM_MSG_FLAG_START_BATCH 0x1
00259 /*! lbm_msg_t flags. Message ends a batch. */
00260 #define LBM_MSG_FLAG_END_BATCH 0x2
00261 /*! lbm_msg_t flags. Message is a passed-through Hot Failover message. */
00262 #define LBM_MSG_FLAG_HF_PASS_THROUGH 0x4
00263 /*! lbm_msg_t flags. Message is a UMP retransmission. */
00264 #define LBM_MSG_FLAG_UME_RETRANSMIT 0x8
00265 /*! lbm_msg_t flags. Message is a retransmission. */
00266 #define LBM_MSG_FLAG_RETRANSMIT 0x8
00267 /*! lbm_msg_t flags. Message is an immediate message. */
00268 #define LBM_MSG_FLAG_IMMEDIATE 0x10
00269 /*! lbm_msg_t flags. Message is a Hot Failover duplicate message. */
00270 #define LBM_MSG_FLAG_HF_DUPLICATE 0x20
00271 /*! lbm_msg_t flags. Message is a UMQ message that has been re-assigned at least once. */
00272 #define LBM_MSG_FLAG_UMQ_REASSIGNED 0x40
00273 /*! lbm_msg_t flags. Message is a UMQ message that has been resubmitted at least once. */
00274 #define LBM_MSG_FLAG_UMQ_RESUBMITTED 0x80
00275 /*! lbm_msg_t flags. Message has no topic. */
00276 #define LBM_MSG_FLAG_TOPICLESS 0x100
00277 
00278 /*! lbm_msg_t flags. For internal use only. */
00279 #define LBM_MSG_FLAG_DELIVERY_LATENCY 0x200
00280 
00281 /*! lbm_msg_t flags. Message is a Hot Failover optional message. */
00282 #define LBM_MSG_FLAG_HF_OPTIONAL 0x400
00283 /*! lbm_msg_t flags. Message contains a 32 bit hot failover sequence number */
00284 #define LBM_MSG_FLAG_HF_32 0x800
00285 /*! lbm_msg_t flags. Message contains a 64 bit hot failover sequence number. */
00286 #define LBM_MSG_FLAG_HF_64 0x1000
00287 /*! lbm_msg_t flags. Message was recovered via OTR */
00288 #define LBM_MSG_FLAG_OTR 0x2000
00289 /*! lbm_msg_t flags. For internal use only. */
00290 #define LBM_MSG_FLAG_UME_SRC_REGID 0x4000
00291 
00292 
00293 /*! Message channel info flags */
00294 /*! lbm_msg_channel_info_t flags. Message was sent on a numbered channel */
00295 #define LBM_MSG_FLAG_NUMBERED_CHANNEL 0x1
00296 
00297 /* Flags to topic resolution request routine. May be or'ed together. */
00298 /*! Flag passed to lbm_context_topic_resolution_request() to request each Gateway to propogate remote interest. */
00299 #define LBM_TOPIC_RES_REQUEST_GW_REMOTE_INTEREST 0x40
00300 /*! Flag passed to lbm_context_topic_resolution_request() to request contexts to query for other contexts */
00301 #define LBM_TOPIC_RES_REQUEST_CONTEXT_QUERY 0x20
00302 /*! Flag passed to lbm_context_topic_resolution_request() to request contexts to re-advertise */
00303 #define LBM_TOPIC_RES_REQUEST_CONTEXT_ADVERTISEMENT 0x10
00304 /*! reserved for internal use */
00305 #define LBM_TOPIC_RES_REQUEST_RESERVED1 0x08
00306 /*! Flag passed to lbm_context_topic_resolution_request() to request sources to re-advertise */
00307 #define LBM_TOPIC_RES_REQUEST_ADVERTISEMENT 0x04
00308 /*! Flag passed to lbm_context_topic_resolution_request() to request receivers to query for source */
00309 #define LBM_TOPIC_RES_REQUEST_QUERY 0x02
00310 /*! Flag passed to lbm_context_topic_resolution_request() to request wildcard receivers to query for source */
00311 #define LBM_TOPIC_RES_REQUEST_WILDCARD_QUERY 0x01
00312 
00313 /* event types for source callbacks */
00314 /*! Type of source event. This event indicates that the first or initial receiver of a receiving
00315  application has joined a unicast transport session. UM delivers this event if it has mapped a source object to a unicast transport session (TCP, LBT-RU, LBT-IPC, or LBT-RDMA) and then the first receiver joins the transport session. If several sources map to the transport session, UM delivers this event multiple times, once for each source. The initial receiver can be subscribed to any of the sources topics. Subsequent receivers that join the transport session do not trigger additional events. However, additional receiving applications (contexts) may also join the transport session and UM delivers the event for the first or initial receiver of each additional application. */
00316 #define LBM_SRC_EVENT_CONNECT 1
00317 /*! Type of source event. This event indicates that the last or final receiver of a receiving application has left a unicast transport session. UM delivers this event if it has mapped a source object to a unicast transport session (TCP, LBT-RU, LBT-IPC, or LBT-RDMA) and then the last receiver leaves the transport session. If several sources map to the transport session, UM delivers this event multiple times, once for each source. The final receiver can be subscribed to any of the sources topics. Additional receiving applications (contexts) may also leave the transport session and UM delivers the event for the last or final receiver of each additional application. */
00318 #define LBM_SRC_EVENT_DISCONNECT 2
00319 /*! Type of source event. Following earlier return of LBM_EWOULDBLOCK, means source is ready for more sends */
00320 #define LBM_SRC_EVENT_WAKEUP 3
00321 /*! Type of source event. For UM daemon usage only, means daemon has confirmed src created */
00322 #define LBM_SRC_EVENT_DAEMON_CONFIRM 4
00323 /*! Type of source event. For UMP only, means registration of source failed with an error. Event data holds error string. */
00324 #define LBM_SRC_EVENT_UME_REGISTRATION_ERROR 5
00325 /*! Type of source event. For UMP only, means registration of source successful. Event data holds registration info */
00326 #define LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS 6
00327 /*! Type of source event. For UMP only, means UMP ACK from store indicates message is stable. Event data holds ACK information. */
00328 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE 7
00329 /*! Type of source event. For UMP only, means UMP Confirmed Delivery of Message from receiver. Event data holds ACK information. */
00330 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION 8
00331 /*! Type of source event. For UMP only, means store has not been active within timeout. Event data holds info string. */
00332 #define LBM_SRC_EVENT_UME_STORE_UNRESPONSIVE 9
00333 /*! Type of source event. For UMP only, means message is being reclaimed. Event data holds ACK information. */
00334 #define LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED 10
00335 /*! Type of source event. For UMP only, means registration of source successful (extended form). Event data holds registration info */
00336 #define LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS_EX 11
00337 /*! Type of source event. For UMP only, means registration of source complete (extended form). Event data holds sequence number, flags, etc. */
00338 #define LBM_SRC_EVENT_UME_REGISTRATION_COMPLETE_EX 12
00339 /*! Type of source event. For UMP only, means UMP ACK from store indicates message is stable (extended form). Event data holds ACK information. */
00340 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX 13
00341 /*! Type of source event. For UMP only, means UMP Confirmed Delivery of Message from receiver (extended form). Event data holds ACK information. */
00342 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX 14
00343 /*! Type of source event. Informs the application the sequence numbers used with a message. Event data holds sequence number data. This event is generated only when using the "lbm_src_send_ex()" API's with the LBM_SRC_SEND_EX_FLAG_SEQUENCE_NUMBER_INFO flag or LBM_SRC_SEND_EX_FLAG_SEQUENCE_NUMBER_INFO_FRAGONLY flag. */
00344 #define LBM_SRC_EVENT_SEQUENCE_NUMBER_INFO 15
00345 /*! Type of source event. For UMQ only, means registration of source failed with an error. Event data holds error string. */
00346 #define LBM_SRC_EVENT_UMQ_REGISTRATION_ERROR 16
00347 /*! Type of source event. For UMQ only, informs the application of the Message ID assigned with a message. Event data holds Message ID, etc. */
00348 #define LBM_SRC_EVENT_UMQ_MESSAGE_ID_INFO 17
00349 /*! Type of source event. For UMQ only, means registration of source complete. Event data holds Queue information, etc. */
00350 #define LBM_SRC_EVENT_UMQ_REGISTRATION_COMPLETE_EX 18
00351 /*! Type of source event. For UMQ only, means UMQ ACK from queue indicates message is stable. Event data holds ACK information. */
00352 #define LBM_SRC_EVENT_UMQ_MESSAGE_STABLE_EX 19
00353 /*! Type of source event. For UMQ ULB only, means message was assigned to a receiver. Event data holds message information. */
00354 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_ASSIGNED_EX 20
00355 /*! Type of source event. For UMQ ULB only, means message was reassigned from a receiver. Event data holds message information. */
00356 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_REASSIGNED_EX 21
00357 /*! Type of source event. For UMQ ULB only, means message timed out and was end-of-lifed. Event data holds message information. */
00358 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_TIMEOUT_EX 22
00359 /*! Type of source event. For UMQ ULB only, means message was completed processed on all application sets. Event data holds message information. */
00360 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_COMPLETE_EX 23
00361 /*! Type of source event. For UMQ ULB only, means message was consumed by a receiver. Event data holds message information. */
00362 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_CONSUMED_EX 24
00363 /*! Type of source event. For UMQ ULB only, means receiver registered. Event data holds receiver information. */
00364 #define LBM_SRC_EVENT_UMQ_ULB_RECEIVER_REGISTRATION_EX 25
00365 /*! Type of source event. For UMQ ULB only, means receiver deregistered. Event data holds receiver information. */
00366 #define LBM_SRC_EVENT_UMQ_ULB_RECEIVER_DEREGISTRATION_EX 26
00367 /*! Type of source event. For UMQ ULB only, means receiver signalled ready for messages. Event data holds receiver information. */
00368 #define LBM_SRC_EVENT_UMQ_ULB_RECEIVER_READY_EX 27
00369 /*! Type of source event. For UMQ ULB only, means receiver timed out and was end-of-lifed. Event data holds receiver information. */
00370 #define LBM_SRC_EVENT_UMQ_ULB_RECEIVER_TIMEOUT_EX 28
00371 /*! Type of source event. For UMP, UMQ, and/or ULB, informs the application of a change in state for a specified flight size. Event data holds state information. */
00372 #define LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION 29
00373 /*! Type of source event. Message is being reclaimed. Event data holds ACK information. */
00374 #define LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX 30
00375 /*! Type of source event. For UMP only, means deregistration of source successful (extended form). */
00376 #define LBM_SRC_EVENT_UME_DEREGISTRATION_SUCCESS_EX 31
00377 /*! Type of source event. For UMP only, means deregistration of source complete (extended form). */
00378 #define LBM_SRC_EVENT_UME_DEREGISTRATION_COMPLETE_EX 32
00379 /*! Type of source event. For UMP only, means a message is NOT stable, and the source has given up waiting for stability. Event data tells which store the message is not stable at and the reason the source gave up. */
00380 #define LBM_SRC_EVENT_UME_MESSAGE_NOT_STABLE 33
00381 
00382 /* event types for context event callbacks */
00383 /*! Type of context event. For UMQ only, means registration of context complete. Event data holds Queue information, Registration ID, etc. */
00384 #define LBM_CONTEXT_EVENT_UMQ_REGISTRATION_COMPLETE_EX 1
00385 /*! Type of context event. For UMQ only, means registration of context successful with specific Queue instance. Event data holds Queue instance information, etc. */
00386 #define LBM_CONTEXT_EVENT_UMQ_REGISTRATION_SUCCESS_EX 2
00387 /*! Type of context event. For UMQ only, means registration of context failed with an error. Event data holds error string. */
00388 #define LBM_CONTEXT_EVENT_UMQ_REGISTRATION_ERROR 3
00389 /*! Type of context event. For UMQ only, means queue instance list has changed. Event holds information string. */
00390 #define LBM_CONTEXT_EVENT_UMQ_INSTANCE_LIST_NOTIFICATION 4
00391 
00392 /* UM Transport Types */
00393 /*! Transport type TCP. */
00394 #define LBM_TRANSPORT_TYPE_TCP 0x00
00395 /*! Transport type LBT-RU. */
00396 #define LBM_TRANSPORT_TYPE_LBTRU 0x01
00397 /*! Transport type LBT-SMX. */
00398 #define LBM_TRANSPORT_TYPE_LBTSMX 0x4
00399 /*! Transport type LBT-RM. */
00400 #define LBM_TRANSPORT_TYPE_LBTRM 0x10
00401 /*! Transport type LBT-IPC. */
00402 #define LBM_TRANSPORT_TYPE_LBTIPC 0x40
00403 /*! Transport type LBT-RDMA. */
00404 #define LBM_TRANSPORT_TYPE_LBTRDMA 0x20
00405 
00406 /* Context attr - Opmode */
00407 #define LBM_CTX_ATTR_OP_EMBEDDED 1
00408 #define LBM_CTX_ATTR_OP_DAEMON 2
00409 #define LBM_CTX_ATTR_OP_SEQUENTIAL 3
00410 
00411 /* Context attr - fdtype */
00412 #define LBM_CTX_ATTR_FDTYPE_POLL 1
00413 #define LBM_CTX_ATTR_FDTYPE_SELECT 2
00414 #define LBM_CTX_ATTR_FDTYPE_WSAEV 3
00415 #define LBM_CTX_ATTR_FDTYPE_WINCPORT 4
00416 #define LBM_CTX_ATTR_FDTYPE_WINCPORT_OV 5
00417 #define LBM_CTX_ATTR_FDTYPE_EPOLL 6
00418 #define LBM_CTX_ATTR_FDTYPE_DEVPOLL 7
00419 #define LBM_CTX_ATTR_FDTYPE_KQUEUE 8
00420 #define LBM_CTX_ATTR_FDTYPE_WINRIOCPORT 9
00421 
00422 /* Context attr - monitor transport */
00423 #define LBM_CTX_ATTR_MON_TRANSPORT_LBM 1
00424 #define LBM_CTX_ATTR_MON_TRANSPORT_LBMSNMP 2
00425 
00426 /* Context attr - IPC receiver signaling behavior */
00427 #define LBM_CTX_ATTR_IPC_RCV_THREAD_PEND 1
00428 #define LBM_CTX_ATTR_IPC_RCV_THREAD_BUSY_WAIT 2
00429 
00430 /* Context attr - LBT-RDMA receiver signaling behavior */
00431 #define LBM_CTX_ATTR_RDMA_RCV_THREAD_PEND 1
00432 #define LBM_CTX_ATTR_RDMA_RCV_THREAD_BUSY_WAIT 2
00433 
00434 /* Context attr - Receive Thread Pool Behavior */
00435 #define LBM_CTX_ATTR_RCV_THRD_POOL_CREATE 1
00436 #define LBM_CTX_ATTR_RCV_THRD_POOL_DYNAMIC 2
00437 
00438 /* Context attr - Network compatibility mode */
00439 #define LBM_CTX_ATTR_NET_COMPAT_MODE_DEFAULT    0x00000000
00440 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_3_6    0x00030600
00441 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_3_6_1  0x00030601
00442 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_3_6_2  0x00030602
00443 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_3_6_5  0x00030605
00444 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_0    0x00040000
00445 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_0_1  0x00040001
00446 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_1    0x00040100
00447 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_1_1  0x00040101
00448 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_1_2  0x00040102
00449 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_1_3  0x00040103
00450 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_1  0x00040201
00451 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_2  0x00040202
00452 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_3  0x00040203
00453 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_4  0x00040204
00454 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_5  0x00040205
00455 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_6  0x00040206
00456 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_7  0x00040207
00457 #define LBM_CTX_ATTR_NET_COMPAT_MODE_LBM_4_2_8  0x00040208
00458 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_0    0x01030000
00459 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_0_1  0x01030001
00460 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_0_2  0x01030002
00461 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_1    0x01030100
00462 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_1_1  0x01030101
00463 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_1_2  0x01030102
00464 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_1_3  0x01030103
00465 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_1  0x01030201
00466 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_2  0x01030202
00467 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_3  0x01030203
00468 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_4  0x01030204
00469 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_5  0x01030205
00470 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_6  0x01030206
00471 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_7  0x01030207
00472 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UME_3_2_8  0x01030208
00473 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_1_0    0x02010000
00474 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_1_1    0x02010100
00475 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_1_1_1  0x02010101
00476 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_0    0x02020000
00477 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_0_1  0x02020001
00478 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_1  0x02020101
00479 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_3  0x02020103
00480 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_4  0x02020104
00481 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_5  0x02020105
00482 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_6  0x02020106
00483 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_7  0x02020107
00484 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_8  0x02020108
00485 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_9  0x02020109
00486 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UMQ_2_1_10 0x0202010a
00487 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_0     0x03050000
00488 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_0_1   0x03050001
00489 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_1     0x03050100
00490 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_1_1   0x03050101
00491 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_1_2   0x03050102
00492 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_2     0x03050200
00493 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_2_1   0x03050201
00494 #define LBM_CTX_ATTR_NET_COMPAT_MODE_UM_5_2_2   0x03050202
00495 
00496 /* Src Topic attr */
00497 #define LBM_SRC_TOPIC_ATTR_TRANSPORT_TCP LBM_TRANSPORT_TYPE_TCP
00498 #define LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTRM LBM_TRANSPORT_TYPE_LBTRM
00499 #define LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTRU LBM_TRANSPORT_TYPE_LBTRU
00500 #define LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTIPC LBM_TRANSPORT_TYPE_LBTIPC
00501 #define LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTSMX LBM_TRANSPORT_TYPE_LBTSMX
00502 #define LBM_SRC_TOPIC_ATTR_TRANSPORT_LBTRDMA LBM_TRANSPORT_TYPE_LBTRDMA
00503 #define LBM_SRC_TOPIC_ATTR_TCP_MULTI_RECV_NORMAL 0
00504 #define LBM_SRC_TOPIC_ATTR_TCP_MULTI_RECV_BOUNDED_LATENCY 1
00505 #define LBM_SRC_TOPIC_ATTR_TCP_MULTI_RECV_SOURCE_PACED 2
00506 #define LBM_SRC_TOPIC_ATTR_TCP_MULTI_RECV_SEND_ORDER_SERIAL 0
00507 #define LBM_SRC_TOPIC_ATTR_TCP_MULTI_RECV_SEND_ORDER_RANDOM 1
00508 #define LBM_SRC_TOPIC_ATTR_SSF_NONE 0
00509 #define LBM_SRC_TOPIC_ATTR_SSF_INCLUSION 1
00510 #define LBM_SRC_TOPIC_ATTR_SSF_EXCLUSION 2
00511 #define LBM_SRC_TOPIC_ATTR_IMPLICIT_BATCH_TYPE_DEFAULT 0
00512 #define LBM_SRC_TOPIC_ATTR_IMPLICIT_BATCH_TYPE_ADAPTIVE 1
00513 #define LBM_SRC_TOPIC_ATTR_UME_STORE_BEHAVIOR_RR 0x0
00514 #define LBM_SRC_TOPIC_ATTR_UME_STORE_BEHAVIOR_QC 0x1
00515 #define LBM_SRC_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_LOWEST 0x0
00516 #define LBM_SRC_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_MAJORITY 0x1
00517 #define LBM_SRC_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_HIGHEST 0x2
00518 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ANY 0x0
00519 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_MAJORITY 0x1
00520 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_QUORUM 0x1
00521 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ALL 0x2
00522 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ALL_ACTIVE 0x3
00523 #define LBM_SRC_TOPIC_ATTR_UMQ_STABLE_BEHAVIOR_ANY 0x0
00524 #define LBM_SRC_TOPIC_ATTR_UMQ_STABLE_BEHAVIOR_MAJORITY 0x1
00525 #define LBM_SRC_TOPIC_ATTR_UMQ_STABLE_BEHAVIOR_QUORUM 0x1
00526 #define LBM_SRC_TOPIC_ATTR_UMQ_STABLE_BEHAVIOR_ALL 0x2
00527 #define LBM_SRC_TOPIC_ATTR_UMQ_STABLE_BEHAVIOR_ALL_ACTIVE 0x3
00528 #define LBM_SRC_TOPIC_ATTR_LBTIPC_BEHAVIOR_SOURCE_PACED LBTIPC_BEHAVIOR_SRC_PACED
00529 #define LBM_SRC_TOPIC_ATTR_LBTIPC_BEHAVIOR_RECEIVER_PACED LBTIPC_BEHAVIOR_RCVR_PACED
00530 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_CONSUME 0x1
00531 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_TIMEOUT 0x2
00532 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_ASSIGNMENT 0x4
00533 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_REASSIGNMENT 0x8
00534 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_COMPLETE 0x10
00535 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_TIMEOUT 0x20
00536 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_REGISTRATION 0x40
00537 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_DEREGISTRATION 0x80
00538 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_READY 0x100
00539 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_ALL 0x1FF
00540 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_ASSIGNMENT_DEFAULT 0x0
00541 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_ASSIGNMENT_RANDOM 0x1
00542 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_LF_BEHAVIOR_IGNORED 0x0
00543 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_LF_BEHAVIOR_PROVISIONED 0x1
00544 #define LBM_SRC_TOPIC_ATTR_UMQ_ULB_LF_BEHAVIOR_DYNAMIC 0x2
00545 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_NONE 0x0
00546 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_PER_FRAGMENT 0x1
00547 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_PER_MESSAGE 0x2
00548 #define LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_FRAG_AND_MSG 0x3
00549 #define LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_NONE 0x0
00550 #define LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_PER_FRAGMENT 0x1
00551 #define LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_PER_MESSAGE 0x2
00552 #define LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_FRAG_AND_MSG 0x3
00553 
00554 /* Rcv Topic attr */
00555 #define LBM_RCV_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_LOWEST 0x0
00556 #define LBM_RCV_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_MAJORITY 0x1
00557 #define LBM_RCV_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_HIGHEST 0x2
00558 #define LBM_RCV_TOPIC_ATTR_TCP_ACTIVITY_TIMEOUT_SO_KEEPALIVE 0x1
00559 #define LBM_RCV_TOPIC_ATTR_TCP_ACTIVITY_TIMEOUT_TIMER 0x2
00560 #define LBM_RCV_TOPIC_ATTR_CHANNEL_BEHAVIOR_DELIVER_MSGS 0x1
00561 #define LBM_RCV_TOPIC_ATTR_CHANNEL_BEHAVIOR_DISCARD_MSGS 0x2
00562 #define LBM_RCV_TOPIC_ATTR_UMQ_INDEX_ASSIGN_ELIGIBILITY_INELIGIBLE 0x0
00563 #define LBM_RCV_TOPIC_ATTR_UMQ_INDEX_ASSIGN_ELIGIBILITY_ELIGIBLE 0x1
00564 #define LBM_RCV_TOPIC_ATTR_UMQ_QUEUE_PARTICIPATION_NONE 0
00565 #define LBM_RCV_TOPIC_ATTR_UMQ_QUEUE_PARTICIPATION_NORMAL 1
00566 #define LBM_RCV_TOPIC_ATTR_UMQ_QUEUE_PARTICIPATION_OBSERVER 2
00567 #define LBM_RCV_TOPIC_ATTR_UMQ_HOLD_INTERVAL_FOREVER 0xFFFFFFFF
00568 
00569 /* Limits */
00570 #define LBM_MSG_MAX_SOURCE_LEN 128
00571 #define LBM_MSG_MAX_TOPIC_LEN 256
00572 #define LBM_MSG_MAX_STATE_LEN 32
00573 #define LBM_UME_MAX_STORE_STRLEN 24
00574 #define LBM_UMQ_MAX_QUEUE_STRLEN 256
00575 #define LBM_UMQ_MAX_TOPIC_STRLEN 256
00576 #define LBM_UMQ_MAX_APPSET_STRLEN 256
00577 #define LBM_MAX_CONTEXT_NAME_LEN 128
00578 #define LBM_MAX_EVENT_QUEUE_NAME_LEN 128
00579 #define LBM_MAX_UME_STORES 25
00580 #define LBM_UMQ_ULB_MAX_RECEIVER_STRLEN 32
00581 #define LBM_UMQ_MAX_INDEX_LEN 216
00582 #define LBM_UMQ_USER_NAME_LENGTH_MAX 127
00583 #define LBM_UMQ_PASSWORD_LENGTH_MAX 15
00584 #define LBM_UMM_NUM_SERVERS_MAX 16
00585 #define LBM_UMM_USER_NAME_LENGTH_MAX 100
00586 #define LBM_UMM_APP_NAME_LENGTH_MAX 100
00587 #define LBM_UMM_PASSWORD_LENGTH_MAX 100
00588 #define LBM_UMM_SERVER_LENGTH_MAX 32
00589 #define LBM_HMAC_BLOCK_SZ       20
00590 #define LBM_MAX_GATEWAY_NAME_LEN 128
00591 #define LBM_OTID_BLOCK_SZ 32
00592 #define LBM_CONTEXT_INSTANCE_BLOCK_SZ 8
00593 
00594 #define LBM_FLIGHT_SIZE_BEHAVIOR_NOTIFY 0x0
00595 #define LBM_FLIGHT_SIZE_BEHAVIOR_BLOCK 0x1
00596 
00597 /* Event types for file descriptor/socket management */
00598 /*! FD event. Read indication on file descriptor/socket */
00599 #define LBM_FD_EVENT_READ 0x1
00600 /*! FD event. Write indication on file descriptor/socket */
00601 #define LBM_FD_EVENT_WRITE 0x2
00602 /*! FD event. Exception (OOB/URG)  indication on file descriptor/socket */
00603 #define LBM_FD_EVENT_EXCEPT 0x4
00604 /*! FD event. Accept connection (TCP) indication on file descriptor/socket */
00605 #define LBM_FD_EVENT_ACCEPT 0x8
00606 /*! FD event. Close indication on file descriptor/socket */
00607 #define LBM_FD_EVENT_CLOSE 0x10
00608 /*! FD event. Connected indication on file descriptor/socket */
00609 #define LBM_FD_EVENT_CONNECT 0x20
00610 /*! FD event. All events indication on file descriptor/socket */
00611 #define LBM_FD_EVENT_ALL 0x3f
00612 
00613 /*! Value passed to lbm_event_dispatch to ask it to block */
00614 #define LBM_EVENT_QUEUE_BLOCK 0xFFFFFFFF
00615 /*! Value passed to lbm_event_dispatch to ask it to poll */
00616 #define LBM_EVENT_QUEUE_POLL 0x0
00617 
00618 /* Event Queue monitor event types */
00619 /*! event queue monitor event type. Warning of event queue size. */
00620 #define LBM_EVENT_QUEUE_SIZE_WARNING 0x1
00621 /*! event queue monitor event type. Warning of excessive delay for event. */
00622 #define LBM_EVENT_QUEUE_DELAY_WARNING 0x2
00623 /*! event queue monitor event type. Notification of something being added to queue. */
00624 #define LBM_EVENT_QUEUE_ENQUEUE_NOTIFICATION 0x3
00625 
00626 /* UM Log level values */
00627 /*! log level. Emergency */
00628 #define LBM_LOG_EMERG 1
00629 /*! log level. Alert */
00630 #define LBM_LOG_ALERT 2
00631 /*! log level. Critical */
00632 #define LBM_LOG_CRIT 3
00633 /*! log level. Error */
00634 #define LBM_LOG_ERR 4
00635 /*! log level. Warning */
00636 #define LBM_LOG_WARNING 5
00637 /*! log level. Notice */
00638 #define LBM_LOG_NOTICE 6
00639 /*! log level. Informational */
00640 #define LBM_LOG_INFO 7
00641 /*! log level. Debugging information */
00642 #define LBM_LOG_DEBUG 8
00643 
00644 /* UM daemon event types */
00645 /*! UM daemon event. Connected successfully to daemon (info not valid) */
00646 #define LBM_DAEMON_EVENT_CONNECTED 1
00647 /*! UM daemon event. Connected could not complete successfully (info valid) */
00648 #define LBM_DAEMON_EVENT_CONNECT_ERROR 2
00649 /*! UM daemon event. Connection to daemon aborted (info not valid) */
00650 #define LBM_DAEMON_EVENT_DISCONNECTED 3
00651 /*! UM daemon event. Connection to daemon timed out */
00652 #define LBM_DAEMON_EVENT_CONNECT_TIMEOUT 4
00653 
00654 /* transport statistics types */
00655 /*! Transport statistic type. TCP transport */
00656 #define LBM_TRANSPORT_STAT_TCP LBM_TRANSPORT_TYPE_TCP
00657 /*! Transport statistic type. LBT-RM transport */
00658 #define LBM_TRANSPORT_STAT_LBTRM LBM_TRANSPORT_TYPE_LBTRM
00659 /*! Transport statistic type. UM Daemon is being used */
00660 #define LBM_TRANSPORT_STAT_DAEMON 0xFF
00661 /*! Transport statistic type. LBT-RU transport */
00662 #define LBM_TRANSPORT_STAT_LBTRU LBM_TRANSPORT_TYPE_LBTRU
00663 /*! Transport statistic type. LBT-IPC transport */
00664 #define LBM_TRANSPORT_STAT_LBTIPC LBM_TRANSPORT_TYPE_LBTIPC
00665 /*! Transport statistic type. LBT-SMX transport */
00666 #define LBM_TRANSPORT_STAT_LBTSMX LBM_TRANSPORT_TYPE_LBTSMX
00667 /*! Transport statistic type. LBT-RDMA transport */
00668 #define LBM_TRANSPORT_STAT_LBTRDMA LBM_TRANSPORT_TYPE_LBTRDMA
00669 
00670 /* wildcard receiver pattern types */
00671 /*! PCRE (Perl Compatible Regular Expressions) pattern type */
00672 #define LBM_WILDCARD_RCV_PATTERN_TYPE_PCRE 1
00673 /*! POSIX regex pattern type */
00674 #define LBM_WILDCARD_RCV_PATTERN_TYPE_REGEX 2
00675 /*! Application defined callback pattern type */
00676 #define LBM_WILDCARD_RCV_PATTERN_TYPE_APP_CB 3
00677 
00678 /* LBM_SRC_EVENT_WAKEUP source type flags */
00679 /*! Unblocked source is a normal (or hot failover) source. */
00680 #define LBM_SRC_EVENT_WAKEUP_FLAG_NORMAL 0x1
00681 /*! Unblocked source is a context-level multicast immediate mode source. */
00682 #define LBM_SRC_EVENT_WAKEUP_FLAG_MIM 0x2
00683 /*! Unblocked source is a context-level unicast immediate mode source. */
00684 #define LBM_SRC_EVENT_WAKEUP_FLAG_UIM 0x4
00685 /*! Unblocked source is a context-level request source. */
00686 #define LBM_SRC_EVENT_WAKEUP_FLAG_REQUEST 0x8
00687 /*! Unblocked source is a context-level response source. */
00688 #define LBM_SRC_EVENT_WAKEUP_FLAG_RESPONSE 0x10
00689 
00690 /* LBM_SRC_EVENT_UMQ_ULB_MESSAGE_TIMEOUT_EX event flags */
00691 /*! timeout is the result of the total lifetime expiring */
00692 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_TIMEOUT_EX_FLAG_TOTAL_LIFETIME_EXPIRED 0x1
00693 /*! timeout is the result of the lbm_msg_umq_reassign API being called by a receiver */
00694 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_TIMEOUT_EX_FLAG_EXPLICIT 0x2
00695 /*! timeout is the result of the lbm_msg_umq_reassign API being called with the LBM_MSG_UMQ_REASSIGN_FLAG_DISCARD flag set */
00696 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_TIMEOUT_EX_FLAG_DISCARD 0x4
00697 /*! timeout is the result of hitting umq_ulb_application_set_message_max_reassignments number of assignments */
00698 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_TIMEOUT_EX_FLAG_MAX_REASSIGNS 0x8
00699 
00700 /* LBM_SRC_EVENT_UMQ_ULB_MESSAGE_REASSIGNED_EX event flags */
00701 /*! reassignment is the result of the lbm_msg_umq_reassign API being called by a receiver */
00702 #define LBM_SRC_EVENT_UMQ_ULB_MESSAGE_REASSIGNED_EX_FLAG_EXPLICIT 0x1
00703 
00704 /* LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION type */
00705 /*! Specifies a UMP flight size */
00706 #define LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_TYPE_UME 0x1
00707 /*! Specifies a ULB flight size */
00708 #define LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_TYPE_ULB 0x2
00709 /*! Specifies a UMQ flight size */
00710 #define LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_TYPE_UMQ 0x3
00711 
00712 /* LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION state */
00713 /*! Messages in flight has exceeded the threshold */
00714 #define LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_STATE_OVER 0x1
00715 /*! Messages in flight is now below the threshold */
00716 #define LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION_STATE_UNDER 0x2
00717 
00718 /* lbm_src_get_inflight types */
00719 /*! Specify a UMP flight size */
00720 #define LBM_FLIGHT_SIZE_TYPE_UME 0x1
00721 /*! Specify a ULB flight size */
00722 #define LBM_FLIGHT_SIZE_TYPE_ULB 0x2
00723 /*! Specify a UMQ flight size */
00724 #define LBM_FLIGHT_SIZE_TYPE_UMQ 0x3
00725 
00726 /* lbm_src_send_ex info flags */
00727 /*! UMP client data pointer is valid */
00728 #define LBM_SRC_SEND_EX_FLAG_UME_CLIENTD 0x1
00729 /*! UMQ client data pointer is valid */
00730 #define LBM_SRC_SEND_EX_FLAG_UMQ_CLIENTD 0x1
00731 /*! Inform application of the sequence numbers used for message */
00732 #define LBM_SRC_SEND_EX_FLAG_SEQUENCE_NUMBER_INFO 0x2
00733 /*! Inform application of the sequence numbers used for message (fragmented messages only) */
00734 #define LBM_SRC_SEND_EX_FLAG_SEQUENCE_NUMBER_INFO_FRAGONLY 0x4
00735 /*! Send messages using an appheader chain */
00736 #define LBM_SRC_SEND_EX_FLAG_APPHDR_CHAIN 0x8
00737 /*! Inform application of the UMQ Message ID used for the message */
00738 #define LBM_SRC_SEND_EX_FLAG_UMQ_MESSAGE_ID_INFO 0x10
00739 /*! Send messages using supplied channel information */
00740 #define LBM_SRC_SEND_EX_FLAG_CHANNEL 0x20
00741 /*! Send messages associating them with the supplied UMQ Index */
00742 #define LBM_SRC_SEND_EX_FLAG_UMQ_INDEX 0x40
00743 /*! umq_msg_total_lifetime is valid */
00744 #define LBM_SRC_SEND_EX_FLAG_UMQ_TOTAL_LIFETIME 0x80
00745 /*! Send messages marked as an optional message for Hot Failover */
00746 #define LBM_SRC_SEND_EX_FLAG_HF_OPTIONAL 0x100
00747 /*! Send message with the supplied messages properties */
00748 #define LBM_SRC_SEND_EX_FLAG_PROPERTIES 0x200
00749 /*! Send message with the supplied 32 bit hot failover sequence number */ 
00750 #define LBM_SRC_SEND_EX_FLAG_HF_32 0x400
00751 /*! Send message with the supplied 64 bit hot failover sequence number */
00752 #define LBM_SRC_SEND_EX_FLAG_HF_64 0x800
00753 
00754 /* Message properties types */
00755 /*! Message property with no type (used to indicate an iterator has reached the last element) */
00756 #define LBM_MSG_PROPERTY_NONE 0x0
00757 /*! Message property of boolean type */
00758 #define LBM_MSG_PROPERTY_BOOLEAN 0x1
00759 /*! Message property of byte type */
00760 #define LBM_MSG_PROPERTY_BYTE 0x2
00761 /*! Message property of short type (2 bytes)*/
00762 #define LBM_MSG_PROPERTY_SHORT 0x3
00763 /*! Message property of int type (4 bytes)*/
00764 #define LBM_MSG_PROPERTY_INT 0x4
00765 /*! Message property of long type (8 bytes)*/
00766 #define LBM_MSG_PROPERTY_LONG 0x5
00767 /*! Message property of float type */
00768 #define LBM_MSG_PROPERTY_FLOAT 0x6
00769 /*! Message property of double type */
00770 #define LBM_MSG_PROPERTY_DOUBLE 0x7
00771 /*! Message property of string type */
00772 #define LBM_MSG_PROPERTY_STRING 0x8
00773 
00774 /*! Maximum size for the name of a message property */
00775 #define LBM_MSG_PROPERTIES_MAX_NAMELEN 250
00776         
00777 /* appheader chain element types */
00778 /*! Element is a channel number in network byte order */
00779 #define LBM_CHAIN_ELEM_CHANNEL_NUMBER 0x1
00780 /*! Element is a hot-failover sequence number in network byte order */
00781 #define LBM_CHAIN_ELEM_HF_SQN 0x2
00782 /*! Element is gateway information */
00783 #define LBM_CHAIN_ELEM_GW_INFO 0x3
00784 /*! Element is a non-chain app header */
00785 #define LBM_CHAIN_ELEM_APPHDR 0x4
00786 /*! Element is user data with no byte-order transformation applied */
00787 #define LBM_CHAIN_ELEM_USER_DATA 0x5
00788 /*! Element is the offset of a serialized properties object within an LBM message */
00789 #define LBM_CHAIN_ELEM_PROPERTIES_LENGTH 0x6
00790 
00791 /* flags for registration successful extended event for UMP sources */
00792 /*! Registration was flagged as an old source by the store. An old source is one the store had cached. */
00793 #define LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS_EX_FLAG_OLD 0x1
00794 /*! Registration was flagged as coming from a store that is configured to not send ACKs for stability (no-cache store) */
00795 #define LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS_EX_FLAG_NOACKS 0x2
00796 /*! Registration was flagged as coming from a store that allows and has accepted RPP persistent topics */
00797 #define LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS_EX_FLAG_RPP 0x4
00798 
00799 /* flags for registration complete extended event for UMP sources */
00800 /*! Registration completed with only quorum reached. */
00801 #define LBM_SRC_EVENT_UME_REGISTRATION_COMPLETE_EX_FLAG_QUORUM 0x1
00802 
00803 /* flags for message stability extended event for UMP sources */
00804 /*! Message stable for intragroup stability */
00805 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX_FLAG_INTRAGROUP_STABLE 0x1
00806 /*! Message stable for intergroup stability */
00807 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX_FLAG_INTERGROUP_STABLE 0x2
00808 /*! Message is stable according to behavior desired */
00809 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX_FLAG_STABLE 0x4
00810 /*! Message stable information has active store information */
00811 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX_FLAG_STORE 0x8
00812 /*! Whole message (each fragment) is stable */
00813 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX_FLAG_WHOLE_MESSAGE_STABLE 0x10
00814 /*! Message stabilized via lbm_ume_src_msg_stable API */
00815 #define LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX_FLAG_USER 0x20
00816 
00817 /*! Message not stable information has store information */
00818 #define LBM_SRC_EVENT_UME_MESSAGE_NOT_STABLE_FLAG_STORE 0x8
00819 /*! Message not stable due to explicitly reported unrecoverable loss at the store or receiver. */
00820 #define LBM_SRC_EVENT_UME_MESSAGE_NOT_STABLE_FLAG_LOSS 0x40
00821 /*! Message not stable due to stability lifetime timeout. */
00822 #define LBM_SRC_EVENT_UME_MESSAGE_NOT_STABLE_FLAG_TIMEOUT 0x80
00823 
00824 /* flags for delivery confirmation extended event for UMP sources */
00825 /*! Confirmation received for specified number of unique ACKs. */
00826 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX_FLAG_UNIQUEACKS 0x1
00827 /*! Confirmation received with User Specified Rcv Registration ID flagged. */
00828 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX_FLAG_UREGID 0x2
00829 /*! Confirmation received with Out-of-Order Delivery (OOD) flagged. */
00830 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX_FLAG_OOD 0x4
00831 /*! Confirmation received with Explicit ACK (EXACK) flagged. */
00832 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX_FLAG_EXACK 0x8
00833 /*! Whole message (each fragment) has been confirmed */
00834 #define LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX_FLAG_WHOLE_MESSAGE_CONFIRMED 0x10
00835 
00836 /* flags for message reclaimed extended event for source */
00837 /*! Reclaim notification is the result of a forced reclaim */
00838 #define LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX_FLAG_FORCED 0x1
00839 
00840 /* flags for registration successful extended event for UMP receivers */
00841 /*! Registration was flagged as an old receiver by the store. An old receiver is one the store had cached. */
00842 #define LBM_MSG_UME_REGISTRATION_SUCCESS_EX_FLAG_OLD 0x1
00843 /*! Registration was flagged as coming from a store that is configured to not cache data. */
00844 #define LBM_MSG_UME_REGISTRATION_SUCCESS_EX_FLAG_NOCACHE 0x2
00845 /*! Registration was flagged as coming from a store that has allowed a RPP receiver */
00846 #define LBM_MSG_UME_REGISTRATION_SUCCESS_EX_FLAG_RPP 0x4
00847 /*! The src_session_id field of the lbm_msg_ume_registration_ex_t structure is valid */
00848 #define LBM_MSG_UME_REGISTRATION_SUCCESS_EX_FLAG_SRC_SID 0x8
00849 
00850 /* flags for recovery sequence number information structure */
00851 /* ! The src_session_id field of the lbm_ume_rcv_recovery_info_ex_func_info_t is valid. */
00852 #define LBM_UME_RCV_RECOVERY_INFO_EX_FLAG_SRC_SID 0x1
00853 
00854 /* flags for registration complete extended event for UMP receivers */
00855 /*! Registration completed with only quorum reached. */
00856 #define LBM_MSG_UME_REGISTRATION_COMPLETE_EX_FLAG_QUORUM 0x1
00857 /*! Registration completed with RX REQ maximum used. */
00858 #define LBM_MSG_UME_REGISTRATION_COMPLETE_EX_FLAG_RXREQMAX 0x2
00859 /*! The src_session_id field of the lbm_msg_ume_registration_complete_ex_t structure is valid */
00860 #define LBM_MSG_UME_REGISTRATION_COMPLETE_EX_FLAG_SRC_SID 0x4
00861 
00862 /*! Deregistration was flagged as coming from a RPP store */
00863 #define LBM_MSG_UME_DEREGISTRATION_SUCCESS_EX_FLAG_RPP 0x1
00864 
00865 /* flags for registration complete extended event for UMQ contexts */
00866 /*! Registration completed with only quorum reached. */
00867 #define LBM_CONTEXT_EVENT_UMQ_REGISTRATION_COMPLETE_EX_FLAG_QUORUM 0x1
00868 
00869 /* flags for registration complete extended event for UMQ sources */
00870 /*! Registration completed with only quorum reached. */
00871 #define LBM_SRC_EVENT_UMQ_REGISTRATION_COMPLETE_EX_FLAG_QUORUM 0x1
00872 /*! Message stable for intragroup stability */
00873 #define LBM_SRC_EVENT_UMQ_MESSAGE_STABLE_EX_FLAG_INTRAGROUP_STABLE 0x1
00874 /*! Message stable for intergroup stability */
00875 #define LBM_SRC_EVENT_UMQ_MESSAGE_STABLE_EX_FLAG_INTERGROUP_STABLE 0x2
00876 /*! Message is stable according to behavior desired */
00877 #define LBM_SRC_EVENT_UMQ_MESSAGE_STABLE_EX_FLAG_STABLE 0x4
00878 /*! Message stabilized via the lbm_umq_ctx_msg_stable API */
00879 #define LBM_SRC_EVENT_UMQ_MESSAGE_STABLE_EX_FLAG_USER 0x8
00880 
00881 /* flags for registration complete extended event for UMQ receivers */
00882 /*! Registration completed with only quorum reached. */
00883 #define LBM_MSG_UMQ_REGISTRATION_COMPLETE_EX_FLAG_QUORUM 0x1
00884 /*! Registration completed for UMQ ULB source. */
00885 #define LBM_MSG_UMQ_REGISTRATION_COMPLETE_EX_FLAG_ULB 0x2
00886 
00887 /* flags for deregistration complete extended event for UMQ receivers */
00888 /*! Deregistration completed for UMQ ULB source. */
00889 #define LBM_MSG_UMQ_DEREGISTRATION_COMPLETE_EX_FLAG_ULB 0x1
00890 
00891 /* flags for beginning of index event for UMQ receivers */
00892 /*! Beginning of index from ULB source. */
00893 #define LBM_MSG_UMQ_INDEX_ASSIGNED_EX_FLAG_ULB 0x1
00894 /*! Beginning of index assignment that was requested by receiver. */
00895 #define LBM_MSG_UMQ_INDEX_ASSIGNED_EX_FLAG_REQUESTED 0x2
00896 
00897 /* flags for end of index event for UMQ receivers */
00898 /*! End of index from ULB source. */
00899 #define LBM_MSG_UMQ_INDEX_RELEASED_EX_FLAG_ULB 0x1
00900 
00901 /* flags for index assignment stop complete extended event for UMQ receivers */
00902 /*! Index assignment stopped for ULB source. */
00903 #define LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX_FLAG_ULB 0x1
00904 
00905 /* flags for index assignment start complete extended event for UMQ receivers */
00906 /*! Index assignment started for ULB source. */
00907 #define LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX_FLAG_ULB 0x1
00908 
00909 /* flags for lbm_msg_umq_reassign */
00910 /*! Instead of requesting reassignment, request the message be discarded. */
00911 #define LBM_MSG_UMQ_REASSIGN_FLAG_DISCARD 0x1
00912 
00913 /* flags for ume receiver liveness */
00914 /* TMO means that the source context has not heard from a given receiver for
00915  * a specified amount of time and is therefore declared "dead". */
00916 #define LBM_UME_LIVENESS_RECEIVER_UNRESPONSIVE_FLAG_TMO 0x1
00917 
00918 /* EOF means that the receiver context has closed the response socket
00919  * and the source context declares the receiver "dead".
00920  */
00921 #define LBM_UME_LIVENESS_RECEIVER_UNRESPONSIVE_FLAG_EOF 0x2
00922 
00923 /* flags for lbm_umm_info_t */
00924 /*! Use SSL for UMM daemon connections. */
00925 #define LBM_UMM_INFO_FLAGS_USE_SSL 0x1
00926 
00927 /* 
00928         Possible JMS Message Types.  
00929 */
00930 #define LBM_TEXTMESSAGE         0
00931 #define LBM_BYTEMESSAGE         1
00932 #define LBM_MAPMESSAGE          2
00933 #define LBM_MESSAGE             3
00934 #define LBM_OBJECTMESSAGE       4
00935 #define LBM_STREAMMESSAGE       5
00936 
00937 /*
00938         List of JMS provider MessageProperties.  
00939 */
00940 
00941 /* int,  NON_PERSISTENT = 1, PERSISTENT = 2 */
00942 #define LBM_JMSDeliveryMode             "JMSDeliveryMode"
00943 
00944 /* long, Number of milliseconds since 1970. */
00945 #define LBM_JMSExpiration               "JMSExpiration"
00946 
00947 /* int */
00948 #define LBM_JMSPriority                 "JMSPriority"
00949 
00950 /* String */
00951 #define LBM_JMSMessageID                "JMSMessageID"
00952 
00953 /* long, Number of milliseconds since 1970. */
00954 #define LBM_JMSTimestamp                "JMSTimestamp"
00955 
00956 /* String */
00957 #define LBM_JMSCorrelationID    "JMSCorrelationID"
00958 
00959 /* String, topic, queue or destination */
00960 #define LBM_JMSType                             "JMSType"
00961 
00962 /* boolean */
00963 #define LBM_JMSRedelivered              "JMSRedelivered"
00964 
00965 /* int, LBM_TEXTMESSAGE, LBM_BYTEMESSAGE, LBM_MAPMESSAGE, LBM_MESSAGE, LBM_OBJECTMESSAGE, LBM_STREAMMESSAGE */
00966 #define LBM_LBMMessageType              "LBMMessageType"
00967 
00968 /* String, topic, queue or destination */
00969 #define LBM_JMSTopicType                "JMSTopicType"
00970 
00971 /* String */
00972 #define LBM_JMSReplyToName              "JMSReplyToName"
00973 
00974 /* boolean*/
00975 #define LBM_JMSReplyToWildcard  "JMSReplyToWildcard"
00976 
00977 /* String,  topic, queue or destination */
00978 #define LBM_JMSReplyToType              "JMSReplyToType"
00979 
00980 /* enums */
00981 enum {
00982         LBM_OK = 0,
00983         LBM_FAILURE = -1
00984 };
00985 
00986 /* Types */
00987 typedef unsigned int lbm_uint_t;
00988 typedef unsigned long int lbm_ulong_t;
00989 typedef unsigned short int lbm_ushort_t;
00990 typedef unsigned char lbm_uchar_t;
00991 typedef uint8_t lbm_uint8_t;
00992 typedef uint16_t lbm_uint16_t;
00993 typedef uint32_t lbm_uint32_t;
00994 typedef uint64_t lbm_uint64_t;
00995 
00996 #if !defined(DONT_TYPEDEF_INT_T)
00997 typedef int64_t lbm_int64_t;
00998 #else
00999 typedef __int64 lbm_int64_t;
01000 #endif
01001         
01002 #define LBM_EXTERNAL_STRUCT_FILL_SIZE   (512)
01003 
01004 #if defined(_WIN32)
01005 typedef SOCKET lbm_handle_t;
01006 #else
01007 typedef int lbm_handle_t;
01008 #endif /* _WIN32 */
01009 /*! \brief Context object (opaque) for UM.
01010 */
01011 struct lbm_context_t_stct;
01012 typedef struct lbm_context_t_stct lbm_context_t;
01013 
01014 /*! \brief Structure, struct iovec compatible, that holds information about buffers used for vectored sends
01015 
01016   UM replacement for struct iovec for portability.
01017 */
01018 typedef struct lbm_iovec_t_stct {
01019         /*! Pointer to a segment of application data */
01020         char *iov_base;
01021         /*! Number of bytes in this segment */
01022         size_t iov_len;
01023 } lbm_iovec_t;
01024 
01025 /*! \brief Structure that holds an IPv4 address and a CIDR style netmask
01026 
01027    A structure used with options to set/get specific addresses within a range.
01028  */
01029 typedef struct lbm_ipv4_address_mask_t_stct {
01030         /*! IPv4 address */
01031         lbm_uint_t addr;
01032         /*! Number of leading 1's in the netmask */
01033         int bits;
01034 } lbm_ipv4_address_mask_t;
01035 
01036 /*! \brief Structure that holds seconds and microseconds since midnight, Jan 1, 1970 UTC
01037   
01038   A structure included in UM messages to indicate when the message was
01039   received by UM. A message timestamp using this can be up to 500 milliseconds prior to actual
01040   receipt time, and hence, is not suitable when accurate message-arrival-time measurements are
01041   needed.
01042          */
01043 typedef struct lbm_timeval_t_stct {
01044         lbm_ulong_t tv_sec;
01045         lbm_ulong_t tv_usec;
01046 } lbm_timeval_t;
01047 
01048 /*! \brief Structure that holds source wakeup event data
01049 
01050    A structure used to indicate the type of source that is now unblocked.
01051 */
01052 typedef struct lbm_src_event_wakeup_t_stct {
01053         /*! OR'd set of flags indicating which context-level sources are now unblocked.
01054           Can contain one or more of LBM_SRC_EVENT_WAKEUP_FLAG_* */
01055         int flags;
01056 } lbm_src_event_wakeup_t;
01057 
01058 /*! \brief Structure that holds flight size notification event data
01059 
01060    A structure used to indicate a state change in flight size status
01061 */
01062 typedef struct lbm_src_event_flight_size_notification_t_stct {
01063         /*! Specifies which flight size's state changed */
01064         int type;
01065         /*! Current state of specified flight size */
01066         int state;
01067 } lbm_src_event_flight_size_notification_t;
01068 
01069 /*! \brief Structure that holds store registration information for the UMP source
01070 
01071   A structure used with UMP sources to indicate successful registration.
01072 */
01073 typedef struct lbm_src_event_ume_registration_t_stct {
01074         /*! The registration ID for the source */
01075         lbm_uint_t registration_id;
01076 } lbm_src_event_ume_registration_t;
01077 
01078 /*! \brief Structure that holds store registration information for the UMP source in an extended form
01079 
01080   A structure used with UMP sources to indicate successful registration (extended form).
01081 */
01082 typedef struct lbm_src_event_ume_registration_ex_t_stct {
01083         /*! Flags */
01084         int flags;
01085         /*! The registration ID for the source */
01086         lbm_uint_t registration_id;
01087         /*! The sequence number for the source to use as reported by the store */
01088         lbm_uint_t sequence_number;
01089         /*! The store index of the store involved */
01090         lbm_ushort_t store_index;
01091         /*! The store that was registered with */
01092         char store[LBM_UME_MAX_STORE_STRLEN];
01093 } lbm_src_event_ume_registration_ex_t;
01094 
01095 /*! \brief Structure that holds information for sources after registration is complete to all involved stores
01096 
01097   A structure used with UMP sources to indicate successful registration to quorum or to all stores involved.
01098 */
01099 typedef struct lbm_src_event_ume_registration_complete_ex_t_stct {
01100         /*! Flags */
01101         int flags;
01102         /*! The sequence number that will be the first sent */
01103         lbm_uint_t sequence_number;
01104 } lbm_src_event_ume_registration_complete_ex_t;
01105 
01106 /*! \brief Structure that holds store deregistration information for the UMP source in an extended form
01107  *
01108  * A structure used with UMP sources to indicate successful deregistration (extended form).
01109  */
01110 typedef struct lbm_src_event_ume_deregistration_ex_t_stct {
01111         /*! Flags */
01112         int flags;
01113         /*! The registration ID for the source */
01114         lbm_uint32_t registration_id;
01115         /*! The sequence number of the last message stored for the source as reported by the store */
01116         lbm_uint_t sequence_number;
01117         /*! The store index of the store involved. */
01118         lbm_ushort_t store_index;
01119         /*! The store that was registered with. */
01120         char store[LBM_UME_MAX_STORE_STRLEN];
01121 } lbm_src_event_ume_deregistration_ex_t;
01122 
01123 /*! \brief Structure that holds store registration information for the UMP receiver
01124 
01125   A structure used with UMP receivers to indicate successful registration.
01126 */
01127 typedef struct lbm_msg_ume_registration_t_stct {
01128         /*! The registration ID for the source */
01129         lbm_uint_t src_registration_id;
01130         /*! The registration ID for the receiver */
01131         lbm_uint_t rcv_registration_id;
01132 } lbm_msg_ume_registration_t;
01133 
01134 /*! \brief Structure that holds store registration information for the UM receiver in an extended form
01135 
01136   A structure used with UM receivers to indicate successful registration (extended form).
01137 */
01138 typedef struct lbm_msg_ume_registration_ex_t_stct {
01139         /*! Flags */
01140         int flags;
01141         /*! The registration ID for the source */
01142         lbm_uint_t src_registration_id;
01143         /*! The registration ID for the receiver */
01144         lbm_uint_t rcv_registration_id;
01145         /*! The sequence number for the receiver to start at as reported by the store */
01146         lbm_uint_t sequence_number;
01147         /*! The store index of the store involved */
01148         lbm_ushort_t store_index;
01149         /*! The store that was registered with */
01150         char store[LBM_UME_MAX_STORE_STRLEN];
01151         /*! The session ID for the source */
01152         lbm_uint64_t src_session_id;
01153 } lbm_msg_ume_registration_ex_t;
01154 
01155 /*! \brief Structure that holds information for receivers after registration is complete to all involved stores
01156 
01157   A structure used with UM receivers to indicate successful registration to quorum or to all stores involved.
01158 */
01159 typedef struct lbm_msg_ume_registration_complete_ex_t_stct {
01160         /*! Flags */
01161         int flags;
01162         /*! The sequence number that will be the first requested */
01163         lbm_uint_t sequence_number;
01164         /*! The session ID for the source */
01165         lbm_uint64_t src_session_id;
01166 } lbm_msg_ume_registration_complete_ex_t;
01167 
01168 /*! \brief Structure that holds store deregistration information for the UM receiver in an extended form.
01169  *
01170  *  A structure used with UM receivers to indicate successful deregistration (extended form).
01171  */
01172 typedef struct lbm_msg_ume_deregistration_ex_t_stct {
01173         /*! Flags */
01174         int flags;
01175         /*! The registration ID for the source */
01176         lbm_uint_t src_registration_id;
01177         /*! The registration ID for the receiver */
01178         lbm_uint_t rcv_registration_id;
01179         /*! The sequence number for the receiver to end at as reported by the store */
01180         lbm_uint_t sequence_number;
01181         /*! The store index of the store involved */
01182         lbm_ushort_t store_index;
01183         /*! The store that was registered with */
01184         char store[LBM_UME_MAX_STORE_STRLEN];
01185 } lbm_msg_ume_deregistration_ex_t;
01186 
01187 /*! \brief Structure that holds ACK information for a given message
01188 
01189   A structure used with UMP sources to indicate message acknowledgment by the store and UMP receivers.
01190 */
01191 typedef struct lbm_src_event_ume_ack_info_t_stct {
01192         /*! The sequence number of the message that is being acknowledged */
01193         lbm_uint_t sequence_number;
01194         /*! The registration ID for the receiver */
01195         lbm_uint_t rcv_registration_id;
01196         /*! The clientd pointer passed in for the message */
01197         void *msg_clientd;
01198 } lbm_src_event_ume_ack_info_t;
01199 
01200 /*! \brief Structure that holds ACK information for a given message in an extended form
01201 
01202   A structure used with UMP sources to indicate message acknowledgment by the store and UMP receivers or message stability information (extended form).
01203 */
01204 typedef struct lbm_src_event_ume_ack_ex_info_t_stct {
01205         /*! Flags */
01206         int flags;
01207         /*! The sequence number of the message */
01208         lbm_uint_t sequence_number;
01209         /*! The registration ID for the receiver, if applicable. This field is 0 (zero) if this struct is not being delivered as part of a confirmed delivery event. */
01210         lbm_uint_t rcv_registration_id;
01211         /*! The store involved. This field is 0 (zero) if the event applies to multiple stores or if using the structure for a delivery confirmation event. */
01212         char store[LBM_UME_MAX_STORE_STRLEN];
01213         /*! The clientd pointer passed in for the message */
01214         void *msg_clientd;
01215         /*! The store index of the store involved. This field is 0 (zero) if the event applies to multiple stores or if using the structure for a delivery confirmation event. */
01216         lbm_ushort_t store_index;
01217 } lbm_src_event_ume_ack_ex_info_t;
01218 
01219 /*! \brief Structure that holds information for source total inflight messages and bytes */
01220 typedef struct lbm_flight_size_inflight_t_stct {
01221         /*! Current amount of inflight messages */
01222         int messages;
01223         /*! Current amount of inflight payload bytes */
01224         lbm_uint64_t bytes;
01225 } lbm_flight_size_inflight_t;
01226 
01227 /*! \brief Opaque structure that holds information used for sending on channels
01228 */
01229 struct lbm_src_channel_info_t_stct;
01230 typedef struct lbm_src_channel_info_t_stct lbm_src_channel_info_t;
01231 
01232 /*! lbm_umq_index_info_t flags. Index is a 64-bit unsigned integer. */
01233 #define LBM_UMQ_INDEX_FLAG_NUMERIC 0x1
01234 
01235 /*! \brief Structure that holds information used for sending and receiving messages with UMQ indices
01236 
01237   A structure used with UM sources and receivers to associated UMQ Indices with messages.
01238  */
01239 typedef struct lbm_umq_index_info_t_stct {
01240         /*! Flags that indicate optional portions are included */
01241         int flags;
01242         /* UM internal only. DO NOT ACCESS DIRECTLY! */
01243         int reserved;
01244         /*! The index */
01245         char index[LBM_UMQ_MAX_INDEX_LEN];
01246         /*! The length of the index in bytes */
01247         size_t index_len;
01248 } lbm_umq_index_info_t;
01249 
01250 /*! \brief Structure that holds index assignment information for receivers
01251 
01252   A structure used with UMQ or ULB receivers to indicate the stop of index assignment from all queue instances involved.
01253 */
01254 typedef struct lbm_msg_umq_index_assignment_eligibility_stop_complete_ex_t_stct {
01255         /*! Flags that indicate which optional portions are included */
01256         int flags;
01257         /*! The Queue ID of the queue stopping index assignment eligibility */
01258         lbm_uint_t queue_id;
01259         /* The name of the queue */
01260         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01261 } lbm_msg_umq_index_assignment_eligibility_stop_complete_ex_t;
01262 
01263 
01264 /*! \brief Structure that holds beginning-of-index information for receivers
01265 
01266   A structure used with UMQ or ULB receivers to indicate the stop of index assignment from all queue instances involved.
01267 */
01268 typedef struct lbm_msg_umq_index_assigned_ex_t_stct {
01269         /*! Flags that indicate why the index was assigned to the receiver, etc. */
01270         int flags;
01271         /*! The Queue ID of the queue beginning assignment of this index */
01272         lbm_uint_t queue_id;
01273         /* The name of the queue */
01274         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01275         /* The index info. */
01276         lbm_umq_index_info_t index_info;
01277 } lbm_msg_umq_index_assigned_ex_t;
01278 
01279 /*! \brief Structure that holds end-of-index information for receivers
01280 
01281   A structure used with UMQ or ULB receivers to indicate the stop of index assignment from all queue instances involved.
01282 */
01283 typedef struct lbm_msg_umq_index_released_ex_t_stct {
01284         /*! Flags that indicate why the index was released (user-requested release, etc.) */
01285         int flags;
01286         /*! The Queue ID of the queue ending assignment of this index */
01287         lbm_uint_t queue_id;
01288         /* The name of the queue */
01289         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01290         /* The index info. */
01291         lbm_umq_index_info_t index_info;
01292 } lbm_msg_umq_index_released_ex_t;
01293 
01294 /*! \brief Structure that holds index assignment information for receivers
01295 
01296   A structure used with UMQ or ULB receivers to indicate the start of index assignment from all queue instances involved.
01297 */
01298 typedef struct lbm_msg_umq_index_assignment_eligibility_start_complete_ex_t_stct {
01299         /*! Flags that indicate which optional portions are included */
01300         int flags;
01301         /*! The Queue ID of the queue starting index assignment eligibility */
01302         lbm_uint_t queue_id;
01303         /* The name of the queue */
01304         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01305 } lbm_msg_umq_index_assignment_eligibility_start_complete_ex_t;
01306 
01307 /*! \brief Opaque structure used for sending messages with app header chains*/
01308 struct lbm_apphdr_chain_t_stct;
01309 typedef struct lbm_apphdr_chain_t_stct lbm_apphdr_chain_t;
01310 
01311 /*! \brief Structure that holds UMQ message total lifetime information
01312 
01313   A structure used with UMQ sources to specify a message's total lifetime.
01314  */
01315 typedef struct lbm_umq_msg_total_lifetime_info_t_stct {
01316         /*! Flags that indicate which optional portions are included */
01317         int flags;
01318         /*! The message's total lifetime, in milliseconds */
01319         lbm_ulong_t umq_msg_total_lifetime;
01320 } lbm_umq_msg_total_lifetime_info_t;
01321 
01322 /*! \brief Structure to hold a hot failover sequence number */
01323 typedef union lbm_hf_sequence_number_t_stct {
01324         /*! 32 bit hot failover sequence number */
01325         lbm_uint32_t u32;
01326         /*! 64 bit hot failover sequence number */
01327         lbm_uint64_t u64;
01328 } lbm_hf_sequence_number_t;
01329 
01330 /*! Registration ID used for UMQ contexts for both sources and receivers */
01331 typedef lbm_uint64_t lbm_umq_regid_t;
01332 
01333 /*! \brief Structure that holds information for UMQ messages that allows the message to be identified uniquely
01334 
01335         \sa lbm_umq_regid_t
01336         A structure used with UMQ messages to identify a message uniquely.
01337 */
01338 typedef struct lbm_umq_msgid_t_stct {
01339         /*! The Registration ID of the original source context of the message */
01340         lbm_umq_regid_t regid;
01341         /*! The stamp of the message that indicates the individual message from the given source context */
01342         lbm_uint64_t stamp;
01343 } lbm_umq_msgid_t;
01344 
01345 typedef struct lbm_umq_queue_application_set_t_stct {
01346         /*! Name of the application set as configured within the queue. */
01347         char appset_name[LBM_UMQ_MAX_APPSET_STRLEN];
01348         /*! Receiver Type IDs configured for this appset. */
01349         lbm_uint32_t *ids;
01350         /*! Number of receiver type IDs. */
01351         int num_ids;
01352         /*! Application set index. */
01353         lbm_ushort_t application_set_index;
01354         /* Reserved field; do not touch. */
01355         void *reserved;
01356 } lbm_umq_queue_application_set_t;
01357 
01358 /*! \brief Structure that holds queue topic information and can
01359            be used as a handle to a queue topic.
01360 */
01361 typedef struct lbm_umq_queue_topic_t_stct {
01362         /*! The topic name string. */
01363         char topic_name[LBM_UMQ_MAX_TOPIC_STRLEN];
01364         /*! Array of application sets within this topic. */
01365         lbm_umq_queue_application_set_t *appsets;
01366         /*! Length of the application sets array. */
01367         int num_appsets;
01368         /*! Reserved field; do not touch. */
01369         void *reserved;
01370 } lbm_umq_queue_topic_t;
01371 
01372 /*! \brief Struct containing extended asynchronous operation status information about a single UMQ topic. */
01373 typedef struct {
01374         /*! UMQ topic info. */
01375         lbm_umq_queue_topic_t *topic;
01376         /*! Status code for this topic (reserved for future use; will currently always be set to 0). */
01377         int status;
01378         /*! Reserved flags field. */
01379         int flags;
01380 } lbm_umq_queue_topic_status_t;
01381 
01382 /*! \brief Struct containing an array of queue topics retrieved via lbm_umq_queue_topic_list. */
01383 typedef struct {
01384         /*! An array of UMQ topic status objects. */
01385         lbm_umq_queue_topic_status_t *topics;
01386         /*! The length, in number of elements, of the topic objects array. */
01387         int num_topics;
01388 } lbm_ctx_umq_queue_topic_list_info_t;
01389 
01390 struct lbm_msg_t_stct;
01391 typedef struct lbm_msg_t_stct lbm_msg_t;
01392 
01393 /*! \brief Opaque structure that designates a UM event queue object
01394 */
01395 struct lbm_event_queue_t_stct;
01396 typedef struct lbm_event_queue_t_stct lbm_event_queue_t;
01397 
01398 /*! \brief Queue message status; queue has no knowledge of the message. */
01399 #define LBM_UMQ_QUEUE_MSG_STATUS_UNKNOWN 0
01400 /*! \brief Queue message status; message is currently enqueued but not yet assigned. */
01401 #define LBM_UMQ_QUEUE_MSG_STATUS_UNASSIGNED 1
01402 /*! \brief Queue message status; message is currently assigned to a receiver but not yet consumed. */
01403 #define LBM_UMQ_QUEUE_MSG_STATUS_ASSIGNED 2
01404 /*! \brief Queue message status; message is waiting to be re-assigned to a different receiver. */
01405 #define LBM_UMQ_QUEUE_MSG_STATUS_REASSIGNING 3
01406 /*! \brief Queue message status; message has been fully consumed and is no longer present in the queue. */
01407 #define LBM_UMQ_QUEUE_MSG_STATUS_CONSUMED 4
01408 
01409 /*! \brief Struct containing extended asynchronous operation status information about a single UMQ message. */
01410 typedef struct {
01411         /*! UMQ message ID of this message. */
01412         lbm_umq_msgid_t msgid;
01413         /*! Actual message, if appropriate and available (NULL otherwise) */
01414         lbm_msg_t *msg;
01415         /*! User client data pointer. */
01416         void *clientd;
01417         /*! Status code for this message (retrieval in progress, consumed, etc.) */
01418         int status;
01419         /*! Reserved flags field. */
01420         int flags;
01421 } lbm_umq_queue_msg_status_t;
01422 
01423 /*! \brief Struct containing an array of UMQ messages listed via lbm_rcv_umq_queue_msg_list. */
01424 typedef struct {
01425         /*! An array of queued messages. */
01426         lbm_umq_queue_msg_status_t *msgs;
01427         /*! The length of the queued messages array. */
01428         lbm_uint64_t num_msgs;
01429 } lbm_rcv_umq_queue_msg_list_info_t;
01430 
01431 /*! \brief Struct containing an array of UMQ messages retrieved via lbm_rcv_umq_queue_msg_retrieve. */
01432 typedef struct {
01433         /*! An array of the retrieved messages. */
01434         lbm_umq_queue_msg_status_t *msgs;
01435         /*! The length of the retrieved message array. */
01436         int num_msgs;
01437 } lbm_rcv_umq_queue_msg_retrieve_info_t;
01438 
01439 /*! Asynchronous operation type. UMQ queue topic list. */
01440 #define LBM_ASYNC_OP_TYPE_CTX_UMQ_QUEUE_TOPIC_LIST 1
01441 /*! Asynchronous operation type. UMQ queue message list. */
01442 #define LBM_ASYNC_OP_TYPE_RCV_UMQ_QUEUE_MSG_LIST 2
01443 /*! Asynchronous operation type. UMQ queue message retrieve. */
01444 #define LBM_ASYNC_OP_TYPE_RCV_UMQ_QUEUE_MSG_RETRIEVE 3
01445 
01446 /*! Asynchronous operation status code. Overall operation is still in progress. */
01447 #define LBM_ASYNC_OP_STATUS_IN_PROGRESS 1
01448 /*! Asynchronous operation status code. Overall operation has completed successfully. This is a terminal status code. */
01449 #define LBM_ASYNC_OP_STATUS_COMPLETE 128
01450 /*! Asynchronous operation status code. Overall operation has failed. This is a terminal status code. */
01451 #define LBM_ASYNC_OP_STATUS_ERROR 129
01452 /*! Asynchronous operation status code. Overall operation has been successfully canceled. This is a terminal status code. */
01453 #define LBM_ASYNC_OP_STATUS_CANCELED 130
01454 
01455 /*! Invalid asynchronous operation handle. */
01456 #define LBM_ASYNC_OP_INVALID_HANDLE 0
01457 
01458 /*! lbm_async_operation_cancel flag.  Do not block if the operation cannot be immediately canceled. */
01459 #define LBM_ASYNC_OPERATION_CANCEL_FLAG_NONBLOCK 0x1
01460 
01461 /*! lbm_async_operation_status flag.  Do not block if the operation's status cannot be retrieved immediately. */
01462 #define LBM_ASYNC_OPERATION_STATUS_FLAG_NONBLOCK 0x1
01463 
01464 /*! \brief Opaque handle to an asynchronous operation.
01465 */
01466 typedef lbm_uint64_t lbm_async_operation_handle_t;
01467 
01468 /*! \brief Results struct returned via the user-specified asynchronous operation callback from any
01469            asynchronous API.
01470 
01471     \sa LBM_ASYNC_OP_TYPE_CTX_UMQ_QUEUE_TOPIC_LIST
01472     \sa LBM_ASYNC_OP_TYPE_RCV_UMQ_QUEUE_MSG_LIST
01473     \sa LBM_ASYNC_OP_TYPE_RCV_UMQ_QUEUE_MSG_RETRIEVE
01474 */
01475 typedef struct {
01476         /*! The type of asynchronous operation. */
01477         int type;
01478         /*! The current status of the operation. */
01479         int status;
01480         /*! Flags with extra information about the async operation. */
01481         int flags;
01482         /*! An opaque handle to the asynchronous operation. */
01483         lbm_async_operation_handle_t handle;
01484         /*! Operation-specific results. */
01485         union {
01486                 lbm_ctx_umq_queue_topic_list_info_t *ctx_umq_queue_topic_list;
01487                 lbm_rcv_umq_queue_msg_list_info_t *rcv_umq_queue_msg_list;
01488                 lbm_rcv_umq_queue_msg_retrieve_info_t *rcv_umq_queue_msg_retrieve;
01489         } info;
01490 } lbm_async_operation_info_t;
01491 
01492 /*! \brief Resolver event structure (for internal use only).
01493 */
01494 typedef struct lbm_resolver_event_info_t_stct {
01495     lbm_uint64_t info_flags;
01496     lbm_uint32_t capability_flags;
01497     lbm_uint8_t source_type;
01498     lbm_uint32_t domain_id;
01499     lbm_uint32_t version;
01500         lbm_uint8_t source_id[8];
01501 } lbm_resolver_event_info_t;
01502 
01503 /*! \brief Resolver event callback signature (for internal use only).
01504 */
01505 typedef lbm_uint32_t (*lbm_resolver_event_cb_func) (lbm_context_t *ctx, int event, const void * ed, const lbm_resolver_event_info_t * info, void *clientd);
01506 
01507 #define LBM_RESOLVER_EVENT_ADVERTISEMENT_TYPE 0x01
01508 
01509 #define LBM_RESOLVER_EVENT_ADVERTISEMENT_FLAGS_LJ  0x00000001
01510 #define LBM_RESOLVER_EVENT_ADVERTISEMENT_FLAGS_UME 0x00000002
01511 #define LBM_RESOLVER_EVENT_ADVERTISEMENT_FLAGS_UMQ 0x00000004
01512 #define LBM_RESOLVER_EVENT_ADVERTISEMENT_FLAGS_ULB 0x00000008
01513 #define LBM_RESOLVER_EVENT_ADVERTISEMENT_FLAGS_EVC 0x00000010    /* Eviction Notice */
01514 
01515 /*! \brief Advertisement event structure (for internal use only).
01516 */
01517 typedef struct lbm_resolver_event_advertisement_t_stct {
01518         lbm_uint32_t flags;
01519         char topic_string[LBM_MSG_MAX_TOPIC_LEN];
01520         char transport_string[LBM_MSG_MAX_SOURCE_LEN];
01521         lbm_uint32_t topic_index;
01522         lbm_uint32_t source_domain_id;
01523         lbm_uint8_t otid[LBM_OTID_BLOCK_SZ];
01524         lbm_uint32_t source_type;
01525 } lbm_resolver_event_advertisement_t;
01526 
01527 /*! \brief Resolver event function (for internal use only).
01528 */
01529 typedef struct lbm_resolver_event_func_t_stct {
01530         lbm_resolver_event_cb_func event_cb_func;
01531         void * clientd;
01532 } lbm_resolver_event_func_t;
01533 
01534 
01535 #define LBM_RESOLVER_EVENT_INFO_CAPABILITY_VERSION_FLAG_UME 0x1
01536 #define LBM_RESOLVER_EVENT_INFO_CAPABILITY_VERSION_FLAG_UMQ 0x2
01537 
01538 
01539 #define LBM_RESOLVER_EVENT_INFO_INFO_DOMAIN_ID_PRESENT_FLAG 0x1ULL
01540 #define LBM_RESOLVER_EVENT_INFO_INFO_SOURCE_ID_PRESENT_FLAG 0x2ULL
01541 #define LBM_RESOLVER_EVENT_INFO_INFO_SOURCE_ID_TYPE_PRESENT_FLAG 0x4ULL
01542 #define LBM_RESOLVER_EVENT_INFO_INFO_VERSION_PRESENT_FLAG 0x8ULL
01543 
01544 #define LBMR_RESOLVER_EVENT_INFO_SRC_TYPE_APPLICATION 0
01545 #define LBMR_RESOLVER_EVENT_INFO_SRC_TYPE_TNWGD 1
01546 #define LBMR_RESOLVER_EVENT_INFO_SRC_TYPE_STORE 2
01547 
01548 
01549 /*! \brief User-supplied application callback for asynchronous operation status and completion.
01550 
01551   \param opinfo Operation-specific results.
01552   \param clientd Client data pointer supplied in in the lbm_async_operation_func_t struct passed in to an asynchronous API call.
01553   \return 0 for Success, -1 for Failure.
01554 */
01555 typedef int (*lbm_async_operation_function_cb)(lbm_async_operation_info_t *opinfo, void *clientd);
01556 
01557 /*! lbm_async_operation_info_t flag.  Asynchronous operation callback is being called
01558  * directly inline from within an API call. */
01559 #define LBM_ASYNC_OP_INFO_FLAG_INLINE 0x1
01560 /*! lbm_async_operation_info_t flag.  This is the very first notification for this particular asynchronous operation. */
01561 #define LBM_ASYNC_OP_INFO_FLAG_FIRST 0x2
01562 /*! lbm_async_operation_info_t flag.  This is the very last notification for this particular asynchronous operation. */
01563 #define LBM_ASYNC_OP_INFO_FLAG_LAST 0x4
01564 /*! lbm_async_operation_info_t flag.  This is the only notification that will be delivered for this particular asynchronous operation. */
01565 #define LBM_ASYNC_OP_INFO_FLAG_ONLY (LBM_ASYNC_OP_INFO_FLAG_FIRST | LBM_ASYNC_OP_INFO_FLAG_LAST)
01566 
01567 /*! \brief Structure that holds information for asynchronous operation callbacks.
01568 
01569  */
01570 typedef struct {
01571         /*! A callback function to receive status and completion of an asynchronous operation. */
01572         lbm_async_operation_function_cb func;
01573         /*! An event queue pointer; not yet supported.  Should be set to NULL. */
01574         lbm_event_queue_t *evq;
01575         /*! A client object pointer to be passed back in to the specified callback. */
01576         void *clientd;
01577         /*! Flags that indicate which optional portions are included and may affect callback behavior. */
01578         int flags;
01579 } lbm_async_operation_func_t;
01580 
01581 /*! \brief A struct that holds information used for messages with properties. (opaque)
01582 */
01583 struct lbm_msg_properties_t_stct;
01584 typedef struct lbm_msg_properties_t_stct lbm_msg_properties_t;
01585 
01586 /*! \brief Structure that holds information for the extended send calls
01587   A structure used with UM sources that utilize the extended send calls to pass options.
01588 
01589         \sa lbm_src_send_ex
01590 */
01591 typedef struct lbm_src_send_ex_info_t_stct {
01592         /*! Flags that set which settings are active as defined by "LBM_SRC_SEND_EX_*". 
01593         Search lbm.h for LBM_SRC_SEND_EX_FLAG_*. */
01594         int flags;
01595         /*! client data pointer to be passed back in source events for stability and confirmations */
01596         void *ume_msg_clientd;
01597         /*! pointer to information used to send messages on a channel */
01598         lbm_src_channel_info_t *channel_info;
01599         /*! pointer to information used to send messages using app header chains */
01600         lbm_apphdr_chain_t *apphdr_chain;
01601         /*! pointer to information used to send messages and associate them with a given UMQ index */
01602         lbm_umq_index_info_t *umq_index;
01603         /*! pointer to information used to specify a message's total lifetime */
01604         lbm_umq_msg_total_lifetime_info_t *umq_total_lifetime;
01605         /*! pointer to a message properties structure */
01606         lbm_msg_properties_t *properties;
01607         /*! The hot failover sequence number to send */
01608         lbm_hf_sequence_number_t hf_sqn;
01609         /*! pointer to an asynchronous operation callback */
01610         lbm_async_operation_func_t *async_opfunc;
01611 } lbm_src_send_ex_info_t;
01612 
01613 /*! \brief Structure that holds information for UMP receiver registration ID application callbacks
01614 
01615   A structure used with UMP receiver registration ID callbacks to pass in information.
01616 
01617         \sa lbm_ume_rcv_regid_func_t
01618 */
01619 typedef struct lbm_ume_rcv_regid_ex_func_info_t_stct {
01620         /*! Flags that indicate which optional portions are included */
01621         int flags;
01622         /*! The registration ID for the source */
01623         lbm_uint_t src_registration_id;
01624         /*! The store index of the store involved */
01625         lbm_ushort_t store_index;
01626         /*! The per-source clientd value for the source set by the
01627          lbm_rcv_src_notification_create_function_cb callback */
01628         void *source_clientd;
01629         /*! The source for the registration ID */
01630         char source[LBM_MSG_MAX_SOURCE_LEN];
01631         /*! The store involved */
01632         char store[LBM_UME_MAX_STORE_STRLEN];
01633 } lbm_ume_rcv_regid_ex_func_info_t;
01634 
01635 /*! \brief Structure that holds sequence number information for a message sent by a source
01636 
01637   A structure used with UM sources that informs the application the sequence numbers used with a message.
01638 
01639   \sa lbm_src_send_ex
01640 */
01641 typedef struct lbm_src_event_sequence_number_info_t_stct {
01642         /*! Flags that indicate which optional portions are included */
01643         int flags;
01644         /*! First sequence number for the message set */
01645         lbm_uint_t first_sequence_number;
01646         /*! Last sequence number for the message set */
01647         lbm_uint_t last_sequence_number;
01648         /*! The clientd pointer passed in for the message */
01649         void *msg_clientd;
01650 } lbm_src_event_sequence_number_info_t;
01651 
01652 /*! \brief Structure that holds information for UMP receiver recovery sequence number info application callbacks
01653 
01654    A structure used with UMP receiver recovery sequence number information callbacks to pass in information as well
01655    as return low sequence number information.
01656 
01657    \sa lbm_ume_rcv_recovery_info_ex_func_t
01658 */
01659 typedef struct lbm_ume_rcv_recovery_info_ex_func_info_t_stct {
01660         /*! Flags that indicate optional portions that are included */
01661         int flags;
01662         /*! Lowest sequence number that the receiver will attempt to recover. May be altered to
01663          instruct UMP to recover differently */
01664         lbm_uint_t low_sequence_number;
01665         /*! Lowest sequence number that the receiver will attempt to recover (with retransmit request maximum taken into account) */
01666         lbm_uint_t low_rxreq_max_sequence_number;
01667         /*! Highest sequence number that the receiver has seen from the source. May not be actual highest sent by source */
01668         lbm_uint_t high_sequence_number;
01669         /*! The per-source clientd value for the source set by the
01670          lbm_rcv_src_notification_create_function_cb callback */
01671         void *source_clientd;
01672         /*! The source */
01673         char source[LBM_MSG_MAX_SOURCE_LEN];
01674         /*! The session ID for the source */
01675         lbm_uint64_t src_session_id;
01676 } lbm_ume_rcv_recovery_info_ex_func_info_t;
01677 
01678 /*! \brief Structure that holds Message ID information for a message sent by a sending UMQ application
01679 
01680         \sa lbm_src_send_ex
01681         A structure used with UMQ sending applications that informs the application of the UMQ Message ID used with a message.
01682 */
01683 typedef struct lbm_src_event_umq_message_id_info_t_stct {
01684         /*! Flags that indicate which optional portions are included */
01685         int flags;
01686         /*! Message ID for the message sent */
01687         lbm_umq_msgid_t msg_id;
01688         /*! The clientd pointer passed in for the message */
01689         void *msg_clientd;
01690 } lbm_src_event_umq_message_id_info_t;
01691 
01692 /*! \brief Structure that holds queue registration information for the UMQ context in an extended form
01693 
01694   A structure used with UMQ receivers and sources to indicate successful context registration with an instance of
01695   the queue.
01696 */
01697 typedef struct lbm_context_event_umq_registration_ex_t_stct {
01698         /*! Flags that indicate which optional portions are included */
01699         int flags;
01700         /*! Registration ID used for the registration */
01701         lbm_umq_regid_t registration_id;
01702         /*! The Queue ID of the queue */
01703         lbm_uint_t queue_id;
01704         /*! The index of the instance of the queue registered with */
01705         lbm_uint_t queue_instance_index;
01706         /*! The instance of the queue registered with */
01707         char queue_instance[LBM_UME_MAX_STORE_STRLEN];
01708         /*! The name of the queue registered with */
01709         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01710 } lbm_context_event_umq_registration_ex_t;
01711 
01712 /*! \brief Structure that holds information for contexts after registration is complete to all involved queue instances
01713 
01714   A structure used with UMQ receivers and sources to indicate successful context registration to quorum or to all queue instances involved.
01715 */
01716 typedef struct lbm_context_event_umq_registration_complete_ex_t_stct {
01717         /*! Flags that indicate which optional portions are included */
01718         int flags;
01719         /*! Registration ID used for the registration */
01720         lbm_umq_regid_t registration_id;
01721         /*! The Queue ID of the queue */
01722         lbm_uint_t queue_id;
01723         /*! The name of the queue registered with */
01724         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01725 } lbm_context_event_umq_registration_complete_ex_t;
01726 
01727 /*! \brief Structure that holds information for sources after registration is complete to all involved queue instances
01728 
01729   A structure used with UMQ sources to indicate successful source registration to quorum or to all queue instances involved.
01730 */
01731 typedef struct lbm_src_event_umq_registration_complete_ex_t_stct {
01732         /*! Flags that indicate which optional portions are included */
01733         int flags;
01734         /*! The Queue ID of the queue */
01735         lbm_uint_t queue_id;
01736         /*! The name of the queue registered with */
01737         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01738 } lbm_src_event_umq_registration_complete_ex_t;
01739 
01740 /*! \brief Structure that holds information for receivers after registration is complete to all involved queue instances
01741 
01742   A structure used with UMQ receivers to indicate successful receiver registration to quorum or to all queue instances involved.
01743 */
01744 typedef struct lbm_msg_umq_registration_complete_ex_t_stct {
01745         /*! Flags that indicate which optional portions are included */
01746         int flags;
01747         /*! The Queue ID of the queue */
01748         lbm_uint_t queue_id;
01749         /*! The generated Assignment ID for the receiver with the queue */
01750         lbm_uint_t assignment_id;
01751         /*! The name of the queue registered with */
01752         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01753 } lbm_msg_umq_registration_complete_ex_t;
01754 
01755 /*! \brief Structure that holds UMQ ACK information for a given message in an extended form
01756 
01757   A structure used with UMQ source applications to indicate message acknowledgment by a queue instance.
01758 */
01759 typedef struct lbm_src_event_umq_stability_ack_info_ex_t_stct {
01760         /*! Flags that indicate which optional portions are included */
01761         int flags;
01762         /*! Message ID of the message being acknowledged */
01763         lbm_umq_msgid_t msg_id;
01764         /*! First sequence number for the message after being fragmented */
01765         lbm_uint_t first_sequence_number;
01766         /*! Last sequence number for the message after being fragmented */
01767         lbm_uint_t last_sequence_number;
01768         /*! The Queue ID of the queue */
01769         lbm_uint_t queue_id;
01770         /*! The index of the instance of the queue acknowledging the message */
01771         lbm_uint_t queue_instance_index;
01772         /*! The clientd pointer passed in for the message */
01773         void *msg_clientd;
01774         /*! The instance of the queue acknowledging the message */
01775         char queue_instance[LBM_UME_MAX_STORE_STRLEN];
01776         /*! The name of the queue */
01777         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01778 } lbm_src_event_umq_stability_ack_info_ex_t;
01779 
01780 /*! \brief Structure that holds information for receivers after they de-register from a queue
01781 
01782         A struct used with UMQ receivers to indicate successful de-registration from a queue.
01783 */
01784 typedef struct lbm_msg_umq_deregistration_complete_ex_t_stct {
01785         /*! Flags that indicate which optional portions are included */
01786         int flags;
01787         /*! The Queue ID of the queue de-registering from */
01788         lbm_uint_t queue_id;
01789         /* The name of the queue */
01790         char queue[LBM_UMQ_MAX_QUEUE_STRLEN];
01791 } lbm_msg_umq_deregistration_complete_ex_t;
01792 
01793 /*! \brief Structure that holds UMQ ULB receiver information in an extended form
01794 
01795   A structure used with UMQ ULB source applications to indicate receiver events.
01796 */      
01797 typedef struct lbm_src_event_umq_ulb_receiver_info_ex_t_stct {
01798         /*! Flags that indicate which optional portions are included */
01799         int flags;
01800         /*! The registration ID of the receiver */
01801         lbm_umq_regid_t registration_id;
01802         /*! The Assignment ID of the receiver */
01803         lbm_uint_t assignment_id;
01804         /*! The Application Set Index the receiver is in */
01805         lbm_uint_t application_set_index;
01806         /*! The receivers immediate message target string */
01807         char receiver[LBM_UMQ_ULB_MAX_RECEIVER_STRLEN];
01808 } lbm_src_event_umq_ulb_receiver_info_ex_t;
01809 
01810 /*! \brief Structure that holds UMQ ULB message information in an extended form
01811 
01812   A structure used with UMQ ULB source applications to indicate message events.
01813 */
01814 typedef struct lbm_src_event_umq_ulb_message_info_ex_t_stct {
01815         /*! Flags that indicate which optional portions are included */
01816         int flags;
01817         /*! Message ID of the message */
01818         lbm_umq_msgid_t msg_id;
01819         /*! The registration ID of the receiver */
01820         lbm_umq_regid_t registration_id;
01821         /*! First sequence number for the message after being fragmented */
01822         lbm_uint_t first_sequence_number;
01823         /*! Last sequence number for the message after being fragmented */
01824         lbm_uint_t last_sequence_number;
01825         /*! The Assignment ID of the receiver */
01826         lbm_uint_t assignment_id;
01827         /*! The Application Set Index the receiver is in */
01828         lbm_uint_t application_set_index;
01829         /*! The clientd pointer passed in for the message */
01830         void *msg_clientd;
01831         /*! The receivers immediate message target string */
01832         char receiver[LBM_UMQ_ULB_MAX_RECEIVER_STRLEN];
01833 } lbm_src_event_umq_ulb_message_info_ex_t;
01834 
01835 /*! \brief Application callback for user-supplied topic hash function
01836 
01837            Set by lbm_context_attr_setopt() with option "resolver_string_hash_function".
01838            NOTE: this application callback is always made from the context
01839            thread, and is therefore limited in the UM API calls it can make.
01840   \param str String to be hashed.
01841   \return hash value 0..(lbm_ulong_t)-1
01842 */
01843 typedef lbm_ulong_t (*lbm_str_hash_function_cb)(const char *str);
01844 
01845 /*! \brief Application callback for user-supplied extended version of the topic hash function
01846 
01847            Set by lbm_context_attr_setopt() with option "resolver_string_hash_function_ex".
01848            NOTE: this application callback is always made from the context
01849            thread, and is therefore limited in the UM API calls it can make.
01850   \param str String to be hashed.
01851   \param strlen Length of str IF AVAILABLE, (lbm_ulong_t)-1 if not calculated by lbm
01852   \param clientd Client data pointer supplied in in the lbm_str_hash_func_ex_t passed to the lbm_context_attr_setopt().
01853   \return hash value 0..(lbm_ulong_t)-1
01854 */
01855 typedef lbm_ulong_t (*lbm_str_hash_function_cb_ex)(const char *str, size_t strlen, void* clientd);
01856 
01857 
01858 /*! \brief Application callback to inform application of the presence of new
01859            sources for topics.
01860 
01861            Set by lbm_context_attr_setopt() with option
01862            "resolver_source_notification_function".  NOTE: this
01863            application callback is always made from the context
01864            thread, and is therefore limited in the UM API calls it
01865            can make.
01866   \sa lbm_src_notify_func_t
01867   \param topic_str Name of topic for which a source has been found.
01868   \param src_str Source as a string.  Format depends on transport type.
01869         For string formats and examples, see lbm_transport_source_info_t_stct.
01870   \param clientd Client data pointer supplied in the lbm_src_notify_func_t passed to the lbm_context_attr_setopt().
01871   \return 0 always.
01872 */
01873 typedef int (*lbm_src_notify_function_cb)(const char *topic_str, const char *src_str, void *clientd);
01874 
01875 /*! \brief Application callback for application-supplied wildcard matching
01876 
01877            Set by lbm_wildcard_rcv_attr_setopt() with option
01878            "pattern_callback".
01879            NOTE: this application callback is always made from the context
01880            thread, and is therefore limited in the UM API calls it can make.
01881   \sa lbm_wildcard_rcv_compare_func_t
01882   \param topic_str Name of topic to be checked for match.
01883   \param clientd Client data pointer supplied in the lbm_wildcard_rcv_compare_func_t passed to lbm_wildcard_rcv_attr_setopt() with the "pattern_callback" attribute.
01884   \return 0 for match and 1 for no match.
01885 */
01886 typedef int (*lbm_wildcard_rcv_compare_function_cb)(const char *topic_str, void *clientd);
01887 
01888 /*! \brief Application callback to set the registration ID for a receiver for a specific source
01889 
01890            Set by lbm_rcv_topic_attr_setopt() with option
01891                    "ume_registration_function". NOTE: this application
01892                    callback is always made from the context thread, and is therefore limited
01893                    in the UM API calls it can make.
01894   \sa lbm_ume_rcv_regid_func_t
01895   \param src_str Name of the source for the ID.
01896   \param src_regid Registration ID for the source for this topic.
01897   \param clientd Client data pointer supplied in the lbm_ume_rcv_regid_func_t passed to lbm_rcv_topic_attr_setopt() with the "ume_registration_function" attribute.
01898   \return Registration ID to be used by receiver for given source and topic.
01899 */
01900 typedef lbm_uint_t (*lbm_ume_rcv_regid_function_cb)(const char *src_str, lbm_uint_t src_regid, void *clientd);
01901 
01902 /*! \brief Application callback to set the registration ID for a receiver for a specific source, extended form
01903 
01904            Set by lbm_rcv_topic_attr_setopt() with option
01905                    "ume_registration_extended_function". NOTE: this application
01906                    callback is always made from the context thread, and is therefore limited
01907                    in the UM API calls it can make.
01908   \sa lbm_ume_rcv_regid_ex_func_t
01909   \param info Structure holding registration information in an extended form
01910   \param clientd Client data pointer supplied in the lbm_ume_rcv_regid_ex_func_t passed to lbm_rcv_topic_attr_setopt() with the "ume_registration_extended_function" attribute.
01911   \return Registration ID to be used by receiver for given source and topic.
01912 */
01913 typedef lbm_uint_t (*lbm_ume_rcv_regid_ex_function_cb)(lbm_ume_rcv_regid_ex_func_info_t *info, void *clientd);
01914 
01915 /*! \brief Application callback for notification of forced reclamation of retained messages for UMP sources
01916 
01917                 Set by lbm_src_topic_attr_setopt() with option
01918                 "ume_force_reclaim_function". NOTE: this application callback
01919                 is always made from the context thread and is therefore limited
01920                 in the UM API calls it can make.
01921     \sa lbm_ume_src_force_reclaim_func_t
01922         \param topic_str Name of the topic for the reclaim
01923         \param seqnum Sequence Number that is reclaimed
01924         \param clientd Client data pointer supplied in the lbm_ume_src_force_reclaim_func_t passed to lbm_src_topic_attr_setopt() with the "ume_force_reclaim_function" attribute.
01925         \return 0 always.
01926 */
01927 typedef int (*lbm_ume_src_force_reclaim_function_cb)(const char *topic_str, lbm_uint_t seqnum, void *clientd);
01928 
01929 /*! \brief Application callback in receiving application for notification of unrecoverable lost messages from a multicast immediate message sender
01930 
01931                 Set by lbm_context_attr_setopt() with option
01932                 "mim_unrecoverable_loss_function". NOTE: this application callback
01933                 is always made from the context thread and is therefore limited
01934                 in the UM API calls it can make.
01935     \sa lbm_mim_unrecloss_func_t
01936         \param source_name Name of the source
01937         \param seqnum Sequence Number that is lost
01938         \param clientd Client data pointer supplied in the lbm_mim_unrecloss_func_t passed to lbm_context_attr_setopt() with the "mim_unrecoverable_loss_function" attribute.
01939         \return 0 always.
01940 */
01941 typedef int (*lbm_mim_unrecloss_function_cb)(const char *source_name, lbm_uint_t seqnum, void *clientd);
01942 
01943 /*! \brief Application callback to set the lowest sequence number to be requested during recovery, extended form
01944 
01945                 Set by lbm_rcv_topic_attr_setopt() with option "ume_recovery_sequence_number_info_function".
01946                 NOTE: this application callback is always made from the context thread, and is therefore limited
01947                 in the UM API calls it can make.
01948    \sa lbm_ume_rcv_recovery_info_ex_func_t
01949    \param info Structure to hold recovery sequence number information in an extended form
01950    \param clientd Client data pointer supplied in the lbm_ume_rcv_recovery_info_ex_func_t passed to lbm_rcv_topic_attr_setopt() with the "ume_recovery_sequence_number_info_function" attribute.
01951    \return 0 always
01952 */
01953 typedef int (*lbm_ume_rcv_recovery_info_ex_function_cb)(lbm_ume_rcv_recovery_info_ex_func_info_t *info, void *clientd);
01954 
01955 /*! \brief Application callback for notification of creation of sources for a topic
01956 
01957                 Set by lbm_rcv_topic_attr_setopt() with option "source_notification_function".
01958                 NOTE: this application callback is always made from the context thread and is therefore limited
01959                 in the UM API calls it can make.
01960         \sa lbm_rcv_src_notification_func_t
01961         \param source_name Name of the source
01962         \param clientd Client data pointer supplied in the lbm_rcv_src_notification_func_t passed to lbm_context_attr_setopt() with the "source_notification_function" attribute.
01963         \return void pointer to be set for all messages to this topic from the specified source.
01964 */
01965 typedef void *(*lbm_rcv_src_notification_create_function_cb)(const char *source_name, void *clientd);
01966 
01967 /*! \brief Application callback for notification of deletion of sources for a topic
01968 
01969                 Set by lbm_rcv_topic_attr_setopt() with option "source_notification_function".
01970                 NOTE: this application callback is always made from the context thread and is therefore limited
01971                 in the UM API calls it can make.
01972         \sa lbm_rcv_src_notification_func_t
01973         \param source_name Name of the source
01974         \param clientd Client data pointer supplied in the lbm_rcv_src_notification_func_t passed to lbm_context_attr_setopt() with the "source_notification_function" attribute.
01975         \param source_clientd Client data pointer set to be included in each message.
01976         \return 0 always
01977 */
01978 typedef int (*lbm_rcv_src_notification_delete_function_cb)(const char *source_name, void *clientd, void *source_clientd);
01979 typedef struct lbm_str_hash_func_t_stct {
01980         /*! Function pointer for hash function */
01981     lbm_str_hash_function_cb hashfunc;
01982 } lbm_str_hash_func_t;
01983 
01984 /*! \brief Structure that holds the hash function callback information
01985 
01986    A structure used with options to set/get a specific hash function information.
01987 */
01988 typedef struct lbm_str_hash_func_ex_t_stct {
01989         /*! Function pointer for hash function */
01990     lbm_str_hash_function_cb_ex hashfunc;
01991         void* clientd;
01992 } lbm_str_hash_func_ex_t;
01993 
01994 /*! \brief Structure that holds the callback for source notifications
01995 
01996    A structure used with options to set/get a specific callback information
01997 */
01998 typedef struct lbm_src_notify_func_t_stct {
01999     lbm_src_notify_function_cb notifyfunc;
02000         void *clientd;
02001 } lbm_src_notify_func_t;
02002 
02003 /*! \brief Structure that holds the application callback pattern type information for
02004            wildcard receivers.
02005 
02006    A structure used with options to set/get a specific application callback pattern type.
02007 */
02008 typedef struct lbm_wildcard_rcv_compare_func_t_stct {
02009         lbm_wildcard_rcv_compare_function_cb compfunc;
02010         void *clientd;
02011 } lbm_wildcard_rcv_compare_func_t;
02012 
02013 /*! \brief Structure that holds the application callback for registration ID setting
02014 
02015    A structure used with options to set/get a specific callback function
02016 */
02017 typedef struct lbm_ume_rcv_regid_func_t_stct {
02018         lbm_ume_rcv_regid_function_cb func;
02019         void *clientd;
02020 } lbm_ume_rcv_regid_func_t;
02021 
02022 /*! \brief Structure that holds the application callback for registration ID setting, extended form
02023 
02024    A structure used with options to set/get a specific callback function
02025 */
02026 typedef struct lbm_ume_rcv_regid_ex_func_t_stct {
02027         lbm_ume_rcv_regid_ex_function_cb func;
02028         void *clientd;
02029 } lbm_ume_rcv_regid_ex_func_t;
02030 
02031 /*! \brief Structure that holds the application callback for forced reclamation notifications
02032 
02033    A structure used with options to set/get a specific callback function
02034 */
02035 typedef struct lbm_ume_src_force_reclaim_func_t_stct {
02036         lbm_ume_src_force_reclaim_function_cb func;
02037         void *clientd;
02038 } lbm_ume_src_force_reclaim_func_t;
02039 
02040 /*! \brief Structure that holds the application callback for multicast immediate message unrecoverable loss notification
02041 
02042    A structure used with options to set/get a specific callback function
02043 */
02044 typedef struct lbm_mim_unrecloss_func_t_stct {
02045         lbm_mim_unrecloss_function_cb func;
02046         void *clientd;
02047 } lbm_mim_unrecloss_func_t;
02048 
02049 /*! \brief Structure that holds the application callback for recovery sequence number information, extended form
02050 
02051   A struct used with options to set/get a specific callback function
02052 */
02053 typedef struct lbm_ume_rcv_recovery_info_ex_func_t_stct {
02054         lbm_ume_rcv_recovery_info_ex_function_cb func;
02055         void *clientd;
02056 } lbm_ume_rcv_recovery_info_ex_func_t;
02057 
02058 /*! \brief Structure that holds information for a UMP store for configuration purposes
02059 
02060    A structure used with options to get/set information for a UMP store
02061 */
02062 typedef struct lbm_ume_store_entry_t_stct {
02063         /*! The IP address of the UMP store (network order) */
02064         lbm_uint_t ip_address;
02065         /*! The TCP port of the store (network order) */
02066         lbm_ushort_t tcp_port;
02067         /*! The index of the group this UMP store belongs to */
02068         lbm_ushort_t group_index;
02069         /*! The registration ID that should be used with this UMP store for the source */
02070         lbm_uint_t registration_id;
02071         /*! The domain ID of the store */
02072         lbm_uint32_t domain_id;
02073 } lbm_ume_store_entry_t;
02074 
02075 /*! \brief Structure that holds information for a unicast resolver daemon for configuration purposes
02076 
02077     A structure used with options to get/set information about unicast resolver daemons.
02078 */
02079 typedef struct lbm_ucast_resolver_entry_t_stct {
02080         /*! Interface to be used */
02081         lbm_ipv4_address_mask_t iface;
02082         /*! The IP address of the unicast resolver daemon (network order) */
02083         lbm_uint_t resolver_ip;
02084         /*! The source port.  Use 0 to indicate that the port should come from the 
02085           [resolver_unicast_port_low, resolver_unicast_port_high] range. (network order)*/
02086         lbm_ushort_t source_port;
02087         /*! The port configured on the unicast resolver daemon. (network order) */
02088         lbm_ushort_t destination_port;
02089 } lbm_ucast_resolver_entry_t;
02090 
02091 /*! \brief Structure that holds information for a UMP store by name for configuration purposes
02092 
02093    A structure used with options to get/set information for a UMP store
02094 */
02095 typedef struct lbm_ume_store_name_entry_t_stct {
02096         /*! The store context name  Restricted to alphanumeric characters, hyphens, and underscores */
02097         char name[LBM_MAX_CONTEXT_NAME_LEN+1];
02098         /*! The index of the group this UMP store belongs to */
02099         lbm_ushort_t group_index;
02100         /*! The registration ID that should be used with this UMP store for the source */
02101         lbm_uint_t registration_id;
02102 } lbm_ume_store_name_entry_t;
02103 
02104 /*! \brief Structure that holds information for a UMP store group for configuration purposes
02105 
02106    A structure used with options to get/set information for a UMP store group
02107 */
02108 typedef struct lbm_ume_store_group_entry_t_stct {
02109         /*! Index of the group. Used in the individual store entries to indicate the store is in this group */
02110         lbm_ushort_t index;
02111         /*! The size of the group */
02112         lbm_ushort_t group_size;
02113 } lbm_ume_store_group_entry_t;
02114 
02115 /*! \brief Structure that holds the application callback for source status notifications for receivers
02116 
02117    A structure used with options to set/get a specific callback function
02118 */
02119 typedef struct lbm_rcv_src_notification_func_t_stct {
02120         lbm_rcv_src_notification_create_function_cb create_func;
02121         lbm_rcv_src_notification_delete_function_cb delete_func;
02122         void *clientd;
02123 } lbm_rcv_src_notification_func_t;
02124 
02125 /*! \brief Structure that holds the information about a receiving context.
02126  *
02127  * A structure used to hold a receiving context's user rcv regid and session
02128  * id. Source contexts use this information to track receiver liveness.
02129  */
02130 typedef struct ume_liveness_receiving_context_t_stct {
02131         lbm_uint64_t regid;
02132         lbm_uint64_t session_id;
02133         int flag;
02134 } ume_liveness_receiving_context_t;
02135 
02136 /*! \brief Application callback for notification of detection of a receiving application.
02137 
02138                 Set by lbm_context_attr_setopt() with option "lbm_context_attr_ume_receiver_liveness_notify_func".
02139                 NOTE: this application callback is always made from the context thread and is therefore limited
02140                 in the UM API calls it can make.
02141         \sa lbm_ume_rcv_ctx_notification_func_t
02142         \param const struct ume_liveness_receiving_context_t
02143         \param clientd Client data pointer supplied in the lbm_ume_rcv_ctx_notification_func_t passed to lbm_context_attr_setopt() with the "ume_receiver_context_detection_function" attribute.
02144         \return void pointer to be set for the "unresponsive" event when this ume_liveness_receiving_context_t is declared unresponsive.
02145 */
02146 typedef void *(*lbm_ume_ctx_rcv_ctx_notification_create_function_cb)(const ume_liveness_receiving_context_t *rcv, void *clientd);
02147 
02148 /*! \brief Application callback for notification of unresponsiveness of a receiving application.
02149 
02150                  Set by lbm_context_attr_setopt() with option "lbm_context_attr_ume_receiver_liveness_notify_func".
02151                  NOTE: this application callback is always made from the context thread and is therefore limited
02152                  in the UM API calls it can make.
02153          \sa lbm_ume_ctx_rcv_ctx_notification_func_t
02154          \param const struct lbm_ume_liveness_rcv_context_t
02155          \param clientd Client data pointer supplied in the lbm_ume_ctx_rcv_ctx_notification_func_t passed to lbm_context_attr_setopt() with the "ume_receiver_context_deletion_function" attribute.
02156          \return 0 if success -1 if failure.
02157  */
02158 typedef int (*lbm_ume_ctx_rcv_ctx_notification_delete_function_cb)(const ume_liveness_receiving_context_t *rcv, void *clientd, void *source_clientd);
02159 
02160 /*! \brief Structure that holds the application callback for receiving context status notifications for source context.
02161 
02162          A Structure used with options to set/get a specific callback function
02163  */
02164 typedef struct lbm_ume_ctx_rcv_ctx_notification_func_t_stct {
02165         lbm_ume_ctx_rcv_ctx_notification_create_function_cb create_func;
02166         lbm_ume_ctx_rcv_ctx_notification_delete_function_cb delete_func;
02167         void *clientd;
02168 } lbm_ume_ctx_rcv_ctx_notification_func_t;
02169 
02170 /*! \brief Structure that holds information for a UMQ queue registration ID for configuration purposes
02171 
02172         A struct used with options to get/set Registration ID information for UMQ queues
02173 */
02174 typedef struct lbm_umq_queue_entry_t_stct {
02175         /*! Name of the UMQ queue */
02176         char name[LBM_UMQ_MAX_QUEUE_STRLEN];
02177         /*! Registration ID to use with the given UMQ queue */
02178         lbm_umq_regid_t regid;
02179 } lbm_umq_queue_entry_t;
02180 
02181 /*! \brief Structure that holds information for a UMQ ULB sources receiver type associations with application sets
02182 
02183   A struct used with options to get/set UMQ ULB Receiver Type entries
02184 */
02185 typedef struct lbm_umq_ulb_receiver_type_entry_t_stct {
02186         /*! Receiver Type ID */
02187         lbm_ulong_t id;
02188         /*! Index of the Application Set the receiver is in */
02189         lbm_ushort_t application_set_index;
02190 } lbm_umq_ulb_receiver_type_entry_t;
02191 
02192 /*! \brief Structure that holds information for a UMQ ULB sources application set attributes
02193 
02194   A struct used with options to get/set UMQ ULB application set attributes
02195 */
02196 typedef struct lbm_umq_ulb_application_set_attr_t_stct {
02197         /*! Index of the Application Set */
02198         lbm_ushort_t index;
02199         /*! The value of the attribute */
02200         union {
02201                 /*! The integer value of the attribute */
02202                 int d;
02203                 /*! The unsigned long int value of the attribute */
02204                 lbm_ulong_t lu;
02205         } value;
02206 } lbm_umq_ulb_application_set_attr_t;
02207 
02208 /*! \brief Structure that holds information for a UMQ ULB sources receiver type attributes
02209 
02210   A struct used with options to get/set UMQ ULB receiver type attributes
02211 */
02212 typedef struct lbm_umq_ulb_receiver_type_attr_t_stct {
02213         /*! Receiver Type ID */
02214         lbm_ulong_t id;
02215         /*! The value of the attribute */
02216         union {
02217                 /*! The integer value of the attribute */
02218                 int d;
02219                 /*! The unsigned long int value of the attribute */
02220                 lbm_ulong_t lu;
02221         } value;
02222 } lbm_umq_ulb_receiver_type_attr_t;
02223         
02224 
02225 /*! \brief Application context-level callback for events associated with context sources
02226  * (immediate mode sources and responses).
02227 
02228                    Set by the "source_event_function" context attribute.
02229            If this application callback is set without an event queue, it is
02230            called from the context thread and is limited in the API calls that
02231            it can make.
02232   \param ctx Context object generating the event.
02233   \param ed Pointer to event data, content dependent on event type.
02234          \arg For \a event == LBM_SRC_EVENT_WAKEUP,
02235               \a ed should be re-cast as a (lbm_src_event_wakeup_t) and indicates which context-level
02236               source (or sources) has become un-blocked.
02237          \arg For \a event == LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION,
02238               \a ed should be re-cast as a (lbm_src_event_flight_size_notification_t *)
02239               to extract the flight size information.
02240   \param clientd Client data pointer supplied when setting "source_event_function" context attribute.
02241   \return 0 always
02242 */
02243 typedef int (*lbm_context_src_cb_proc)(lbm_context_t *ctx, int event, void *ed, void *clientd);
02244 
02245 /*! \brief Structure that holds the application callback for context-level source events
02246 
02247   A struct used to set a context-level source event callback and callback info.
02248 */
02249 typedef struct lbm_context_src_event_func_t_stct {
02250         lbm_context_src_cb_proc func;
02251         lbm_event_queue_t *evq;
02252         void *clientd;
02253 } lbm_context_src_event_func_t;
02254 
02255 /*! \brief Application context-level callback for events associated with contexts.
02256 
02257   Set by the "context_event_function" context attribute.
02258   If this application callback is set without an event queue, it is
02259   called from the context thread and is limited in the API calls that
02260   it can make.
02261   \param ctx Context object generating the event.
02262   \param event Type of event.
02263   \param ed Pointer to event data, content dependent on event type.
02264   \param clientd Client data pointer supplied when setting "context_event_function" context attribute.
02265   \return 0 always
02266 */        
02267 typedef int (*lbm_context_event_cb_proc)(lbm_context_t *ctx, int event, void *ed, void *clientd);
02268 
02269 /*! \brief Structure that holds the application callback for context-level events
02270 
02271   A struct used to set a context-level event callback and callback info.
02272 */
02273 typedef struct lbm_context_event_func_t_stct {
02274         lbm_context_event_cb_proc func;
02275         lbm_event_queue_t *evq;
02276         void *clientd;
02277 } lbm_context_event_func_t;
02278 
02279 /*! \brief Structure that holds a serialized UM response object
02280 */
02281 typedef struct lbm_serialized_response_t_stct {
02282         char serial_response[32];
02283 } lbm_serialized_response_t;
02284 
02285 struct lbm_buff_t_stct;
02286 typedef struct lbm_buff_t_stct lbm_buff_t;
02287 
02288 /*! \brief Opaque structure that designates a UM wildcard receiver object
02289 */
02290 struct lbm_wildcard_rcv_t_stct;
02291 typedef struct lbm_wildcard_rcv_t_stct lbm_wildcard_rcv_t;
02292 
02293 /*! \brief Opaque structure that designates a UM Hot Failover receiver object
02294 */
02295 struct lbm_hf_rcv_t_stct;
02296 typedef struct lbm_hf_rcv_t_stct lbm_hf_rcv_t;
02297 
02298 /*! \brief Opaque structure that designates HFX attributes*/
02299 struct lbm_hfx_attr_t_stct;
02300 typedef struct lbm_hfx_attr_t_stct lbm_hfx_attr_t;
02301 
02302 /*! \brief Opaque structure that designates an HFX object (for hot failover receivers across multiple contexts)  */
02303 struct lbm_hfx_t_stct;
02304 typedef struct lbm_hfx_t_stct lbm_hfx_t;
02305 
02306 /*! \brief Opaque structure that designates an HFX receiver*/
02307 struct lbm_hfx_rcv_t_stct;
02308 typedef struct lbm_hfx_rcv_t_stct lbm_hfx_rcv_t;
02309 
02310 /*! \brief Opaque structure that designates a Topic
02311 */
02312 struct lbm_topic_t_stct;
02313 typedef struct lbm_topic_t_stct lbm_topic_t;
02314 
02315 /*! \brief Opaque structure that designates a UM source
02316 */
02317 struct lbm_src_t_stct;
02318 typedef struct lbm_src_t_stct lbm_src_t;
02319 
02320 /*! \brief Opaque structure that designates a UM receiver
02321 */
02322 struct lbm_rcv_t_stct;
02323 typedef struct lbm_rcv_t_stct lbm_rcv_t;
02324 
02325 /*! \brief Opaque structure that designates a UM request object
02326 */
02327 struct lbm_request_t_stct;
02328 typedef struct lbm_request_t_stct lbm_request_t;
02329 
02330 /*! \brief Opaque structure that designates a UM response object
02331 */
02332 struct lbm_response_t_stct;
02333 typedef struct lbm_response_t_stct lbm_response_t;
02334 
02335 /*! \brief Structure that holds fragment information for UM messages when appropriate
02336 
02337         To retrieve the UM-message fragment information held in this structure,
02338         it is typically necessary to call lbm_msg_retrieve_fragment_info().
02339 */
02340 typedef struct lbm_msg_fragment_info_t_stct {
02341         /*! The sequence number of the fragment that starts the message
02342         */
02343         lbm_uint_t start_sequence_number;
02344         /*! The offset (in bytes) of this fragment from the message beginning
02345         */
02346         lbm_uint_t offset;
02347         /*! The total length (in bytes) of the message this fragment is for
02348         */
02349         lbm_uint_t total_message_length;
02350 } lbm_msg_fragment_info_t;
02351 
02352 /*! \brief Structure that holds originating information for UM messages which
02353         arrived via a gateway.
02354 
02355         \deprecated
02356 */
02357 typedef struct lbm_msg_gateway_info_t_stct {
02358         /*! The original sequence number (relative to the original transport.)
02359         */
02360         lbm_uint_t sequence_number;
02361         /*! The original source string.
02362         */
02363         char source[LBM_MSG_MAX_SOURCE_LEN];
02364 } lbm_msg_gateway_info_t;
02365 
02366 /*! \brief Structure that represents UMS Spectrum channel information
02367 
02368         This channel information assigns a channel designator to individual messages. Receivers
02369         may use this channel designator to filter messages or direct them to specific callbacks
02370         on a per-channel basis.
02371 */
02372 typedef struct lbm_msg_channel_info_t_stct {
02373         /*! Channel flags 
02374          \arg \c LBM_MSG_FLAG_NUMBERED_CHANNEL Message was delivered on a numbered channel.
02375          */
02376         int flags;  
02377         /*! Channel number in the range 0-4294967295 */
02378         lbm_uint32_t channel_number;
02379 } lbm_msg_channel_info_t;
02380 
02381 /*! \brief Opaque structure that designates a UMP ack object
02382 */
02383 struct lbm_ume_rcv_ack_t_stct;
02384 typedef struct lbm_ume_rcv_ack_t_stct lbm_ume_rcv_ack_t;
02385 
02386 /*! \brief Structure that stores information about a received message
02387 */
02388 struct lbm_msg_t_stct {
02389         /*! Source string of transport session.  Format depends on transport type.
02390         For string formats and examples, see lbm_transport_source_info_t_stct.
02391         */
02392         char source[LBM_MSG_MAX_SOURCE_LEN];
02393         /*! Name of the topic. Although this field is allocated at 256 bytes, legal topic names
02394           are restricted to 246 bytes. */
02395         char topic_name[LBM_MSG_MAX_TOPIC_LEN];
02396         /*! Copy of the state of the msg (only used on specific platforms. DO NOT ACCESS DIRECTLY!) */
02397         char copied_state[LBM_MSG_MAX_STATE_LEN];
02398         /*! Type of message.
02399           \arg \c LBM_MSG_DATA - Data message, Message is composed of user data
02400           \arg \c LBM_MSG_BOS - Beginning of Transport Session (source connection established) (data received)
02401           \arg \c LBM_MSG_EOS - End of Transport Session (connection closed to source) (no further data)
02402           \arg \c LBM_MSG_REQUEST - Request message from source
02403           \arg \c LBM_MSG_RESPONSE - Response message from requestee
02404           \arg \c LBM_MSG_UNRECOVERABLE_LOSS - Missing message detected and not recovered in given time (no data)
02405           \arg \c LBM_MSG_UNRECOVERABLE_LOSS_BURST - Missing burst of messages detected and not recovered (no data)
02406           \arg \c LBM_MSG_NO_SOURCE_NOTIFICATION - No source has been found for topic, Still querying for topic source
02407           \arg \c LBM_MSG_UME_REGISTRATION_ERROR - UMP receiver registration encountered an error. Data holds error message
02408           \arg \c LBM_MSG_UME_REGISTRATION_SUCCESS - UMP receiver registration successful. Data holds registration IDs
02409           \arg \c LBM_MSG_UME_REGISTRATION_CHANGE - UMP receiver notification of source registration change. Data holds info message
02410           \arg \c LBM_MSG_UME_REGISTRATION_SUCCESS_EX - UMP receiver registration successful for a store (extended form). Data holds registration IDs, etc.
02411           \arg \c LBM_MSG_UME_REGISTRATION_CHANGE_EX - UMP receiver notification of registration completion. Data holds sequence number and flags, etc.
02412           \arg \c LBM_MSG_UME_DEREGISTRATION_SUCCESS_EX - UMP receiver notification of deregistration success. Data holds registration IDs, etc.
02413           \arg \c LBM_MSG_UME_DEREGISTRATION_COMPLETE_EX - UMP receiver notification of deregistration complete.
02414           \arg \c LBM_MSG_UMQ_REGISTRATION_ERROR - UMQ receiver registration encountered an error. Data holds error message.
02415           \arg \c LBM_MSG_UMQ_REGISTRATION_COMPLETE_EX - UMQ receiver notification of registration completion. Data holds Queue information, assignment ID, etc.
02416           \arg \c LBM_MSG_UMQ_DEREGISTRATION_COMPLETE_EX - UMQ receiver notification of de-registration completion. Data holds Queue information, etc. 
02417           \arg \c LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_ERROR - UMQ receiver index assignment start/stop encountered an error.  Data holds error message. 
02418           \arg \c LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_START_COMPLETE_EX - UMQ receiver notification of beginning of index assignment eligibility or index assignment. Data holds index information, etc.
02419           \arg \c LBM_MSG_UMQ_INDEX_ASSIGNMENT_ELIGIBILITY_STOP_COMPLETE_EX - UMQ receiver notification of end of index assignment eligibility or index assignment. Data holds index information, etc. 
02420           \arg \c LBM_MSG_UMQ_INDEX_ASSIGNED_EX - UMQ receiver notification of beginning of index.
02421           \arg \c LBM_MSG_UMQ_INDEX_RELEASED_EX - UMQ receiver notification of end of index.
02422           \arg \c LBM_MSG_UMQ_INDEX_ASSIGNMENT_ERROR - UMQ receiver notification of an index assignment error.
02423           \arg \c LBM_MSG_HF_RESET - Hot-failover reset message was handled. UMS is now expecting msg->hf_sequence_number as the next non-reset hot-failover message.
02424         */
02425         int type;
02426         /*! Flags associated with the message.
02427           \arg \c LBM_MSG_FLAG_START_BATCH - Message starts a batch
02428           \arg \c LBM_MSG_FLAG_END_BATCH - Message ends a batch
02429           \arg \c LBM_MSG_FLAG_HF_PASS_THROUGH - Message is a passed-through Hot Failover message
02430           \arg \c LBM_MSG_FLAG_RETRANSMIT - Message is a late join recovered message
02431           \arg \c LBM_MSG_FLAG_UME_RETRANSMIT - Message is a UM recovered message
02432           \arg \c LBM_MSG_FLAG_IMMEDIATE - Message is an immediate message
02433           \arg \c LBM_MSG_FLAG_TOPICLESS - Message has no topic
02434           \arg \c LBM_MSG_FLAG_HF_32 - Message has a 32 bit hot failover sequence number
02435           \arg \c LBM_MSG_FLAG_HF_64 - Message has a 64 bit hot failover sequence number
02436          */
02437         int flags;
02438         /*! Data contents of the message if of a message type that carries data.
02439         Note that UM does not guarantee any alignment of that data.
02440          */
02441         const char *data;
02442         /*! Length of data in bytes
02443          */
02444         size_t len;
02445         /*! Pointer to response object used for sending responses for lbm_msg_t request.
02446          */
02447         lbm_response_t *response;
02448         /*! Topic level sequence number of message. For fragmented messages, this
02449          *  is the sequence number of the final fragment comprising the message.
02450          */
02451         lbm_uint_t sequence_number;
02452         /* UM internal only */
02453 #if defined(_WIN32)
02454         LONG refcnt;
02455 #else
02456         long refcnt;
02457 #endif /* _WIN32 */
02458         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02459         size_t apphdr_len;
02460         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02461         lbm_ulong_t apphdr_code;
02462         /* Timestamp indicating the earliest time that the message was received,
02463                 in seconds and microseconds since midnight, January 1st, 1970 UTC.
02464                 This time can be up to 500 milliseconds prior to actual receipt time,
02465                 and hence, is not suitable when accurate message-arrival-time
02466                 measurements are needed.
02467          */
02468         lbm_timeval_t tsp;
02469         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02470         lbm_ushort_t hdrlen;
02471         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02472         const lbm_buff_t *buffer;
02473         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02474         const void *fragment_info;
02475         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02476         const char *apphdr_data;
02477         /*! Pointer set by lbm_rcv_src_notification_create_function_cb callback */
02478         const void *source_clientd;
02479         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02480         const void *umeack;
02481         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02482         const void *src_cd;
02483         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02484         lbm_uint_t osqn;
02485         /*! Channel information set when using Spectrum channels */
02486         lbm_msg_channel_info_t *channel_info;
02487         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02488         const void *umq_msgid;
02489         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02490         const void *umq_cr;
02491         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02492         const void *pdata;
02493         /* UM internal only. DO NOT ACCESS DIRECTLY! */
02494         size_t plen;
02495         /*! Message properties structure for this message */
02496         lbm_msg_properties_t *properties;
02497         /*! Hot failover sequence number, check message flags for LBM_MSG_FLAG_HF_32 or LBM_MSG_FLAG_HF_64. */
02498         lbm_hf_sequence_number_t hf_sequence_number;
02499 };
02500 
02501 /*! \brief Application callback for non-topic immediate-mode received messages.
02502 
02503            Set by lbm_context_rcv_immediate_msgs().
02504            If this application callback is set without an event queue, it is
02505            called from the context thread and is limited in the API calls that
02506            it can make.
02507 
02508   \note For received application messages, be aware that UM does not
02509         guarantee any alignment of that data.
02510   \param ctx Context receiving the message.
02511   \param msg Pointer to received message.
02512   \param clientd Client data pointer supplied in lbm_context_rcv_immediate_msgs().
02513   \return 0 always.
02514 */
02515 typedef int (*lbm_immediate_msg_cb_proc)(lbm_context_t *ctx, lbm_msg_t *msg, void *clientd);
02516 
02517 /*! \brief Structure that holds the application callback for receiving topic-less immediate mode messages
02518 
02519   A struct used to set the context-level topic-less immediate mode message receiver callback.  If an
02520   event queue is specified, messages will be placed on the event queue; if evq is NULL, messages will
02521   be delivered directly from the context thread.
02522 */
02523 typedef struct lbm_context_rcv_immediate_msgs_func_t_stct {
02524         lbm_immediate_msg_cb_proc func;
02525         lbm_event_queue_t *evq;
02526         void *clientd;
02527 } lbm_context_rcv_immediate_msgs_func_t;
02528 
02529 /*! \brief Structure that holds formatted and parsed transport source strings
02530         
02531         This structure holds the fields used to format and/or parse transport source strings. The
02532         format of these strings depends mainly on the transport type, as shown below.
02533 
02534         \li TCP:src_ip:src_port:session_id[topic_idx] (session_id optional, per configuration
02535         option transport_tcp_use_session_id)
02536         \n example: <tt>TCP:192.168.0.4:45789:f1789bcc[1539853954]</tt>
02537 
02538         \li LBTRM:src_ip:src_port:session_id:mc_group:dest_port[topic_idx]
02539         \n example: <tt>LBTRM:10.29.3.88:14390:e0679abb:231.13.13.13:14400[1539853954]</tt>
02540 
02541         \li LBT-RU:src_ip:src_port:session_id[topic_idx] (session_id optional, per configuration
02542         option transport_lbtru_use_session_id)
02543         \n example: <tt>LBT-RU:192.168.3.189:34678[1539853954]</tt>
02544 
02545         \li LBT-IPC:session_id:transport_id[topic_idx]
02546         \n example: <tt>LBT-IPC:6481f8d4:20000[1539853954]</tt>
02547 
02548         \li LBT-RDMA:src_ip:src_port:session_id[topic_idx]
02549         \n example: <tt>LBT-RDMA:192.168.3.189:34678:6471e9c4[1539853954]</tt>
02550 
02551         Please note that the topic index field (topic_idx) may or may not be present depending on
02552         your version of UM and/or the setting for configuration option source_includes_topic_index.
02553         \sa lbm_transport_source_format lbm_transport_source_parse 
02554 */
02555 
02556 typedef struct lbm_transport_source_info_t_stct {
02557         /*! Type of transport. See LBM_TRANSPORT_TYPE_*. */
02558         int type;
02559         /*! Source IP address. Applicable only to LBT-RM, LBT-RU, TCP, and LBT-RDMA. Stored in network order. */
02560         lbm_uint32_t src_ip;
02561         /*! Source port. Applicable only to LBT-RM, LBT-RU, TCP, and LBT-RDMA. Stored in host order. */
02562         lbm_ushort_t src_port;
02563         /*! Destination port. Applicable only to LBT-RM. Stored in host order. */
02564         lbm_ushort_t dest_port;
02565         /*! Multicast group. Applicable only to LBT-RM. Stored in network order. */
02566         lbm_uint32_t mc_group;
02567         /*! Transport ID. Applicable only to LBT-IPC. Stored in host order. */
02568         lbm_uint32_t transport_id;
02569         /*! Session ID. Applicable to all transport. Stored in host order. */
02570         lbm_uint32_t session_id;
02571         /*! Topic index. Applicable to all transports. Stored in host order. */
02572         lbm_uint32_t topic_idx;
02573         /*! Transport index. Applicable to all transports. Stored in host order. */
02574         lbm_uint32_t transport_idx;
02575 #ifndef LBM_INTERNAL_USE_ONLY
02576         char _fill[LBM_EXTERNAL_STRUCT_FILL_SIZE];
02577 #endif
02578 } lbm_transport_source_info_t;
02579 
02580 /*! Source cost function return value to indicate this source should be permanently rejected. */
02581 #define LBM_SRC_COST_FUNCTION_REJECT 0xffffffff
02582 
02583 /*!     \brief Application callback to evaluate the cost of a newly discovered source.
02584 
02585                 Set via the "source_cost_evaluation_function" context attribute.
02586         \param topic Topic for which the new source was discovered.
02587         \param transport Pointer to a ::lbm_transport_source_info_t, describing the transport session.
02588         \param hop_count Current hop count for the transport session.
02589         \param cost Current cumulative cost for the transport session.
02590         \param clientd Client data pointer supplied when setting "source_cost_evaluation_function" context attribute.
02591         \return Application-determined cost for this source as an unsigned 32-bit number.
02592                 To permanently reject this source, return ::LBM_SRC_COST_FUNCTION_REJECT.
02593 */
02594 typedef lbm_uint32_t (*lbm_src_cost_function_cb)(const char *topic, const lbm_transport_source_info_t *transport, lbm_uint32_t hop_count, lbm_uint32_t cost, void *clientd);
02595 
02596 /*!     \brief Structure that holds the "source_cost_evaluation_function" context attribute
02597 */
02598 typedef struct lbm_src_cost_func_t_stct
02599 {
02600         lbm_src_cost_function_cb cost_cb;
02601         void *clientd;
02602 } lbm_src_cost_func_t;
02603 
02604 /*! \brief Structure used to hold attributes for contexts.
02605 
02606     Do not access this structure directly, use setopt() and getopt() functions. 
02607 */
02608 struct lbm_context_attr_t_stct;
02609 typedef struct lbm_context_attr_t_stct lbm_context_attr_t;
02610 
02611 /*! \brief Config option structure holding the option name and value via string types. */
02612 #define LBM_CONFIG_OPTIONS_STR_LEN 128
02613 typedef struct lbm_config_option_stct_t
02614 {
02615         char type[LBM_CONFIG_OPTIONS_STR_LEN];
02616         char oname[LBM_CONFIG_OPTIONS_STR_LEN];
02617         char val[LBM_CONFIG_OPTIONS_STR_LEN];
02618 } lbm_config_option_t;
02619 
02620 /*! \brief Opaque structure that holds attributes for source topics
02621 */
02622 struct lbm_src_topic_attr_t_stct;
02623 typedef struct lbm_src_topic_attr_t_stct lbm_src_topic_attr_t;
02624 
02625 /*! \brief Opaque structure that holds attributes for receiver topics
02626 */
02627 struct lbm_rcv_topic_attr_t_stct;
02628 typedef struct lbm_rcv_topic_attr_t_stct lbm_rcv_topic_attr_t;
02629 
02630 /*!     \brief Application callback for wildcard receiver creation.
02631 
02632                         Set by lbm_wildcard_rcv_attr_setopt() with option
02633                         "receiver_create_callback".
02634                         NOTE: this application callback is always made from the context
02635                         thread, and is therefore limited in the UM API calls it can make.
02636         \sa lbm_wildcard_rcv_create_func_t
02637         \param topic_str Name of topic which was matched, and for which a receiver will be created.
02638         \param attr Pointer to an lbm_rcv_topic_attr_t which has been initialized with the receiver
02639                 options which will be used to create the receiver.
02640         \param clientd Client data pointer supplied in the lbm_wildcard_rcv_create_func_t passed
02641                 to lbm_wildcard_rcv_attr_setopt() with the "receiver_create_callback" attribute.
02642         \return Always return 0.
02643 */
02644 typedef int (*lbm_wildcard_rcv_create_function_cb)(const char * topic_str, lbm_rcv_topic_attr_t * attr, void * clientd);
02645 
02646 /*!     \brief Structure that holds the receiver creation callback information for
02647                         wildcard receivers.
02648 
02649         A structure used with options to set/get a specific wildcard topic receiver creation callback type.
02650  */
02651 typedef struct lbm_wildcard_rcv_create_func_t_stct {
02652         lbm_wildcard_rcv_create_function_cb createfunc;
02653         void *clientd;
02654 } lbm_wildcard_rcv_create_func_t;
02655 
02656 /*!     \brief Application callback for wildcard receiver deletion.
02657 
02658                         Set by lbm_wildcard_rcv_attr_setopt() with option
02659                         "receiver_delete_callback".
02660                         NOTE: this application callback is always made from the context
02661                         thread, and is therefore limited in the UM API calls it can make.
02662         \sa lbm_wildcard_rcv_delete_func_t
02663         \param topic_str Name of topic which was matched, and for which a receiver will be deleted.
02664         \param clientd Client data pointer supplied in the lbm_wildcard_rcv_delete_func_t passed
02665                 to lbm_wildcard_rcv_attr_setopt() with the "receiver_delete_callback" attribute.
02666         \return Always return 0.
02667 */
02668 typedef int (*lbm_wildcard_rcv_delete_function_cb)(const char * topic_str, void * clientd);
02669 
02670 /*!     \brief Structure that holds the receiver deletion callback information for
02671                         wildcard receivers.
02672 
02673         A structure used with options to set/get a specific wildcard topic receiver deletion callback type.
02674  */
02675 typedef struct lbm_wildcard_rcv_delete_func_t_stct {
02676         lbm_wildcard_rcv_delete_function_cb deletefunc;
02677         void *clientd;
02678 } lbm_wildcard_rcv_delete_func_t;
02679 
02680 /*! \brief Opaque structure that holds attributes for wildcard receivers
02681 */
02682 struct lbm_wildcard_rcv_attr_t_stct;
02683 typedef struct lbm_wildcard_rcv_attr_t_stct lbm_wildcard_rcv_attr_t;
02684 
02685 /*! \brief Structure that holds datagram statistics for source TCP transports */
02686 typedef struct lbm_src_transport_stats_tcp_t_stct {
02687         /*! Number of TCP receiver clients currently connected over this transport. */
02688         lbm_ulong_t num_clients;
02689         /*! Number of bytes currently in UM's TCP buffer, i.e., a snapshot. This count is
02690         affected by the number of receivers,and configuration options
02691         transport_tcp_multiple_receiver_behavior and transport_session_maximum_buffer.  */
02692         lbm_ulong_t bytes_buffered;
02693 } lbm_src_transport_stats_tcp_t;
02694 
02695 /*! \brief Structure that holds datagram statistics for source LBT-RM transports */
02696 typedef struct lbm_src_transport_stats_lbtrm_t_stct {
02697         /*! Number of LBT-RM datagrams sent. Depending on batching settings, a single
02698                 LBT-RM datagram may contain one or more messages, or a fragment of a larger
02699                 message. With LBT-RM, larger messages are split into fragment sizes limited by
02700                 configuration option transport_lbtrm_datagram_max_size (default 8KB). */
02701         lbm_ulong_t msgs_sent;
02702         /*! Number of LBT-RM datagram bytes sent, i.e., the total of lengths of
02703                 all LBT-RM packets including UM header information. */
02704         lbm_ulong_t bytes_sent;
02705         /*! Number of LBT-RM datagrams currently in the transmission window. Each
02706                 source transport session maintains a transmission window buffer (the size
02707                 of which is set by transport_lbtrm_transmission_window_size, default 24MB). When
02708                 the source transport receives a NAK, the corresponding message for
02709                 retransmission must be found in this transmission window. */
02710         lbm_ulong_t txw_msgs;
02711         /*! Number of bytes currently in the transmission window. See txw_msgs (above) for a
02712                 description of the transmission window. Typically, this count approaches its
02713                 window size or exceeds it by a small amount.  */
02714         lbm_ulong_t txw_bytes;
02715         /*! Number of NAK packets received by this source transport. UM batches NAKs into NAK
02716                 packets to save network bandwidth. This should always be less than or equal to
02717                 naks_rcved (below). */
02718         lbm_ulong_t nak_pckts_rcved;
02719         /*! Number of individual NAKs received by the source transport. When a source transport
02720                 receives a NAK from a receiver transport, it may respond by re-transmitting the
02721                 requested LBT-RM datagram, or it may send an NCF. The NAKing receiver transport
02722                 responds to the NCF by waiting (timeout set by
02723                 transport_lbtrm_nak_suppress_interval, default 1000 ms), then re-sending the
02724                 NAK. */
02725         lbm_ulong_t naks_rcved;
02726         /*! Number of NAKs this source transport ignored and sent an NCF with reason code "ignored".
02727                 A source transport ignores a NAK for a datagram it has already recently
02728                 retransmitted. How "recently" is determined by the configuration option source
02729                 transport_lbtrm_ignore_interval (default 500ms). If this count is high, a
02730                 receiver transport may be having trouble receiving retransmissions, or the
02731                 ignore interval may be set too long. */
02732         lbm_ulong_t naks_ignored;
02733         /*! Number of NAKs this source transport has shed by sending an NCF with reason code "shed".
02734                 When a source transport's retransmit rate limiter and retransmit queue are both
02735                 at maximum, it responds to a NAK by sending an "NCF shed", and does not
02736                 retransmit. The receiver transport should wait, then send another NAK. If this
02737                 count is high, one or more crybaby receiver transports may be clogging the
02738                 source transport's retransmit queue. */
02739         lbm_ulong_t naks_shed;
02740         /*! Number of NAKs this source transport has not yet processed because doing so would
02741                 exceed its retransmit rate limit (set by configuration option
02742                 transport_lbtrm_retransmit_rate_limit, default 5Mbps). For each of these NAKs,
02743                 the source transport immediately sends an NFC rx_delay, then queues the
02744                 retransmission for a later send within the rate limit. If this count is high,
02745                 one or more crybaby receiver transports may be clogging the source transport's
02746                 retransmit queue. */
02747         lbm_ulong_t naks_rx_delay_ignored;
02748         /*! Number of LBT-RM datagrams retransmitted by this source transport (incremented under
02749                 the same circumstances as rx_bytes_sent, below). In a normal, light-loss
02750                 scenario, most NAKs induce a retransmission. When losses becomes heavy and/or
02751                 many receiver transports begin losing the same LBT-RM datagrams, NCF-related
02752                 no-retransmit counts (naks_ignored, naks_shed and naks_rx_delay_ignored) may
02753                 begin to inflate, and retransmissions (rxs_sent/rx_bytes_sent counts) may become
02754                 significantly lower than NAKS received (naks_rcved). */
02755         lbm_ulong_t rxs_sent;
02756         /*! Number of LBT-RM datagrams currently queued by the data rate limiter. When a source
02757                 transport attempts to send messages (any type) faster than its data rate limiter
02758                 allows (set by configuration option transport_lbtrm_data_rate_limit, default
02759                 10Mbps), the data rate limiter queues the messages until they can be sent within
02760                 the data rate limit. */
02761         lbm_ulong_t rctlr_data_msgs;
02762         /*! Number of LBT-RM transport retransmission datagrams currently queued by the retransmit
02763                 rate limiter. When a source transport attempts to send retransmissions faster
02764                 that its retransmit rate limiter allows (set by configuration option
02765                 transport_lbtrm_retransmit_rate_limit, default 5Mbps), the retransmit rate limiter
02766                 queues retransmissions until they can be sent within the rate limit.
02767                 naks_rx_delay_ignored (above) will generally also rise if this count is high. */
02768         lbm_ulong_t rctlr_rx_msgs;
02769         /*! Number of LBT-RM transport total bytes retransmitted by this source transport
02770                 (triggered under the same circumstances as rxs_sent, above). In a normal,
02771                 light-loss scenario, most NAKs induce a retransmission. When losses becomes
02772                 heavy and/or many receiver transports begin losing the same LBT-RM datagrams,
02773                 NCF-related no-retransmit counts (naks_ignored, naks_shed and
02774                 naks_rx_delay_ignored) may begin to inflate, and retransmissions
02775                 (rxs_sent/rx_bytes_sent counts) may become significantly lower than NAKS
02776                 received (naks_rcved). */
02777         lbm_ulong_t rx_bytes_sent;
02778 } lbm_src_transport_stats_lbtrm_t;
02779 
02780 /*! \brief Structure that holds statistics for source daemon mode transport (deprecated)
02781 
02782         This structure holds statistics for source transports using the daemon mode. NOTE: daemon
02783         mode is deprecated and no longer available; this structure is retained for for backward
02784         compatibility only.
02785 */
02786 typedef struct lbm_src_transport_stats_daemon_t_stct {
02787         /*! This statistic has been deprecated. */
02788         lbm_ulong_t bytes_buffered;
02789 } lbm_src_transport_stats_daemon_t;
02790 
02791 /*! \brief Structure that holds datagram statistics for source LBT-RU transports */
02792 typedef struct lbm_src_transport_stats_lbtru_t_stct {
02793         /*! Number of LBT-RU datagrams sent. Depending on batching settings, a single LBT-RU
02794                 datagram may contain one or more messages, or a fragment of a larger message. With
02795                 LBT-RU, larger messages are split into fragment sizes limited by configuration
02796                 option transport_lbtru_datagram_max_size (default 8KB). */
02797         lbm_ulong_t msgs_sent;
02798         /*! Number of LBT-RU datagram bytes sent, i.e., the total of lengths of all LBT-RU packets
02799                 including UM header information. */
02800         lbm_ulong_t bytes_sent;
02801         /*! Number of NAK packets received by this source transport. UM batches NAKs into NAK
02802                 packets to save network bandwidth. This should always be less than or equal to
02803                 naks_rcved (below). */
02804         lbm_ulong_t nak_pckts_rcved;
02805         /*! Number of individual NAKs received by the source transport. When a source transport
02806                 receives a NAK from a receiver transport, it may respond by re-transmitting the
02807                 requested LBT-RU datagram, or it may send an NCF. The NAKing receiver transport
02808                 responds to the NCF by waiting (timeout set by
02809                 transport_lbtru_nak_suppress_interval, default 1000 ms), then re-sending the
02810                 NAK. */
02811         lbm_ulong_t naks_rcved;
02812         /*! Number of NAKs this source transport ignored and sent an NCF with reason code "ignored".
02813                 A source transport ignores a NAK for a datagram it has already recently
02814                 retransmitted. How "recently" is determined by the configuration option source
02815                 transport_lbtru_ignore_interval (default 500ms). If this count is high, a
02816                 receiver transport may be having trouble receiving retransmissions, or the
02817                 ignore interval may be set too long. */
02818         lbm_ulong_t naks_ignored;
02819         /*! Number of NAKs this source transport has shed by sending an NCF with reason code "shed".
02820                 When a source transport's retransmit rate limiter and retransmit queue are both
02821                 at maximum, it responds to a NAK by sending an "NCF shed", and does not
02822                 retransmit. The receiver transport should wait, then send another NAK. If this
02823                 count is high, one or more crybaby receiver transports may be clogging the
02824                 source transport's retransmit queue. */
02825         lbm_ulong_t naks_shed;
02826         /*! Number of NAKs this source transport has not yet processed because doing so would
02827                 exceed its retransmit rate limit (set by configuration option
02828                 transport_lbtru_retransmit_rate_limit, default 5Mbps). For each of these NAKs,
02829                 the source transport immediately sends an NFC rx_delay, then queues the
02830                 retransmission for a later send within the rate limit. If this count is high,
02831                 one or more crybaby receiver transports may be clogging the source transport's
02832                 retransmit queue. */
02833         lbm_ulong_t naks_rx_delay_ignored;
02834         /*! Number of LBT-RU datagrams retransmitted by this source transport (incremented under
02835                 the same circumstances as rx_bytes_sent, below). In a normal, light-loss
02836                 scenario, most NAKs induce a retransmission. When losses becomes heavy and/or
02837                 many receiver transports begin losing the same LBT-RU datagrams, NCF-related
02838                 no-retransmit counts (naks_ignored, naks_shed and naks_rx_delay_ignored) may
02839                 begin to inflate, and retransmissions (rxs_sent/rx_bytes_sent counts) may become
02840                 significantly lower than NAKS received (naks_rcved). */
02841         lbm_ulong_t rxs_sent;
02842         /*! Number of receiver transports that are currently connected to this source transport. */
02843         lbm_ulong_t num_clients;
02844         /*! Number of LBT-RU transport total bytes retransmitted by this source transport
02845                 (triggered under the same circumstances as rxs_sent, above). In a normal,
02846                 light-loss scenario, most NAKs induce a retransmission. When losses becomes
02847                 heavy and/or many receiver transports begin losing the same LBT-RU datagrams,
02848                 NCF-related no-retransmit counts (naks_ignored, naks_shed and
02849                 naks_rx_delay_ignored) may begin to inflate, and retransmissions
02850                 (rxs_sent/rx_bytes_sent counts) may become significantly lower than NAKS
02851                 received (naks_rcved). */
02852         lbm_ulong_t rx_bytes_sent;
02853 } lbm_src_transport_stats_lbtru_t;
02854 
02855 /*! \brief Structure that holds datagram statistics for source LBT-IPC transports */
02856 typedef struct lbm_src_transport_stats_lbtipc_t_stct {
02857         /*! Number of receiver transports that are currently connected to this source transport. */
02858         lbm_ulong_t num_clients;
02859         /*! Number of LBT-IPC datagrams sent. Depending on batching settings, a single LBT-IPC
02860                 datagram may contain one or more messages, or a fragment of a larger message. With
02861                 LBT-IPC, larger messages are split into fragment sizes limited by configuration
02862                 option transport_lbtipc_datagram_max_size (default 64KB). */
02863         lbm_ulong_t msgs_sent;
02864         /*! Number of LBT-IPC datagram bytes sent, i.e., the total of lengths of all LBT-IPC
02865                 packets including UM header information. */
02866         lbm_ulong_t bytes_sent;
02867 } lbm_src_transport_stats_lbtipc_t;
02868 
02869 /*! \brief Structure that holds datagram statistics for source LBT-SMX transports */
02870 typedef struct lbm_src_transport_stats_lbtsmx_t_stct {
02871         /*! Number of receiver transports that are currently connected to this source transport. */
02872         lbm_ulong_t num_clients;
02873         /*! Number of LBT-SMX datagrams sent. */
02874         lbm_ulong_t msgs_sent;
02875         /*! Number of LBT-SMX datagram bytes sent, i.e., the total of lengths of all LBT-SMX
02876                 packets including UM header information. */
02877         lbm_ulong_t bytes_sent;
02878 } lbm_src_transport_stats_lbtsmx_t;
02879 
02880 /*! \brief Structure that holds datagram statistics for source LBT-RDMA transports */
02881 typedef struct lbm_src_transport_stats_lbtrdma_t_stct {
02882         /*! Number of receiver transports that are currently connected to this source transport. */
02883         lbm_ulong_t num_clients;
02884         /*! Number of LBT-RDMA datagrams sent. Depending on batching settings, a single LBT-RDMA
02885                 datagram may contain one or more messages, or a fragment of a larger message. With
02886                 LBT-RDMA, larger messages are split into fragment sizes limited by configuration
02887                 option transport_lbtrdma_datagram_max_size (default 4KB). */
02888         lbm_ulong_t msgs_sent;
02889         /*! Number of LBT-RDMA datagram bytes sent, i.e., the total of lengths of all LBT-RDMA
02890                 packets including UM header information. */
02891         lbm_ulong_t bytes_sent;
02892 } lbm_src_transport_stats_lbtrdma_t;
02893 
02894 /*! \brief Structure that holds statistics for source transports
02895 
02896         This structure holds statistics for all source transports. The structure is filled in
02897                 when statistics for source transports are requested.
02898 */
02899 typedef struct lbm_src_transport_stats_t_stct {
02900         /*! Type of transport (LBM_TRANSPORT_STAT_TCP, LBM_TRANSPORT_STAT_LBTRM, etc.). */
02901         int type;
02902         /*! Source string of transport session, the format of which depends on the transport type.
02903                 For string formats and examples, see lbm_transport_source_info_t_stct. */
02904         char source[LBM_MSG_MAX_SOURCE_LEN];
02905         union {
02906                 /*! The statistics for source TCP transports. */
02907                 lbm_src_transport_stats_tcp_t tcp;
02908                 /*! The statistics for source LBT-RM transports. */
02909                 lbm_src_transport_stats_lbtrm_t lbtrm;
02910                 /*! These statistics have been deprecated. */
02911                 lbm_src_transport_stats_daemon_t daemon;
02912                 /*! The statistics for source LBT-RU transports. */
02913                 lbm_src_transport_stats_lbtru_t lbtru;
02914                 /*! The statistics for source LBT-IPC transports. */
02915                 lbm_src_transport_stats_lbtipc_t lbtipc;
02916                 /*! The statistics for source LBT-SMX transports. */
02917                 lbm_src_transport_stats_lbtsmx_t lbtsmx;
02918                 /*! The statistics for source LBT-RDMA transports. */
02919                 lbm_src_transport_stats_lbtrdma_t lbtrdma;
02920         } transport;
02921         char _fill[LBM_EXTERNAL_STRUCT_FILL_SIZE];
02922 } lbm_src_transport_stats_t;
02923 
02924 /*! \brief Structure that holds datagram statistics for receiver TCP transports */
02925 typedef struct lbm_rcv_transport_stats_tcp_t_stct {
02926         /*! Number of TCP datagram bytes received, i.e., the total of lengths of all TCP packets
02927                 including UM header information. */
02928         lbm_ulong_t bytes_rcved;
02929         /*! Number of messages or message fragments received over a TCP transport. A single
02930                 datagram may contain one or more messages or a fragment of a larger message. For
02931                 fragmented messages larger than configuration option
02932                 transport_tcp_datagram_max_size (default 64KB), this count reflects the number of
02933                 datagrams used to constitute those messages. Thus, this number is equal to or greater
02934                 than the datagram counter (msgs_rcved, above). This number also includes messages
02935                 received for which there was no interested receiver, which is tallied in the
02936                 lbm_msgs_no_topic_rcved counter (below). */
02937         lbm_ulong_t lbm_msgs_rcved;
02938         /*! Number of messages received that were not for a topic of interest to the receiver. A
02939                 high value (relative to, or approaching lbm_msgs_rcved above) indicates more CPU
02940                 time required to filter out uninteresting topics, in which case, consider
02941                 reconfiguring sources to filter more aggressively at the transport layer. */
02942         lbm_ulong_t lbm_msgs_no_topic_rcved;
02943         /*! Number of UM request messages received (message type LBM_MSG_REQUEST). */
02944         lbm_ulong_t lbm_reqs_rcved;
02945 } lbm_rcv_transport_stats_tcp_t;
02946 
02947 /*! \brief Structure that holds datagram statistics for receiver LBT-RM transports */
02948 typedef struct lbm_rcv_transport_stats_lbtrm_t_stct {
02949         /*! Number of LBT-RM datagrams received. Depending on batching settings, a single LBT-RM
02950                 datagram may contain one or more messages, or a fragment of a larger message. With
02951                 LBT-RM, larger messages are split into fragment sizes limited by configuration
02952                 option transport_lbtrm_datagram_max_size (default 8KB). */
02953         lbm_ulong_t msgs_rcved;
02954         /*! Number of LBT-RM datagram bytes received, i.e., the total of lengths of all LBT-RM
02955                 packets including UM header information. */
02956         lbm_ulong_t bytes_rcved;
02957         /*! Number of NAK packets sent by the receiver transport. UM batches NAKs into NAK packets
02958                 to save network bandwidth. This should always be less than or equal to the
02959                 number of individual NAKs sent (naks_sent, below). */
02960         lbm_ulong_t nak_pckts_sent;
02961         /*! Number of individual NAKs sent by the receiver transport. This may differ from the
02962                 tally of lost datagrams (below) due to reasons such as
02963                 \li Other receiver transports may have already sent a NAK for the same lost
02964                 datagram, resulting in a retransmitted lost datagram (or an NCF) to arrive at
02965                 this receiver transport before it has a chance to issue a NAK, or
02966                 \li During periods of heavy loss, receiver transports may be forced to issue
02967                 multiple NAKs per lost datagram (controlled by configuration options
02968                 transport_lbtrm_nak_generation_interval and
02969                 transport_lbtrm_nak_backoff_interval) until either the retransmission is
02970                 received or the datagram is declared unrecovered (which may ultimately lead to
02971                 UM delivering an LBM_MSG_UNRECOVERABLE_LOSS notification to the receiver
02972                 application). */
02973         lbm_ulong_t naks_sent;
02974         /*! Number of LBT-RM datagrams detected as lost. When a gap in
02975                 transport-level sequence numbers is detected, the "lost" statistic increases
02976                 by the size of the gap. Lost packets are typically recovered a
02977                 short time later (also see stats "unrecovered_txw" and "unrecovered_tmo"). 
02978                 Note that a network might reorder UDP packets. If LBT-RM datagrams arrive
02979                 out of order, the "lost" statistic is incremented. Subtracting the
02980                 "out_of_order" stat from "lost" shows a more accurate count of lost
02981                 datagrams. */
02982         lbm_ulong_t lost;
02983         /*! Number of NCFs received from a source transport with reason code "ignored". If a
02984                 source transport receives a NAK for a datagram that it has recently
02985                 retransmitted, it sends an "NCF ignored" and does not retransmit. How "recently"
02986                 is determined by the configuration option source transport_lbtrm_ignore_interval
02987                 (default 500ms). If this count is high, a receiver transport may be having
02988                 trouble receiving retransmissions, or the ignore interval may be set too long. */
02989         lbm_ulong_t ncfs_ignored;
02990         /*! Number of NCFs received with reason code "shed". When a source transport's retransmit
02991                 queue and rate limiter are both at maximum, it responds to a NAK by sending an
02992                 "NCF shed", and does not retransmit. The receiver transport should wait, then
02993                 send another NAK. If this count is high, one or more crybaby receiver transports
02994                 may be clogging the source transport's retransmit queue. */
02995         lbm_ulong_t ncfs_shed;
02996         /*! Number of NCFs received with reason code "rx_delay". When a source transport's
02997                 retransmit rate limiter prevents it from immediately retransmitting any more
02998                 lost datagrams, it responds to a NAK by sending an "NCF rx_delay", then queues
02999                 the retransmission for a later send. The receiver transport should wait for the
03000                 retransmission and not immediately send another NAK. If this count is high, one
03001                 or more crybaby receiver transports may be clogging the source transport's
03002                 retransmit queue. */
03003         lbm_ulong_t ncfs_rx_delay;
03004         /*! Number of NCFs received with reason code "unknown". These are NCFs with a reason code
03005                 this receiver transport does not recognize. After a delay (set by configuration
03006                 option transport_lbtrm_nak_suppress_interval (default 1000ms), it resends the
03007                 NAK. This counter should never be greater than 0 unless applications linked with
03008                 different versions of Ultra Messaging software coexist on the same network. */
03009         lbm_ulong_t ncfs_unknown;
03010         /*! Minimum time (in milliseconds), i.e., the shortest time recorded so far for a lost
03011                 message to be recovered. If this time is greater than configuration option
03012                 transport_lbtrm_nak_backoff_interval, it may be taking multiple NAKs to initiate
03013                 retransmissions, indicating a lossy network. */
03014         lbm_ulong_t nak_stm_min;
03015         /*! Mean time (in milliseconds) in which loss recovery was accomplished. This is an
03016                 exponentially weighted moving average (weighted to more recent) for accumulated
03017                 measured recovery times. Ideally this field should be as close to your minimum
03018                 recovery time (nak_stm_min, above) as possible. High mean recovery times indicate
03019                 a lossy network. */
03020         lbm_ulong_t nak_stm_mean;
03021         /*! Maximum time (in milliseconds), i.e., the longest time recorded so far for a lost
03022                 message to be recovered. If this time is near or equal to the configuration option
03023                 transport_lbtrm_nak_generation_interval setting, you have likely experienced some
03024                 level of unrecoverable loss. */
03025         lbm_ulong_t nak_stm_max;
03026         /*! Minimum number of times per lost message that a receiver transport transmitted a NAK,
03027                 i.e., the lowest value collected so far. A value greater than 1 indicates a
03028                 chronically lossy network. */
03029         lbm_ulong_t nak_tx_min;
03030         /*! Mean number of times per lost message that a receiver transport transmitted a NAK.
03031                 Ideally this should be at or near 1. A higher value indicates a lossy network.
03032                 This is an exponentially weighted moving average (weighted to more recent) for
03033                 accumulated NAKs per lost message. */
03034         lbm_ulong_t nak_tx_mean;
03035         /*! Maximum number of times per lost message that a receiver transport transmitted a NAK,
03036                 i.e., the highest value collected so far. A value higher than 1 suggests that
03037                 there may have been some unrecoverable loss on the network during the sample
03038                 period. A significantly high value (compared to the mean number) implies an
03039                 isolated incident. */
03040         lbm_ulong_t nak_tx_max;
03041         /*! Number of duplicate LBT-RM datagrams received. A large number can indicate a lossy
03042                 network, primarily due to other receiver transports requesting retransmissions
03043                 that this receiver transport has already successfully received. Such duplicates
03044                 require extra effort for filtering, and this should be investigated. */
03045         lbm_ulong_t duplicate_data;
03046         /*! Number of LBT-RM datagrams unrecovered (LBM_MSG_UNRECOVERABLE_LOSS delivered to receiver
03047                 application) due to transmission window advance. This means that the message was no
03048                 longer in the source-side transmission window and therefore not retransmitted. The
03049                 window size is set by transport configuration option lbtrm_transmission_window_size
03050                 (default 24MB). */
03051         lbm_ulong_t unrecovered_txw;
03052         /*! Number of LBT-RM datagrams unrecovered due to a retransmission not received within the
03053                 NAK generation interval (set by configuration option
03054                 transport_lbtrm_nak_generation_interval; default 10,000ms). Note: Receivers for
03055                 these messages' topics will also report related messages as unrecoverable, with
03056                 LBM_MSG_UNRECOVERABLE_LOSS for an individual message and
03057                 LBM_MSG_UNRECOVERABLE_LOSS_BURST for a burst loss event. However, it is possible
03058                 for these application-level message declarations to occur even without increments
03059                 to this counter, as the transport is unaware of the topic content of messages and
03060                 may still be trying to deliver related lost packets. */
03061         lbm_ulong_t unrecovered_tmo;
03062         /*! Number of messages or message fragments received over an LBT-RM transport. A single
03063                 datagram may contain one or more messages or a fragment of a larger message. For
03064                 fragmented messages larger than configuration option
03065                 transport_lbtrm_datagram_max_size (default 8KB), this count reflects the number of
03066                 datagrams used to constitute those messages. Thus, this number is equal to or greater
03067                 than the datagram counter (msgs_rcved, above). This number also includes messages
03068                 received for which there was no interested receiver, which is tallied in the
03069                 lbm_msgs_no_topic_rcved counter (below). */
03070         lbm_ulong_t lbm_msgs_rcved;
03071         /*! Number of messages received that were not for a topic of interest to the receiver. A
03072                 high value (relative to, or approaching lbm_msgs_rcved above) indicates more CPU
03073                 time required to filter out uninteresting topics, in which case, consider
03074                 reconfiguring sources to filter more aggressively at the transport layer. */
03075         lbm_ulong_t lbm_msgs_no_topic_rcved;
03076         /*! Number of UM request messages received (message type LBM_MSG_REQUEST). */
03077         lbm_ulong_t lbm_reqs_rcved;
03078         /*! Number of datagrams discarded due to being smaller than the size designated in the
03079                 datagram's size field.  */
03080         lbm_ulong_t dgrams_dropped_size;
03081         /*! Number of datagrams discarded due to bad packet type. The datagram's type field must
03082                 match the expectations of the receiver transport. */
03083         lbm_ulong_t dgrams_dropped_type;
03084         /*! Number of datagrams discarded due to version mismatch. The datagram's version field
03085                 must match the expectations of the receiver transport. */
03086         lbm_ulong_t dgrams_dropped_version;
03087         /*! Number of datagrams discarded due to bad header type. These datagrams appeared to be
03088                 intact, but with an unrecognizable header format. */
03089         lbm_ulong_t dgrams_dropped_hdr;
03090         /*! Number of unrecognizable datagrams discarded due to reasons other than those determined
03091                 by the above counts. They could be garbled, or possibly be from foreign or
03092                 incompatible software at the other end. */
03093         lbm_ulong_t dgrams_dropped_other;
03094         /*! Number of out-of-order LBT-RM datagrams received. A datagram is
03095                 counted as out of order if it has a sequence number lower than the
03096                 highest-received so far, but was not tagged as a retransmission. */
03097         lbm_ulong_t out_of_order;
03098 } lbm_rcv_transport_stats_lbtrm_t;
03099 
03100 /*! \brief Structure that holds statistics for receiver daemon mode transport (deprecated)
03101 
03102         This structure holds statistics for receiver transports using the daemon mode. NOTE: daemon
03103         mode is deprecated and no longer available; this structure is retained for for backward
03104         compatibility only.
03105 */
03106 typedef struct lbm_rcv_transport_stats_daemon_t_stct {
03107         /*! This statistic has been deprecated. */
03108         lbm_ulong_t bytes_rcved;
03109 } lbm_rcv_transport_stats_daemon_t;
03110 
03111 /*! \brief Structure that holds datagram statistics for receiver LBT-RU transports */
03112 typedef struct lbm_rcv_transport_stats_lbtru_t_stct {
03113         /*! Number of LBT-RU datagrams received. Depending on batching settings, a single LBT-RU
03114                 datagram may contain one or more messages, or a fragment of a larger message. With
03115                 LBT-RU, larger messages are split into fragment sizes limited by configuration
03116                 option transport_lbtru_datagram_max_size (default 8KB). */
03117         lbm_ulong_t msgs_rcved;
03118         /*! Number of LBT-RU datagram bytes received, i.e., the total of lengths of all LBT-RU
03119                 packets including UM header information. */
03120         lbm_ulong_t bytes_rcved;
03121         /*! Number of NAK packets sent by the receiver transport. UM batches NAKs into NAK packets
03122                 to save network bandwidth. This should always be less than or equal to the number of
03123                 individual NAKs sent (naks_sent, below). */
03124         lbm_ulong_t nak_pckts_sent;
03125         /*! Number of individual NAKs sent by the receiver transport. This may differ from the
03126                 tally of lost datagrams (below) due to reasons such as
03127                 \li Other receiver transports may have already sent a NAK for the same lost
03128                 datagram, resulting in a retransmitted lost datagram (or an NCF) to arrive at
03129                 this receiver transport before it has a chance to issue a NAK, or
03130                 \li During periods of heavy loss, receiver transports may be forced to issue
03131                 multiple NAKs per lost datagram (controlled by configuration options
03132                 transport_lbtru_nak_generation_interval and
03133                 transport_lbtru_nak_backoff_interval) until either the retransmission is
03134                 received or the datagram is declared unrecovered (which may ultimately lead to
03135                 UM delivering an LBM_MSG_UNRECOVERABLE_LOSS notification to the receiver
03136                 application). */
03137         lbm_ulong_t naks_sent;
03138         /*! Number of LBT-RU datagrams detected as lost. */
03139         lbm_ulong_t lost;
03140         /*! Number of NCFs received from a source transport with reason code "ignored". If a source
03141                 transport receives a NAK for a datagram that it has recently retransmitted, it
03142                 sends an "NCF ignored" and does not retransmit. How "recently" is determined by
03143                 the configuration option source transport_lbtru_ignore_interval (default 500ms).
03144                 If this count is high, a receiver transport may be having trouble receiving
03145                 retransmissions, or the ignore interval may be set too long. */
03146         lbm_ulong_t ncfs_ignored;
03147         /*! Number of NCFs received with reason code "shed". When a source transport's retransmit
03148                 queue and rate limiter are both at maximum, it responds to a NAK by sending an
03149                 "NCF shed", and does not retransmit. The receiver transport should wait, then
03150                 send another NAK. If this count is high, one or more crybaby receiver
03151                 transports may be clogging the source transport's retransmit queue. */
03152         lbm_ulong_t ncfs_shed;
03153         /*! Number of NCFs received with reason code "rx_delay". When a source transport's
03154                 retransmit rate limiter prevents it from immediately retransmitting any more
03155                 lost datagrams, it responds to a NAK by sending an "NCF rx_delay", then queues
03156                 the retransmission for a later send. The receiver transport should wait for the
03157                 retransmission and not immediately send another NAK. If this count is high, one
03158                 or more crybaby receiver transports may be clogging the source transport's
03159                 retransmit queue. */
03160         lbm_ulong_t ncfs_rx_delay;
03161         /*! Number of NCFs received with reason code "unknown". These are NCFs with a reason code
03162                 this receiver transport does not recognize. After a delay (set by configuration
03163                 option transport_lbtru_nak_suppress_interval (default 1000ms), it resends the
03164                 NAK. This counter should never be greater than 0 unless applications linked with
03165                 different versions of Ultra Messaging software coexist on the same network. */
03166         lbm_ulong_t ncfs_unknown;
03167         /*! Minimum time (in milliseconds), i.e., the shortest time recorded so far for a lost
03168                 message to be recovered. If this time is greater than configuration option
03169                 transport_lbtru_nak_backoff_interval, it may be taking multiple NAKs to initiate
03170                 retransmissions, indicating a lossy network. */
03171         lbm_ulong_t nak_stm_min;
03172         /*! Mean time (in milliseconds) in which loss recovery was accomplished. This is an
03173                 exponentially weighted moving average (weighted to more recent) for accumulated
03174                 measured recovery times. Ideally this field should be as close to your minimum
03175                 recovery time (nak_stm_min, above) as possible. High mean recovery times indicate
03176                 a lossy network. */
03177         lbm_ulong_t nak_stm_mean;
03178         /*! Maximum time (in milliseconds), i.e., the longest time recorded so far for a lost
03179                 message to be recovered. If this time is near or equal to the configuration option
03180                 transport_lbtru_nak_generation_interval setting, you have likely experienced some
03181                 level of unrecoverable loss. */
03182         lbm_ulong_t nak_stm_max;
03183         /*! Minimum number of times per lost message that a receiver transport transmitted a NAK,
03184                 i.e., the lowest value collected so far. A value greater than 1 indicates a
03185                 chronically lossy network. */
03186         lbm_ulong_t nak_tx_min;
03187         /*! Mean number of times per lost message that a receiver transport transmitted a NAK.
03188                 Ideally this should be at or near 1. A higher value indicates a lossy network.
03189                 This is an exponentially weighted moving average (weighted to more recent) for
03190                 accumulated NAKs per lost message. */
03191         lbm_ulong_t nak_tx_mean;
03192         /*! Maximum number of times per lost message that a receiver transport transmitted a NAK,
03193                 i.e., the highest value collected so far. A value higher than 1 suggests that
03194                 there may have been some unrecoverable loss on the network during the sample
03195                 period. A significantly high value (compared to the mean number) implies an
03196                 isolated incident. */
03197         lbm_ulong_t nak_tx_max;
03198         /*! Number of duplicate LBT-RU datagrams received. A large number can indicate a lossy
03199                 network, primarily due to other receiver transports requesting retransmissions
03200                 that this receiver transport has already successfully received. Such duplicates
03201                 require extra effort for filtering, and this should be investigated. */
03202         lbm_ulong_t duplicate_data;
03203         /*! Number of LBT-RU datagrams unrecovered (LBM_MSG_UNRECOVERABLE_LOSS delivered to receiver
03204                 application) due to transmission window advance. This means that the message was no
03205                 longer in the source-side transmission window and therefore not retransmitted. The
03206                 window size is set by transport configuration option lbtru_transmission_window_size
03207                 (default 24MB). */
03208         lbm_ulong_t unrecovered_txw;
03209         /*! Number of LBT-RU datagrams unrecovered due to a retransmission not received within the
03210                 NAK generation interval (set by configuration option
03211                 transport_lbtrm_nak_generation_interval; default 10,000ms). Note: Receivers for
03212                 these messages' topics will also report related messages as unrecoverable, with
03213                 LBM_MSG_UNRECOVERABLE_LOSS for an individual message and
03214                 LBM_MSG_UNRECOVERABLE_LOSS_BURST for a burst loss event. However, it is possible
03215                 for these application-level message declarations to occur even without increments
03216                 to this counter, as the transport is unaware of the topic content of messages and
03217                 may still be trying to deliver related lost packets. */
03218         lbm_ulong_t unrecovered_tmo;
03219         /*! Number of messages or message fragments received over an LBT-RU transport. A single
03220                 datagram may contain one or more messages or a fragment of a larger message. For
03221                 fragmented messages larger than configuration option
03222                 transport_lbtru_datagram_max_size (default 8KB), this count reflects the number of
03223                 datagrams used to constitute those messages. Thus, this number is equal to or greater
03224                 than the datagram counter (msgs_rcved, above). This number also includes messages
03225                 received for which there was no interested receiver, which is tallied in the
03226                 lbm_msgs_no_topic_rcved counter (below). */
03227         lbm_ulong_t lbm_msgs_rcved;
03228         /*! Number of messages received that were not for a topic of interest to the receiver. A
03229                 high value (relative to, or approaching lbm_msgs_rcved above) indicates more CPU
03230                 time required to filter out uninteresting topics, in which case, consider
03231                 reconfiguring sources to filter more aggressively at the transport layer. */
03232         lbm_ulong_t lbm_msgs_no_topic_rcved;
03233         /*! Number of UM request messages received (message type LBM_MSG_REQUEST). */
03234         lbm_ulong_t lbm_reqs_rcved;
03235         /*! Number of datagrams discarded due to being smaller than the size designated in the
03236                 datagram's size field.  */
03237         lbm_ulong_t dgrams_dropped_size;
03238         /*! Number of datagrams discarded due to bad packet type. The datagram's type field must
03239                 match the expectations of the receiver transport. */
03240         lbm_ulong_t dgrams_dropped_type;
03241         /*! Number of datagrams discarded due to version mismatch. The datagram's version field must
03242                 match the expectations of the receiver transport. */
03243         lbm_ulong_t dgrams_dropped_version;
03244         /*! Number of datagrams discarded due to bad header type. These datagrams appeared to be
03245                 intact, but with an unrecognizable header format. */
03246         lbm_ulong_t dgrams_dropped_hdr;
03247         /*! Number of datagrams discarded due to session ID mismatch. These datagrams appeared to be
03248                 correctly formed, but with an unmatched/unrecognized session ID field. */
03249         lbm_ulong_t dgrams_dropped_sid;
03250         /*! Number of unrecognizable datagrams discarded due to reasons other than those determined
03251                 by the above counts. They could be garbled, or possibly be from foreign or
03252                 incompatible software at the other end. */
03253         lbm_ulong_t dgrams_dropped_other;
03254 } lbm_rcv_transport_stats_lbtru_t;
03255 
03256 /*! \brief Structure that holds datagram statistics for receiver LBT-IPC transports */
03257 typedef struct lbm_rcv_transport_stats_lbtipc_t_stct {
03258         /*! Number of LBT-IPC datagrams received. Depending on batching settings, a single LBT-IPC
03259                 datagram may contain one or more messages, or a fragment of a larger message. With
03260                 LBT-IPC, larger messages are split into fragment sizes limited by configuration
03261                 option transport_lbtipc_datagram_max_size (default 64KB). */
03262         lbm_ulong_t msgs_rcved;
03263         /*! Number of LBT-IPC datagram bytes received, i.e., the total of lengths of all LBT-IPC
03264                 packets including UM header information. */
03265         lbm_ulong_t bytes_rcved;
03266         /*! Number of messages or message fragments received over an LBT-IPC transport. A single
03267                 datagram may contain one or more messages or a fragment of a larger message. For
03268                 fragmented messages larger than configuration option
03269                 transport_lbtipc_datagram_max_size (default 64KB), this count reflects the number
03270                 of datagrams used to constitute those messages. Thus, this number is equal to or
03271                 greater than the datagram counter (msgs_rcved, above). This number also includes
03272                 messages received for which there was no interested receiver, which is tallied in
03273                 the lbm_msgs_no_topic_rcved counter (below). */
03274         lbm_ulong_t lbm_msgs_rcved;
03275         /*! Number of messages received that were not for a topic of interest to the receiver. A
03276                 high value (relative to, or approaching lbm_msgs_rcved above) indicates more CPU
03277                 time required to filter out uninteresting topics, in which case, consider
03278                 reconfiguring sources to filter more aggressively at the transport layer. */
03279         lbm_ulong_t lbm_msgs_no_topic_rcved;
03280         /*! Number of UM request messages received (message type LBM_MSG_REQUEST). */
03281         lbm_ulong_t lbm_reqs_rcved;
03282 } lbm_rcv_transport_stats_lbtipc_t;
03283 
03284 
03285 /*! \brief Structure that holds datagram statistics for receiver LBT-SMX transports */
03286 typedef struct lbm_rcv_transport_stats_lbtsmx_t_stct {
03287         /*! Number of LBT-SMX datagrams received. */
03288         lbm_ulong_t msgs_rcved;
03289         /*! Number of LBT-SMX datagram bytes received, i.e., the total of lengths of all LBT-SMX
03290                 packets including UM header information. */
03291         lbm_ulong_t bytes_rcved;
03292         /*! Number of messages received over an LBT-SMX transport. A single
03293                 datagram may contain more than more messages provided the messages size is less than 
03294                 half the size of the configuration option
03295                 transport_lbtsmx_datagram_max_size (default 8192 bytes), This number also includes
03296                 messages received for which there was no interested receiver, tallied in
03297                 the lbm_msgs_no_topic_rcved counter. */
03298         lbm_ulong_t lbm_msgs_rcved;
03299         /*! Number of messages received that were not for a topic of interest to the receiver. A
03300                 high value (relative to, or approaching lbm_msgs_rcved above) indicates more CPU
03301                 time required to filter out uninteresting topics, in which case, consider
03302                 reconfiguring sources to filter more aggressively at the transport layer. */
03303         lbm_ulong_t lbm_msgs_no_topic_rcved;
03304         /*! Reserved field. Do not use. */
03305         lbm_ulong_t reserved1;
03306 } lbm_rcv_transport_stats_lbtsmx_t;
03307 
03308 /*! \brief Structure that holds datagram statistics for receiver LBT-RDMA transports */
03309 typedef struct lbm_rcv_transport_stats_lbtrdma_t_stct {
03310         /*! Number of LBT-RDMA datagrams received. Depending on batching settings, a single LBT-RDMA
03311                 datagram may contain one or more messages, or a fragment of a larger message. With
03312                 LBT-RDMA, larger messages are split into fragment sizes limited by configuration
03313                 option transport_lbtrdma_datagram_max_size (default 4KB). */
03314         lbm_ulong_t msgs_rcved;
03315         /*! Number of LBT-RDMA datagram bytes received, i.e., the total of lengths of all LBT-RDMA
03316                 packets including UM header information. */
03317         lbm_ulong_t bytes_rcved;
03318         /*! Number of messages or message fragments received over an LBT-RDMA transport. A single
03319                 datagram may contain one or more messages or a fragment of a larger message. For
03320                 fragmented messages larger than configuration option
03321                 transport_lbtrdma_datagram_max_size (default 4KB), this count reflects the number
03322                 of datagrams used to constitute those messages. Thus, this number is equal to or
03323                 greater than the datagram counter (msgs_rcved, above). This number also includes
03324                 messages received for which there was no interested receiver, which is tallied in
03325                 the lbm_msgs_no_topic_rcved counter (below). */
03326         lbm_ulong_t lbm_msgs_rcved;
03327         /*! Number of messages received that were not for a topic of interest to the receiver. A
03328                 high value (relative to, or approaching lbm_msgs_rcved above) indicates more CPU
03329                 time required to filter out uninteresting topics, in which case, consider
03330                 reconfiguring sources to filter more aggressively at the transport layer. */
03331         lbm_ulong_t lbm_msgs_no_topic_rcved;
03332         /*! Number of UM request messages received (message type LBM_MSG_REQUEST). */
03333         lbm_ulong_t lbm_reqs_rcved;
03334 } lbm_rcv_transport_stats_lbtrdma_t;
03335 
03336 /*! \brief Structure that holds statistics for receiver transports
03337 
03338         This structure holds statistics for all receiver transports. The structure is filled in when
03339         statistics for receiver transports are requested.
03340 */
03341 typedef struct lbm_rcv_transport_stats_t_stct {
03342         /*! Type of transport (e.g., LBM_TRANSPORT_STAT_TCP, LBM_TRANSPORT_STAT_LBTRM, etc.). */
03343         int type;
03344         /*! Source string of transport session, the format of which depends on the transport type.
03345                 For string formats and examples, see lbm_transport_source_info_t_stct. */
03346         char source[LBM_MSG_MAX_SOURCE_LEN];
03347         union {
03348                 /*! The statistics for receiver TCP transports. */
03349                 lbm_rcv_transport_stats_tcp_t tcp;
03350                 /*! The statistics for receiver LBT-RM transports. */
03351                 lbm_rcv_transport_stats_lbtrm_t lbtrm;
03352                 /*! These statistics have been deprecated. */
03353                 lbm_rcv_transport_stats_daemon_t daemon;
03354                 /*! The statistics for receiver LBT-RU transports. */
03355                 lbm_rcv_transport_stats_lbtru_t lbtru;
03356                 /*! The statistics for receiver LBT-IPC transports. */
03357                 lbm_rcv_transport_stats_lbtipc_t lbtipc;
03358                 /*! The statistics for receiver LBT-RDMA transports. */
03359                 lbm_rcv_transport_stats_lbtrdma_t lbtrdma;
03360                 /*! The statistics for receiver LBT-SMX transports. */
03361                 lbm_rcv_transport_stats_lbtsmx_t lbtsmx;
03362         } transport;
03363         char _fill[LBM_EXTERNAL_STRUCT_FILL_SIZE];
03364 } lbm_rcv_transport_stats_t;
03365 
03366 /*! \brief Opaque structure that holds attributes for event queue objects
03367 */
03368 struct lbm_event_queue_attr_t_stct;
03369 typedef struct lbm_event_queue_attr_t_stct lbm_event_queue_attr_t;
03370 
03371 /*! \brief Structure that holds statistics for an event queue
03372 
03373         This structure holds statistics for messages and other events that enter and exit the event
03374         queue. NOTE: Specific count-enable options must sometimes be enabled for these statistics to
03375         populate.
03376 */
03377 typedef struct lbm_event_queue_stats_t_stct {
03378         /*! Number of data messages currently in the event queue, i.e., a snapshot. Configuration
03379                 option queue_count_enabled must be activated. */
03380         lbm_ulong_t data_msgs;
03381         /*! Total accumulated number of data messages that have been added to the event queue
03382                 (even if subsequently de-queued) since last reset. Configuration
03383                 option queue_count_enabled must be activated. */
03384         lbm_ulong_t data_msgs_tot;
03385         /*! Minimum service time for data messages (in microseconds). This is the low-water mark
03386                 (i.e., the shortest so far) for data message service durations, measured from the
03387                 point of de-queuement until the application has finished servicing the message. 
03388                 Configuration option queue_service_time_enabled must be activated. */
03389         lbm_ulong_t data_msgs_svc_min;
03390         /*! Mean service time for data messages (in microseconds). This is an exponentially weighted
03391                 moving average (weighted to more recent) for accumulated data message service
03392                 durations, measured from the point of de-queuement until the application has
03393                 finished servicing the message. Configuration option queue_service_time_enabled
03394                 must be activated. */
03395         lbm_ulong_t data_msgs_svc_mean;
03396         /*! Maximum service time for data messages (in microseconds). This is the high-water mark
03397                 (i.e., the longest so far) for data message service durations measured from the
03398                 point of de-queuement until the application has finished servicing the message.
03399                 Configuration option queue_service_time_enabled must be activated. */
03400         lbm_ulong_t data_msgs_svc_max;
03401         /*! Number of response messages (from receiver objects) currently in the event queue, i.e.,
03402                 a snapshot. Configuration option queue_count_enabled must be activated. */
03403         lbm_ulong_t resp_msgs;
03404         /*! Total accumulated number of response messages that have been added to the event
03405                 queue (even if subsequently de-queued) since last reset. */
03406         lbm_ulong_t resp_msgs_tot;
03407         /*! Minimum service time for response messages (in microseconds). This is the low-water mark
03408                 (i.e., the shortest so far) for response message service durations, measured from
03409                 the point of de-queuement until the application has finished servicing the message. 
03410                 Configuration option queue_service_time_enabled must be activated. */
03411         lbm_ulong_t resp_msgs_svc_min;
03412         /*! Mean service time for response messages (in microseconds). This is an exponentially
03413                 weighted moving average (weighted to more recent) for accumulated response message
03414                 service durations, measured from the point of de-queuement until the application
03415                 has finished servicing the message. Configuration option queue_service_time_enabled
03416                 must be activated. */
03417         lbm_ulong_t resp_msgs_svc_mean;
03418         /*! Maximum service time for response messages (in microseconds). This is the high-water
03419                 mark (i.e., the longest so far) for response message service durations measured
03420                 from the point of de-queuement until the application has finished servicing the
03421                 message. Configuration option queue_service_time_enabled must be activated. */
03422         lbm_ulong_t resp_msgs_svc_max;
03423         /*! Number of topic-less Multicast Immediate Messaging (MIM) messages currently in the event
03424                 queue, i.e., a snapshot. Configuration option queue_count_enabled must be
03425                 activated. */
03426         lbm_ulong_t topicless_im_msgs;
03427         /*! Total accumulated number of topic-less Multicast Immediate Messaging (MIM) messages
03428                 that have been added to the event queue (even if subsequently de-queued) since last
03429                 reset. Configuration option queue_count_enabled must be activated. */
03430         lbm_ulong_t topicless_im_msgs_tot;
03431         /*! Minimum service time for topic-less Multicast Immediate Messaging (MIM) messages (in
03432                 microseconds). This is the low-water mark (i.e., the shortest so far) for topic-less
03433                 MIM message service durations, measured from the point of de-queuement until the
03434                 application has finished servicing the message. Configuration option
03435                 queue_service_time_enabled must be activated. */
03436         lbm_ulong_t topicless_im_msgs_svc_min;
03437         /*! Mean service time for topic-less Multicast Immediate Messaging (MIM) messages (in
03438                 microseconds). This is an exponentially weighted moving average (weighted to more
03439                 recent) for accumulated topic-less MIM message service durations, measured from the
03440                 point of de-queuement until the application has finished servicing the message.
03441                 Configuration option queue_service_time_enabled must be activated. */
03442         lbm_ulong_t topicless_im_msgs_svc_mean;
03443         /*! Maximum service time for topic-less Multicast Immediate Messaging (MIM) messages (in
03444                 microseconds). This is the high-water mark (i.e., the longest so far) for
03445                 topic-less MIM message service durations measured from the point of de-queuement
03446                 until the application has finished servicing the message. Configuration option
03447                 queue_service_time_enabled must be activated. */
03448         lbm_ulong_t topicless_im_msgs_svc_max;
03449         /*! Number of wildcard receiver messages currently in the event queue, i.e., a snapshot. 
03450                 Configuration option queue_count_enabled must be activated. */
03451         lbm_ulong_t wrcv_msgs;
03452         /*! Total accumulated number of wildcard receiver messages that have been added to the event
03453                 queue (even if subsequently de-queued) since last reset. Configuration option
03454                 queue_count_enabled must be activated. */
03455         lbm_ulong_t wrcv_msgs_tot;
03456         /*! Minimum service time for wildcard receiver messages (in microseconds). This is the
03457                 low-water mark (i.e., the shortest so far) for wildcard receiver message service
03458                 durations measured from the point of de-queuement until the application has
03459                 finished servicing the message. Configuration option queue_service_time_enabled
03460                 must be activated. */
03461         lbm_ulong_t wrcv_msgs_svc_min;
03462         /*! Mean service time for wildcard receiver messages (in microseconds). This is an
03463                 exponentially weighted moving average (weighted to more recent) for accumulated
03464                 wildcard receiver message service durations, measured from the point of
03465                 de-queuement until the application has finished servicing the message.
03466                 Configuration option queue_service_time_enabled must be activated. */
03467         lbm_ulong_t wrcv_msgs_svc_mean;
03468         /*! Maximum service time for wildcard receiver messages (in microseconds). This is the
03469                 high-water mark (i.e., the longest so far) for wildcard receiver message service
03470                 durations measured from the point of de-queuement until the application has
03471                 finished servicing the message. Configuration option queue_service_time_enabled
03472                 must be activated. */
03473         lbm_ulong_t wrcv_msgs_svc_max;
03474         /*! Number of I/O events currently in the event queue, i.e., a snapshot. Configuration
03475                 option queue_count_enabled must be activated. */
03476         lbm_ulong_t io_events;
03477         /*! Total accumulated number of I/O events that have been added to the event queue (even if
03478                 subsequently de-queued) since last reset. Configuration option queue_count_enabled
03479                 must be activated. */
03480         lbm_ulong_t io_events_tot;
03481         /*! Minimum service time for I/O events (in microseconds). This is the low-water mark
03482                 (i.e., the shortest so far) for I/O event service durations measured from the point
03483                 of de-queuement until the application has finished servicing the event.
03484                 Configuration option queue_service_time_enabled must be activated. */
03485         lbm_ulong_t io_events_svc_min;
03486         /*! Mean service time for I/O events (in microseconds). This is an exponentially weighted
03487                 moving average (weighted to more recent) for accumulated I/O event service
03488                 durations, measured from the point of de-queuement until the application has
03489                 finished servicing the event. Configuration option queue_service_time_enabled must
03490                 be activated. */
03491         lbm_ulong_t io_events_svc_mean;
03492         /*! Maximum service time for I/O events (in microseconds). This is the high-water mark
03493                 (i.e., the longest so far) for I/O event service durations measured from the point
03494                 of de-queuement until the application has finished servicing the event.
03495                 Configuration option queue_service_time_enabled must be activated. */
03496         lbm_ulong_t io_events_svc_max;
03497         /*! Number of timer events currently in the event queue, i.e., a snapshot. Configuration
03498                 option queue_count_enabled must be activated. */
03499         lbm_ulong_t timer_events;
03500         /*! Total accumulated number of timer events that have been added to the event queue (even
03501                 if subsequently de-queued) since last reset. Configuration option
03502                 queue_count_enabled must be activated. */
03503         lbm_ulong_t timer_events_tot;
03504         /*! Minimum service time for timer events (in microseconds). This is the low-water mark
03505                 (i.e., the shortest so far) for timer event service durations measured from the
03506                 point of de-queuement until the application has finished servicing the event.
03507                 Configuration option queue_service_time_enabled must be activated. */
03508         lbm_ulong_t timer_events_svc_min;
03509         /*! Mean service time for timer events (in microseconds). This is an exponentially weighted
03510                 moving average (weighted to more recent) for accumulated timer event service
03511                 durations, measured from the point of de-queuement until the application has
03512                 finished servicing the message. Configuration option queue_service_time_enabled
03513                 must be activated. */
03514         lbm_ulong_t timer_events_svc_mean;
03515         /*! Maximum service time for timer events (in microseconds). This is the high-water mark
03516                 (i.e., the longest so far) for timer event service durations measured from the
03517                 point of de-queuement until the application has finished servicing the event.
03518                 Configuration option queue_service_time_enabled must be activated. */
03519         lbm_ulong_t timer_events_svc_max;
03520         /*! Number of source events currently in the event queue, i.e., a snapshot. Configuration
03521                 option queue_count_enabled must be activated. */
03522         lbm_ulong_t source_events;
03523         /*! Total accumulated number of source events that have been added to the event queue (even
03524                 if subsequently de-queued) since last reset. Configuration option
03525                 queue_count_enabled must be activated. */
03526         lbm_ulong_t source_events_tot;
03527         /*! Minimum service time for source events (in microseconds). This is the low-water mark
03528                 (i.e., the shortest so far) for source event service durations measured from the
03529                 point of de-queuement until the application has finished servicing the event.
03530                 Configuration option queue_service_time_enabled must be activated. */
03531         lbm_ulong_t source_events_svc_min;
03532         /*! Mean service time for source events (in microseconds). This is an exponentially weighted
03533                 moving average (weighted to more recent) for accumulated source event service
03534                 durations, measured from the point of de-queuement until the application has
03535                 finished servicing the message. Configuration option queue_service_time_enabled
03536                 must be activated. */
03537         lbm_ulong_t source_events_svc_mean;
03538         /*! Maximum service time for source events (in microseconds). This is the high-water mark
03539                 (i.e., the longest so far) for source event service durations measured from the
03540                 point of de-queuement until the application has finished servicing the event.
03541                 Configuration option queue_service_time_enabled must be activated. */
03542         lbm_ulong_t source_events_svc_max;
03543         /*! Number of unblock events currently in the event queue, i.e., a snapshot. Configuration
03544                 option queue_count_enabled must be activated. */
03545         lbm_ulong_t unblock_events;
03546         /*! Total accumulated number of unblock events that have been added to the event queue
03547                 (even if subsequently de-queued) since last reset. Configuration option
03548                 queue_count_enabled must be activated. */
03549         lbm_ulong_t unblock_events_tot;
03550         /*! Number of cancel events currently in the event queue, i.e., a snapshot. Configuration
03551                 option queue_count_enabled must be activated. */
03552         lbm_ulong_t cancel_events;
03553         /*! Total accumulated number of cancel events that have been added to the event queue (even
03554                 if subsequently de-queued) since last reset. Configuration option
03555                 queue_count_enabled must be activated. */
03556         lbm_ulong_t cancel_events_tot;
03557         /*! Minimum service time for cancel events. Cancel events as seen by the event queue do not
03558                 actually consume service time, so we do not recommend the general use of this
03559                 counter. */
03560         lbm_ulong_t cancel_events_svc_min;
03561         /*! Mean service time for cancel events. Cancel events as seen by the event queue do not
03562                 actually consume service time, so we do not recommend the general use of this
03563                 counter. */
03564         lbm_ulong_t cancel_events_svc_mean;
03565         /*! Maximum service time for cancel events. Cancel events as seen by the event queue do not
03566                 actually consume service time, so we do not recommend the general use of this
03567                 counter. */
03568         lbm_ulong_t cancel_events_svc_max;
03569         /*! Number of context source events currently in the event queue, i.e., a snapshot.
03570                 Configuration option queue_count_enabled must be activated. */
03571         lbm_ulong_t context_source_events;
03572         /*! Total accumulated number of context source events that have been added to the event
03573                 queue (even if subsequently de-queued) since last reset. Configuration option
03574                 queue_count_enabled must be activated. */
03575         lbm_ulong_t context_source_events_tot;
03576         /*! Minimum service time for context source events (in microseconds). This is the low-water
03577                 mark (i.e., the shortest so far) for context source event service durations
03578                 measured from the point of de-queuement until the application has finished
03579                 servicing the event. Configuration option queue_service_time_enabled must be
03580                 activated. */
03581         lbm_ulong_t context_source_events_svc_min;
03582         /*! Mean service time for context source events (in microseconds). This is an exponentially
03583                 weighted moving average (weighted to more recent) for accumulated context source
03584                 event service durations, measured from the point of de-queuement until the
03585                 application has finished servicing the event. Configuration
03586                 option queue_service_time_enabled must be activated. */
03587         lbm_ulong_t context_source_events_svc_mean;
03588         /*! Maximum service time for context source events (in microseconds). This is the
03589                 high-water mark (i.e., the longest so far) for context source event service
03590                 durations measured from the point of de-queuement until the application has
03591                 finished servicing the event. Configuration option queue_service_time_enabled must
03592                 be activated. */
03593         lbm_ulong_t context_source_events_svc_max;
03594         /*! Total number of events (including messages) currently in the event queue, i.e., a
03595                 snapshot. Configuration option queue_count_enabled must be activated. */
03596         lbm_ulong_t events;
03597         /*! Total accumulated number of events (including messages) that have been added to the
03598                 event queue (even if subsequently de-queued) since last reset. Configuration option
03599                 queue_count_enabled must be activated. */
03600         lbm_ulong_t events_tot;
03601         /*! Minimum age of event queue entry when dequeued (in microseconds). This is the low-water
03602                 mark for the measured age of any event or message (i.e., the shortest one so far)
03603                 from the point of enqueuement until de-queuement. Configuration option
03604                 queue_age_enabled must be activated. */
03605         lbm_ulong_t age_min;
03606         /*! Mean age of event queue entries when dequeued (in microseconds). This is an
03607                 exponentially weighted moving average (weighted to more recent) for accumulated
03608                 event or message ages (measured from the point enqueuement until de-queuement).
03609                 Configuration option queue_age_enabled must be activated. */
03610         lbm_ulong_t age_mean;
03611         /*! Maximum age of event queue entry when dequeued (in microseconds). This is the
03612                 high-water mark for the measured age of any event or message (i.e., the oldest one
03613                 so far) from the point of enqueuement until de-queuement. Configuration option
03614                 queue_age_enabled must be activated. */
03615         lbm_ulong_t age_max;
03616         /*! Number of callback events currently in the event queue, i.e., a snapshot. Configuration
03617                 option queue_count_enabled must be activated. */
03618         lbm_ulong_t callback_events;
03619         /*! Total accumulated number of callback events that have been added to the event queue 
03620                 even if subsequently de-queued) since last reset. Configuration option
03621                 queue_count_enabled must be activated. */
03622         lbm_ulong_t callback_events_tot;
03623         /*! Minimum service time for callback events (in microseconds). This is the low-water mark
03624                 (i.e., the shortest so far) for callback event service durations measured from the
03625                 point of de-queuement until the application has finished servicing the event.
03626                 Configuration option queue_service_time_enabled must be activated. */
03627         lbm_ulong_t callback_events_svc_min;
03628         /*! Mean service time for callback events (in microseconds). This is an exponentially
03629                 weighted moving average (weighted to more recent) for accumulated callback event
03630                 service durations, measured from the point of de-queuement until the application
03631                 has finished servicing the message. Configuration option
03632                 queue_service_time_enabled must be activated. */
03633         lbm_ulong_t callback_events_svc_mean;
03634         /*! Maximum service time for callback events (in microseconds). This is the high-water
03635                 mark (i.e., the longest so far) for callback event service durations measured from
03636                 the point of de-queuement until the application has finished servicing the event.
03637                 Configuration option queue_service_time_enabled must be activated. */
03638         lbm_ulong_t callback_events_svc_max;
03639 } lbm_event_queue_stats_t;
03640 
03641 /*! \brief Structure that holds statistics for a context
03642 
03643         This structure holds general context statistics for things like topic resolution
03644         and interaction with transports and applications. 
03645 */
03646 typedef struct lbm_context_stats_t_stct {
03647         /*! Number of topic resolution datagrams sent from this context. Each datagram can contain
03648                 one or more advertisements, queries, query responses, etc. from source or receiver
03649                 objects. A faster accumulation of counts typically indicates more source, receiver,
03650                 and/or context objects are being created. */
03651         lbm_ulong_t tr_dgrams_sent;
03652         /*! Number of topic resolution datagram bytes sent. This count is triggered under the
03653                 same circumstances as tr_dgrams_sent (above), but measures the total number of bytes
03654                 for all datagrams sent, including their headers. */
03655         lbm_ulong_t tr_bytes_sent;
03656         /*! Number of topic resolution datagrams received by this context. Each datagram can contain
03657                 one or more advertisements, queries, query responses, etc. from source or receiver
03658                 objects. A faster accumulation of counts typically indicates more source, receiver,
03659                 and/or context objects are being created. */
03660         lbm_ulong_t tr_dgrams_rcved;
03661         /*! Number of topic resolution datagram bytes received. This count is triggered under the
03662                 same circumstances as tr_dgrams_rcved (above), but measures the total number of
03663                 bytes for all datagrams received, including their headers. */
03664         lbm_ulong_t tr_bytes_rcved;
03665         /*! Number of topic resolution datagrams discarded due to incorrect version. The datagram's
03666                 version field must match the expectations of the receiving context. */
03667         lbm_ulong_t tr_dgrams_dropped_ver;
03668         /*! Number of topic resolution datagrams discarded due to incorrect type. The datagram's
03669                 type field must match the expectations of the receiving context. */
03670         lbm_ulong_t tr_dgrams_dropped_type;
03671         /*! Number of topic resolution datagrams discarded due to being malformed or corrupted. */
03672         lbm_ulong_t tr_dgrams_dropped_malformed;
03673         /*! Number of topic resolution datagram sends that failed. This count should be at or at
03674                 least near 0. */
03675         lbm_ulong_t tr_dgrams_send_failed;
03676         /*! Number of topics in the source topic resolver cache (also referred to as the topic
03677                 map). Inordinately large or growing values here may impact performance. */
03678         lbm_ulong_t tr_src_topics;
03679         /*! Total number of topics in the receiver topic resolver cache (also referred to as the
03680                 topic map). Inordinately large or growing values here may impact performance. */
03681         lbm_ulong_t tr_rcv_topics;
03682         /*! Number of unresolved topics in the receiver topic resolver cache (aka topic map).
03683                 Inordinately large or growing values here may impact performance, though this count
03684                 can be close to the total number of topics in the resolver cache under normal
03685                 conditions. */
03686         lbm_ulong_t tr_rcv_unresolved_topics;
03687         /*! Number of LBT-RM datagrams received not belonging to any transport session. Such
03688                  occurrences should be investigated. These datagrams can be from a source in a
03689                  different topic resolution domain targeting the same group (or IP) and port
03690                  as a source of interest on this receiver's topic resolution domain. Among less
03691                  likely possibilities would be an attempt to spoof UM messages. */
03692         lbm_ulong_t lbtrm_unknown_msgs_rcved;
03693         /*! Number of datagrams received that do not belong to a currently-subscribed LBT-RM
03694                 transport session. This is typically due to improper or suboptimal UM configuration,
03695                 or to interference from non-UM network applications. Steady increases in this
03696                 statistic indicate a waste in CPU resources to read and discard the datagrams. A
03697                 common cause is different application instances creating transport sessions with the
03698                 same multicast group and destination port. */
03699         lbm_ulong_t lbtru_unknown_msgs_rcved;
03700         /*! Number of incidents where a UM send call was blocked. Unusually high counts could
03701                 indicate performance degradation or I/O problems. */
03702         lbm_ulong_t send_blocked;
03703         /*! Number of incidents where a UM send call returned EWOULDBLOCK. This is when a send call
03704                 set to be nonblocking encounters an error condition where it would otherwise be
03705                 blocked. Under normal operating conditions, this count should be at or near 0. */
03706         lbm_ulong_t send_would_block;
03707         /*! Number of incidents where a UM send response call was blocked. Unusually high counts
03708                 could indicate performance degradation or I/O problems. */
03709         lbm_ulong_t resp_blocked;
03710         /*! Number of incidents where a UM send response call returned EWOULDBLOCK. This is when a
03711                 send response call set as nonblocking encounters an error condition where it would
03712                 otherwise be blocked. Under normal operating conditions, this count should be at
03713                 or near 0. */
03714         lbm_ulong_t resp_would_block;
03715         /*! Number of duplicate unicast immediate messages (UIMs) received and dropped. */
03716         lbm_ulong_t uim_dup_msgs_rcved;
03717         /*! Number of unicast immediate messages (UIMs) received without stream information. */
03718         lbm_ulong_t uim_msgs_no_stream_rcved;
03719         /*! For internal use only. Number of data message fragments detected as lost in the context. 
03720                 UM fragments messages larger than the maximum datagram size for the 
03721                 transport and assigns a unique sequence number to each fragment. 
03722                 UM increments the count when a delivery controller in the context detects 
03723                 a gap in fragment sequence numbers. Lost request responses, 
03724                 Multicast Immediate Message (MIM) messages, or Unicast Immediate 
03725                 Message (UIM) control messages do not increase this statistic. Lost message 
03726                 fragments sent to hot-failover receivers with arrival-order delivery and lost 
03727                 message fragments sent over LBT-SMX do not increase this statistic. */
03728         lbm_ulong_t fragments_lost;
03729         /*! For internal use only. Number of data message fragments detected as unrecoverably 
03730                 lost in the context. UM fragments messages larger than the maximum datagram 
03731                 size for the transport and assigns a unique sequence number to each fragment. 
03732                 UM increments the count when a delivery controller in the context sends a 
03733                 LBM_MSG_UNRECOVERABLE_LOSS or  LBM_MSG_UNRECOVERABLE_LOSS_BURST 
03734                 event to the receiving application.
03735                 Unrecoverably lost message fragments sent to hot-failover receivers with 
03736                 arrival-order delivery do not increment this statistic. An unrecoverable loss 
03737                 event sent by a delivery controller for a receiver underlying the hot-failover 
03738                 receiver does increment this statistic if another underlying receiver was able 
03739                 to compensate. Unrecoverably lost message fragments sent over LBT-SMX do 
03740                 not increment this statistic.  */
03741         lbm_ulong_t fragments_unrecoverably_lost;
03742         /*! For internal use only. The minimum time in microseconds used to call user receive 
03743                 callbacks of type lbm_rcv_cb_proc() for wildcard, hot-failover, and regular 
03744                 receivers. Does not include SMX receivers. Does not include minimum times 
03745                 for any other context thread callbacks, such as timer callback or immediate 
03746                 message callbacks. The initial value before UM Monitoring reports any data is 
03747                 the largest possible unsigned integer, which is 4294967295 for 32-bit system 
03748                 and 18446744073709551615 for 64-bit system. Ultra Messaging computes the 
03749                 minimum value as the smaller of the current measured value and the current 
03750                 statistic value. The largest possible value equates to no measurement. 
03751                 For the Java and .NET APIs, includes the
03752                 overhead time spent crossing the managed/jni boundaries. 
03753                 You must set the configuration option
03754                 receiver_callback_service_time_enabled to populate this statistic. */
03755         lbm_ulong_t rcv_cb_svc_time_min;
03756         /*! For internal use only. The maximum time in microseconds used to call user 
03757                 receive callbacks of type lbm_rcv_cb_proc() for wildcard, hot-failover, 
03758                 and regular receivers. Does not include SMX receivers. 
03759                 Does not include minimum times for any other 
03760                 context thread callbacks, such as timer callback or immediate message 
03761                 callbacks. The initial value before any data has been reported is zero. 
03762                 UM computes the maximum value as the larger of the current 
03763                 measured value and the current statistic value. A value of zero equates 
03764                 to no measurement. For the Java and .NET APIs, includes the
03765                 overhead time spent crossing the managed/jni boundaries. 
03766                 You must set the configuration option
03767                 receiver_callback_service_time_enabled to populate this statistic.  */
03768         lbm_ulong_t rcv_cb_svc_time_max;
03769         /*! For internal use only. The mean time in microseconds used to call user receive 
03770                 callbacks of type lbm_rcv_cb_proc() for wildcard, hot-failover, and regular 
03771                 receivers. Does not include SMX receivers. Does not include minimum times 
03772                 for any other context thread callbacks, such as timer callback or immediate 
03773                 message callbacks. For the Java and .NET APIs, includes the
03774                 overhead time spent crossing the managed/jni boundaries. 
03775                 You must set the configuration option
03776                 receiver_callback_service_time_enabled to populate this statistic. */
03777         lbm_ulong_t rcv_cb_svc_time_mean;
03778 } lbm_context_stats_t;
03779 
03780 /*! \brief Structure that holds statistics for a receiver topic
03781 
03782         THIS STRUCTURE IS UNSUPPORTED.
03783 */
03784 typedef struct lbm_rcv_topic_stats_t_stct {
03785         /*! Topic for the receiver. THIS FIELD IS UNSUPPORTED. */
03786         char topic[LBM_MSG_MAX_TOPIC_LEN];
03787         /*! Flags for the receiver. THIS FIELD IS UNSUPPORTED. */
03788         lbm_uint32_t flags;
03789         /*! Source string for a transport joined by the receiver. THIS FIELD IS UNSUPPORTED. */
03790         char source[LBM_MSG_MAX_SOURCE_LEN];
03791         /*! Originating transport ID for a transport joined by the receiver. THIS FIELD IS UNSUPPORTED. */
03792         lbm_uint8_t otid[LBM_OTID_BLOCK_SZ];
03793         /*! Topic index for a transport joined by the receiver. THIS FIELD IS UNSUPPORTED. */
03794         lbm_uint32_t topic_idx;
03795 } lbm_rcv_topic_stats_t;
03796 /*! Receiver topic stats structure indicating the source information is valid. */
03797 #define LBM_RCV_TOPIC_STATS_FLAG_SRC_VALID 0x1
03798 
03799 /*! \brief Structure that holds statistics for a wildcard receiver
03800 
03801         THIS STRUCTURE IS UNSUPPORTED.
03802 */
03803 typedef struct lbm_wildcard_rcv_stats_t_stct {
03804         /*! Pattern for the wildcard receiver. THIS FIELD IS UNSUPPORTED. */
03805         char pattern[LBM_MSG_MAX_TOPIC_LEN];
03806         /*! Pattern type for the wildcard receiver. THIS FIELD IS UNSUPPORTED. */
03807         lbm_uint8_t type;
03808 } lbm_wildcard_rcv_stats_t;
03809 
03810 /*! \brief Application callback for timer events.
03811 
03812            Set by lbm_schedule_timer().
03813            If this application callback is set without an event queue, it is
03814            called from the context thread and is limited in the API calls that
03815            it can make.
03816   \param ctx Context running the timer.
03817   \param clientd Client data pointer supplied in lbm_schedule_timer().
03818   \return 0 always.
03819 */
03820 typedef int (*lbm_timer_cb_proc)(lbm_context_t *ctx, const void *clientd);
03821 
03822 /*! \brief Application callback for receiver events.
03823 
03824            Set by lbm_rcv_create().
03825            If this application callback is set without an event queue, it is
03826            called from the context thread and is limited in the API calls that
03827            it can make.
03828 
03829            After the callback returns, the message
03830            object \a msg is deleted and the application must not refer to it.
03831            This behavior can be overridden by calling lbm_msg_retain() from
03832            the receive callback before it returns.  It then becomes the
03833            application's responsibility to delete the message object
03834            using lbm_msg_delete().
03835 
03836   \note For received application messages, be aware that UM does not
03837         guarantee any alignment of that data.
03838   \param rcv Receiver object generating the event.
03839   \param msg Message object containing the receiver event.
03840   \param clientd Client data pointer supplied in lbm_rcv_create().
03841   \return 0 always.
03842 */
03843 typedef int (*lbm_rcv_cb_proc)(lbm_rcv_t *rcv, lbm_msg_t *msg, void *clientd);
03844 
03845 /*! \brief Application callback for events associated with an application
03846            file descriptor or socket.
03847 
03848            Set by lbm_register_fd().
03849            If this application callback is set without an event queue, it is
03850            called from the context thread and is limited in the API calls that
03851            it can make.
03852   \param ctx Context monitoring the \a handle.
03853   \param handle File descriptor or socket generating the event.
03854   \param ev One or more of LBM_FD_EVENT_* (ORed together) indicating the event type.
03855   \param clientd Client data pointer supplied in lbm_register_fd().
03856   \return 0 always.
03857 */
03858 typedef int (*lbm_fd_cb_proc)(lbm_context_t *ctx, lbm_handle_t handle, lbm_ulong_t ev, void *clientd);
03859 
03860 /*! \brief Application callback for events associated with a source.
03861 
03862            Set by lbm_src_create() and lbm_hf_src_create().
03863            If this application callback is set without an event queue, it is
03864            called from the context thread and is limited in the API calls that
03865            it can make.
03866   \param src Source object generating the event.
03867   \param event One of LBM_SRC_EVENT_* indicating event type.
03868   \param ed Pointer to event data, content dependent on event type.
03869          \arg For \a event == LBM_SRC_EVENT_CONNECT (not applicable for LBT-RM),
03870               \a ed should be re-cast as a (char *) and points at the receiver
03871               as a string.  Format depends on transport type.  Formats containing
03872                           IP address and Port pertain to the receiver's IP and Port.
03873                 For string formats and examples, see lbm_transport_source_info_t_stct.
03874          \arg For \a event == LBM_SRC_EVENT_DISCONNECT (not applicable for LBT-RM),
03875               \a ed should be re-cast as a (char *) and points at the receiver
03876               as a string (see above).
03877          \arg For \a event == LBM_SRC_EVENT_WAKEUP,
03878               \a ed should be re-cast as a (lbm_src_event_wakeup_t) and indicates which
03879               source has become un-blocked.
03880          \arg For \a event == LBM_SRC_EVENT_SEQUENCE_NUMBER_INFO,
03881               \a ed should be re-cast as a (lbm_src_event_sequence_number_info_t *)
03882                           to extract the sequence number information.
03883          \arg For \a event == LBM_SRC_EVENT_UME_REGISTRATION_ERROR,
03884               \a ed should be re-cast as a (const char *)
03885                           to extract the error message.
03886          \arg For \a event == LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS,
03887               \a ed should be re-cast as a (lbm_src_event_ume_registration_t *)
03888                           to extract the registration information.
03889          \arg For \a event == LBM_SRC_EVENT_UME_REGISTRATION_SUCCESS_EX,
03890               \a ed should be re-cast as a (lbm_src_event_ume_registration_ex_t *)
03891                           to extract the extra registration information.
03892          \arg For \a event == LBM_SRC_EVENT_UME_REGISTRATION_COMPLETE_EX,
03893               \a ed should be re-cast as a (lbm_src_event_ume_registration_complete_ex_t *)
03894                           to extract the extra registration completion information.
03895          \arg For \a event == LBM_SRC_EVENT_UME_MESSAGE_STABLE,
03896               \a ed should be re-cast as a (lbm_src_event_ume_ack_info_t *)
03897                           to extract the UMP message acknowledgment information.
03898          \arg For \a event == LBM_SRC_EVENT_UME_MESSAGE_STABLE_EX,
03899               \a ed should be re-cast as a (lbm_src_event_ume_ack_ex_info_t *)
03900                           to extract the extra UMP message acknowledgment information.
03901          \arg For \a event == LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION,
03902               \a ed should be re-cast as a (lbm_src_event_ume_ack_info_t *)
03903                           to extract the UMP message acknowledgment information.
03904          \arg For \a event == LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX,
03905               \a ed should be re-cast as a (lbm_src_event_ume_ack_ex_info_t *)
03906                           to extract the extra UMP message acknowledgment information.
03907          \arg For \a event == LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED,
03908               \a ed should be re-cast as a (lbm_src_event_ume_ack_info_t *)
03909                           to extract the UMP message acknowledgment information.
03910          \arg For \a event == LBM_SRC_EVENT_UME_STORE_UNRESPONSIVE,
03911               \a ed should be re-cast as a (const char *)
03912                           to extract the UMP store name.
03913          \arg For \a event == LBM_SRC_EVENT_FLIGHT_SIZE_NOTIFICATION,
03914               \a ed should be re-cast as a (lbm_src_event_flight_size_notification_t *)
03915                           to extract the flight size information.
03916          \arg For \a event == LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX,
03917               \a ed should be re-cast as a (lbm_src_event_ume_ack_ex_info_t *)
03918                           to extract the UMP message acknowledgment information.
03919          \arg For all other event types, \a ed contains nothing and should be ignored.
03920   \param clientd Client data pointer supplied in lbm_src_create(), etc.
03921   \return 0 always
03922 */
03923 typedef int (*lbm_src_cb_proc)(lbm_src_t *src, int event, void *ed, void *clientd);
03924 
03925 /*! \brief Application callback for responses returned when a request is sent.
03926 
03927            Set by lbm_send_request(), lbm_multicast_immediate_request(),
03928            lbm_unicast_immediate_request().
03929            If this application callback is set without an event queue, it is
03930            called from the context thread and is limited in the API calls
03931            that it can make.
03932 
03933   \note For received application messages, be aware that UM does not
03934         guarantee any alignment of that data.
03935   \param req Request object receiving the response.
03936   \param msg Pointer to received message.
03937   \param clientd Client data pointer supplied in lbm_send_request(), etc.
03938   \return 0 always.
03939 */
03940 typedef int (*lbm_request_cb_proc)(lbm_request_t *req, lbm_msg_t *msg, void *clientd);
03941 
03942 /*! \brief Application callback for event queue monitor events.
03943 
03944            Set by lbm_event_queue_create().
03945            NOTE: this application callback can be made from the context
03946            thread, and is therefore limited in the UM API calls it can make.
03947            (Specifically, the context calls it for the enqueue notification.)
03948            Note that the one or more event
03949            queue options must be set to enable the use of event queue
03950            monitoring.
03951   \param evq Event queue generating the event.
03952   \param event One of LBM_EVENT_QUEUE_*_WARNING or
03953          LBM_EVENT_QUEUE_ENQUEUE_NOTIFICATION, depending on enabled options.
03954   \param evq_size Number of events currently in the queue.
03955   \param event_delay_usec Number of microseconds the oldest event has been
03956          in the event queue.  (Note, this will be the next event dispatched.)
03957   \param clientd Client data pointer supplied in lbm_event_queue_create().
03958   \return 0 for success, -1 for failure.
03959   \note The \a event parameter operates as both a value and a bitmask,
03960         and the monitor function may be called to indicate both a size and delay warning.
03961         The value of ::LBM_EVENT_QUEUE_ENQUEUE_NOTIFICATION is the same as the value of
03962                 (::LBM_EVENT_QUEUE_DELAY_WARNING | ::LBM_EVENT_QUEUE_SIZE_WARNING).
03963         \par
03964         If \a event is ::LBM_EVENT_QUEUE_ENQUEUE_NOTIFICATION,
03965                 \a evq_size is 1,
03966         and \a evq_delay_usec is 0,
03967                 the callback is due to an event being enqueued.
03968                 To distinguish between an enqueue notification and a size or delay warning,
03969                 the following code template may be used.
03970   \code
03971 int event_queue_monitor_proc(lbm_event_queue_t * evq, int event,
03972     size_t evq_size, lbm_ulong_t event_delay_usec, void * clientd)
03973 {
03974     if ((event == LBM_EVENT_QUEUE_ENQUEUE_NOTIFICATION)
03975         && (evq_size == 1) && (event_delay_usec == 0))
03976     {
03977         // This is an ENQUEUE notification.
03978         return (0);
03979     }
03980     if ((event & LBM_EVENT_QUEUE_SIZE_WARNING) != 0)
03981     {
03982         // Size warning, event queue size is in evq_size
03983     }
03984     if ((event & LBM_EVENT_QUEUE_DELAY_WARNING) != 0)
03985     {
03986         // Delay warning, delay of oldest (about to be dequeued)
03987         // message is in event_delay_usec.
03988     }
03989     return (0);
03990 }
03991 \endcode
03992 
03993 
03994 */
03995 typedef int (*lbm_event_queue_monitor_proc)(lbm_event_queue_t *evq, int event, size_t evq_size,
03996                                                                                         lbm_ulong_t event_delay_usec, void *clientd);
03997 
03998 /*! \brief Application callback for message logging.
03999 
04000            Set by lbm_log().
04001            NOTE: this application callback can be made from the context
04002            thread, and is therefore limited in the UM API calls it can make.
04003   \param level One of LBM_LOG_* indicating severity level. Values can be (in order of decreasing importance):
04004         \li LBM_LOG_EMERG
04005         \li LBM_LOG_ALERT
04006         \li LBM_LOG_CRIT
04007         \li LBM_LOG_ERR
04008         \li LBM_LOG_WARNING
04009         \li LBM_LOG_NOTICE
04010         \li LBM_LOG_INFO
04011         \li LBM_LOG_DEBUG
04012   \param message Pointer to error message string.
04013   \param clientd Client data pointer supplied in lbm_log().
04014   \return 0 always.
04015 */
04016 typedef int (*lbm_log_cb_proc)(int level, const char *message, void *clientd);
04017 
04018 /*! \brief Application callback for daemon events.
04019 
04020            Set by lbm_context_create().  Only used when operation_mode is
04021            set to daemon.
04022            NOTE: this application callback is always made from the context
04023            thread, and is therefore limited in the UM API calls it can make.
04024               NOTE: daemon mode is no longer available; this definition is retained for
04025               for backward compatibility only.
04026   \param ctx Context generating the event.
04027   \param event One of LBM_DAEMON_EVENT_* indicating event type.
04028   \param info Pointer to LBM-supplied string giving more information.
04029   \param clientd Client data pointer supplied in lbm_context_create().
04030   \return 0 always.
04031 */
04032 typedef int (*lbm_daemon_event_cb_proc)(lbm_context_t *ctx, int event, const char *info, void *clientd);
04033 
04034 /*! \brief Application callback for lbm_*_delete_ex().
04035 
04036            Set by lbm_*_delete_ex().
04037            NOTE: this application callback can be made from the context
04038            thread, and is therefore limited in the UM API calls it can make.
04039            The application is called after all events associated with the
04040            delete are canceled or completed.
04041   \sa lbm_event_queue_cancel_cb_info_t
04042   \param dispatch_thrd Indicates from where the callback is being called.
04043          This can be useful to the application to avoid deadlock.
04044            \arg 1 - Called by dispatch thread (after the lbm_*_delete_ex() returned).
04045            \arg 0 - Called directly by the lbm_*_delete_ex() function.
04046   \param clientd Client data pointer supplied in the lbm_event_queue_cancel_cb_info_t passed to the lbm_*_delete_ex().
04047   \return 0 always.
04048 */
04049 typedef void (*lbm_event_queue_cancel_cb_proc)(int dispatch_thrd, void *clientd);
04050 
04051 /*! \brief Structure passed to cancel/delete functions so that a cancel callback
04052            may be called.
04053 */
04054 typedef struct lbm_event_queue_cancel_cb_info_t_stct {
04055         /*! The event queue for the cancel callback */
04056         lbm_event_queue_t *event_queue;
04057         /*! The cancel callback function */
04058         lbm_event_queue_cancel_cb_proc cbproc;
04059         /*! Client Data passed in the cancel callback when called */
04060         void *clientd;
04061 } lbm_event_queue_cancel_cb_info_t;
04062 
04063 /*! \brief Application callback for lbm_*_flight_size_set_inflight().
04064 
04065            Set by lbm_*_flight_size_set_inflight().
04066   \param inflight Gives the current inflight value.
04067   \param clientd Client data pointer supplied in the call to lbm_*_flight_size_set_inflight().
04068   \return The new inflight value.
04069 */
04070 typedef int (*lbm_flight_size_set_inflight_cb_proc)(int inflight, void *clientd);
04071 
04072 /*! \brief Application callback for lbm_ume_flight_size_set_inflight_ex().
04073         Change the inflight parameter messages and bytes to update the current settings.
04074         \param inflight Pointer to a structure containing current inflight values for both messages and bytes.
04075         \param clientd Client data pointer supplied in the call to lbm_ume_flight_size_set_inflight_ex().
04076 */
04077 typedef void (*lbm_flight_size_set_inflight_ex_cb_proc)(lbm_flight_size_inflight_t *inflight, void *clientd);
04078 /* Functions */
04079 
04080 /*! \brief return the version string compiled into UM.
04081 
04082   \return String containing version information for UM.
04083 */
04084 LBMExpDLL const char *lbm_version(void);
04085 
04086 /*! \brief Retrieves all context attribute options.
04087 
04088         The config object is filled with context configuration options
04089         \param ctx The context object to retrieve the attributes from
04090         \param size Size of the opts array. Will return the number of items that were set in opts
04091         \param opts The options array to fill
04092         */
04093 LBMExpDLL int lbm_context_dump(lbm_context_t *ctx, int *size, lbm_config_option_t *opts);
04094 
04095 /*! \brief Retrieves all context attribute options.
04096 
04097         The config object is filled with context configuration options
04098         \param cattr The context attribute object to retrieve the attributes from
04099         \param size Size of the opts array. Will return the number of items that were set in opts
04100         \param opts The options array to fill
04101         */
04102 LBMExpDLL int lbm_context_attr_dump(lbm_context_attr_t *cattr, int *size, lbm_config_option_t *opts);
04103 
04104 /*! \brief Retrieves the number of options that are of type "context"
04105 
04106         The function returns the number of entries that are of type "context"
04107 
04108         \return The number of entries that are of type "context"
04109 */
04110 LBMExpDLL int lbm_context_attr_option_size();
04111 
04112 /*! \brief Create and fill a UM context attribute object with the current default values.
04113 
04114   The attribute object is allocated and filled with the current default values that are
04115   used by lbm_context_t objects and may have been modified by a previously loaded configuration file.
04116 
04117   \param attr A pointer to a pointer to a UM context attribute structure. Will be
04118     filled in by this function to point to the newly created lbm_context_attr_t object.
04119   \return 0 for Success and -1 for Failure.
04120 */
04121 LBMExpDLL int lbm_context_attr_create(lbm_context_attr_t * * attr);
04122 
04123 /*! \brief Create and fill a UM context attribute object with the initial default values.
04124 
04125   The attribute object is allocated and filled with the initial or factory default values built into LBM
04126   that are used by lbm_context_t objects.
04127 
04128   \param attr A pointer to a pointer to a UM context attribute structure. Will be
04129     filled in by this function to point to the newly created lbm_context_attr_t object.
04130   \return 0 for Success and -1 for Failure.
04131 */
04132 LBMExpDLL int lbm_context_attr_create_default(lbm_context_attr_t * * attr);
04133 
04134 /*! \brief Create and fill a UM context attribute object with the current default values for the given context name.
04135 
04136   The attribute object is allocated and filled with the current default values 
04137   that are used by lbm_context_t objects and may have been modified by a 
04138   previously loaded configuration file.
04139   Then, if an XML configuration file has been loaded, the attribute object is
04140   further filled with the defaults for the given context name. If the context
04141   name is not permitted by the XML configuration, -1 is returned and no
04142   attribute object is created.
04143 
04144   \param attr A pointer to a pointer to a UM context attribute structure. Will be
04145     filled in by this function to point to the newly created lbm_context_attr_t object.
04146   \param context_name The context name used to lookup this context in the XML 
04147     configuration. A NULL value is permitted, and will match unnamed contexts defined
04148         in the XML. The context name is also written into the attribute object.
04149   \return 0 for Success and -1 for Failure.
04150 */
04151 LBMExpDLL int lbm_context_attr_create_from_xml(lbm_context_attr_t * * attr, const char * context_name);
04152 
04153 /*! \brief Fill a UM context attribute object with the current default values for the given context name.
04154 
04155   The attribute object is filled with the default values for the given context
04156   name, if an XML configuration file has been loaded.
04157   If the context name is not permitted by the XML configuration, -1 is 
04158   returned and no values are set.
04159 
04160   \param attr A pointer to a UM context attribute structure. 
04161   \param context_name The context name used to lookup this context in the XML 
04162     configuration. A NULL value is permitted, and will match unnamed contexts 
04163         defined in the XML. The context name is also written into the attribute object.
04164   \return 0 for Success and -1 for Failure.
04165 */
04166 LBMExpDLL int lbm_context_attr_set_from_xml(lbm_context_attr_t * attr, const char * context_name);
04167 
04168 /*! \brief Delete a UM context attribute object.
04169 
04170   The attribute object is cleaned up and deleted.
04171 
04172   \param attr Pointer to a UM context attribute object as returned by ::lbm_context_attr_create.
04173   \return 0 for Success and -1 for Failure.
04174 */
04175 LBMExpDLL int lbm_context_attr_delete(lbm_context_attr_t *attr);
04176 
04177 /*! \brief Duplicate a UM context attribute object.
04178 
04179   A new attribute object is created as a copy of an existing object.
04180 
04181   \param attr A pointer to a pointer to a UM context attribute structure. Will be
04182     filled in by this function to point to the newly created lbm_context_attr_t object.
04183   \param original Pointer to a UM context attribute object as returned by ::lbm_context_attr_create
04184         or ::lbm_context_attr_create_default, from which \a attr is initialized.
04185   \return 0 for Success and -1 for Failure.
04186 */
04187 LBMExpDLL int lbm_context_attr_dup(lbm_context_attr_t * * attr, const lbm_context_attr_t * original);
04188 
04189 /*! \brief Set an option for the given UM context attribute.
04190 
04191            Used before the context is created.
04192            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
04193 
04194   \param attr Pointer to a UM context attribute object.
04195   \param optname String containing the option name.
04196   \param optval Pointer to the option value structure. The structure of the option values
04197                 are specific to the options themselves.
04198   \param optlen Length (in bytes) of the \a optval structure.
04199   \return 0 for Success and -1 for Failure.
04200 */
04201 LBMExpDLL int lbm_context_attr_setopt(lbm_context_attr_t *attr, const char *optname,
04202                                                                           const void *optval, size_t optlen);
04203 
04204 /*! \brief Set an option for the given UM context attribute using a string.
04205 
04206            Used before the context is created.
04207            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
04208 
04209   \param attr Pointer to a UM context attributed object.
04210   \param optname String containing the option name.
04211   \param optval String containing the option value. The format of the string is
04212                 specific to the option itself.
04213   \return 0 for Success and -1 for Failure.
04214 */
04215 LBMExpDLL int lbm_context_attr_str_setopt(lbm_context_attr_t *attr, const char *optname,
04216                                                                                   const char *optval);
04217 
04218 /*! \brief Retrieve the value of an option for the given UM context attribute.
04219 
04220   \param attr Pointer to a UM context attributed object.
04221   \param optname String containing the option name.
04222   \param optval Pointer to the option value structure to be filled.
04223                 The structure of the option values are specific to the options themselves.
04224   \param optlen Length (in bytes) of the \a optval structure when passed in. Upon return,
04225                 this is set to the size of the optval filled in structure.
04226   \return 0 for Success and -1 for Failure.
04227 */
04228 LBMExpDLL int lbm_context_attr_getopt(lbm_context_attr_t *attr, const char *optname,
04229                                                                           void *optval, size_t *optlen);
04230 
04231 /*! \brief Retrieve the textual value of an option for the given UM context attribute.
04232 
04233   \param attr Pointer to a UM context attributed object.
04234   \param optname String containing the option name.
04235   \param optval Pointer to the string to be filled in.
04236   \param optlen Maximum length (in bytes) of the \a string when passed in. Upon return,
04237                 this is set to the size of the formatted string.
04238   \return 0 for Success and -1 for Failure.
04239 */
04240 LBMExpDLL int lbm_context_attr_str_getopt(lbm_context_attr_t *attr, const char *optname,
04241                                                                                   char *optval, size_t *optlen);
04242 
04243 /*! \brief Create and initialize an lbm_context_t object.
04244 
04245   This creates an instance of the UM main processing element, a UM context.
04246   Sources and Receivers are created from a UM context and work within that
04247   context. For the Embedded operational mode, a thread is spawned to handle
04248   event processing.  For Sequential operational mode, the application
04249   "donates" an execution thread by calling lbm_context_process_events().
04250 
04251   \sa lbm_context_delete()
04252   \param ctxp A pointer to a pointer to a UM context object. Will be filled in
04253              by this function to point to the newly created lbm_context_t object.
04254   \param attr A pointer to a UM context attribute object. A value of NULL will
04255              use default attributes.
04256   \param proc A callback function to call when events occur on the UM daemon connection.
04257               NOTE: daemon mode is no longer available; this parameter is retained for
04258               for backward compatibility only.  Please pass NULL.
04259   \param clientd Client data to pass into the UM daemon event callback.
04260               NOTE: daemon mode is no longer available; this parameter is retained for
04261               for backward compatibility only.  Please pass NULL.
04262   \return 0 for Success and -1 for Failure.
04263  */
04264 LBMExpDLL int lbm_context_create(lbm_context_t **ctxp, const lbm_context_attr_t *attr,
04265                                                                  lbm_daemon_event_cb_proc proc, void *clientd);
04266 
04267 /*! \brief Create and initialize an lbm_context_t object suitable for FD and timers only.
04268 
04269   This creates an instance of the UM main processing element, a UM context.
04270   However, this version of the context is only usable for timer and file descriptor
04271   event handling. It can not be used for source or receiver creation, etc.
04272   For the Embedded operational mode, a thread is spawned to handle
04273   event processing.  For Sequential operational mode, the application
04274   "donates" an execution thread by calling lbm_context_process_events().
04275 
04276   \sa lbm_context_create
04277   \param ctxp A pointer to a pointer to a UM context object. Will be filled in
04278              by this function to point to the newly created lbm_context_t object.
04279   \param attr A pointer to a UM context attribute object. A value of NULL will
04280              use default attributes.
04281   \return 0 for Success and -1 for Failure.
04282  */
04283 LBMExpDLL int lbm_context_reactor_only_create(lbm_context_t **ctxp, const lbm_context_attr_t *attr);
04284 
04285 /*! \brief Delete a UM context object.
04286   \warning It is not safe to call this function from a context thread callback.
04287   \param ctx Pointer to a UM context object to delete.
04288   \return 0 for Success and -1 for Failure.
04289 */
04290 LBMExpDLL int lbm_context_delete(lbm_context_t *ctx);
04291 
04292 /*! \brief  Delete a UM context object with an application callback indicating when
04293   the context is fully deleted.  This extended version of the context delete
04294   function requires the configuration option
04295   queue_cancellation_callbacks_enabled be set to 1.
04296   \warning It is not safe to call this function from a context thread callback.
04297   \param ctx Pointer to a UM context object to delete.
04298   \param cbinfo Cancellation callback information, containing the event
04299                 queue, function pointer, and client data for the callback.
04300   \return 0 for Success and -1 for Failure
04301  */
04302 LBMExpDLL int lbm_context_delete_ex(lbm_context_t *ctx, lbm_event_queue_cancel_cb_info_t *cbinfo);
04303 
04304 /*! \brief  Request Topic Advertisements (sources), Topic Queries (receivers),
04305   and/or Wildcard Topic Queries (wildcard receivers) in the configured topic
04306   resolution address domain.
04307   Since Advertisements and Queries can become quiescent after a
04308   period defined by the Topic Resolution configuration attributes,
04309   this function will schedule Topic Resolution Requests at the given
04310   interval and duration. Contexts that receive these requests
04311   will respond with one advertisement per source and/or one
04312   query per receiver as appropriate. These requests
04313   will be ignored for topics that are not quiescent. Note that
04314   requests are only sent on the outgoing address and are only
04315   received on the incoming address. Responses to the request
04316   will similarly be sent only on the outgoing address.
04317   \param ctx Pointer to a UM context object.
04318   \param flags Flags indicating desired requests. ORed set of values.
04319   \arg \c LBM_TOPIC_RES_REQUEST_ADVERTISEMENT - Request advertisements from quiescent sources.
04320   \arg \c LBM_TOPIC_RES_REQUEST_QUERY - Request queries from quiescent receivers.
04321   \arg \c LBM_TOPIC_RES_REQUEST_WILDCARD_QUERY - Request queries from quiescent wildcard receivers.
04322   \arg \c LBM_TOPIC_RES_REQUEST_CONTEXT_ADVERTISEMENT - Request context advertisements from quiescent contexts.
04323   \arg \c LBM_TOPIC_RES_REQUEST_CONTEXT_QUERY - Request context queries from quiescent contexts.
04324   \arg \c LBM_TOPIC_RES_REQUEST_GW_REMOTE_INTEREST - Request remote interest from Gateways.
04325   \param interval_msec Interval between requests in milliseconds. Less than 10 should be used with
04326          caution. Less than 5 is not recommended.
04327   \param duration_sec Minimum duration of requests in seconds. Actual duration can be longer
04328          depending upon the interval. A value of zero will result in 1 request and the
04329          interval will be meaningless.
04330   \return 0 for Success and -1 for Failure
04331  */
04332 LBMExpDLL int lbm_context_topic_resolution_request(lbm_context_t *ctx, lbm_ushort_t flags, lbm_ulong_t interval_msec, lbm_ulong_t duration_sec);
04333 
04334 /*! \brief Set an option value within the given \a ctx.
04335 
04336            Only those options that can be set during operation may be specified.
04337            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
04338            in The UM Configuration Guide. For API functions that can access any option,
04339            see lbm_context_attr_*().
04340   \param ctx Pointer to a UM context object where the option is to be set.
04341   \param optname String containing the option name.
04342   \param optval Pointer to the option value structure. The structure of the option values
04343                 are specific to the options themselves.
04344   \param optlen Length (in bytes) of the \a optval structure.
04345   \return 0 for Success and -1 for Failure.
04346 */
04347 LBMExpDLL int lbm_context_setopt(lbm_context_t *ctx, const char *optname, const void *optval, size_t optlen);
04348 
04349 /*! \brief Set an option value within the given \a ctx.
04350 
04351            Only those options that can be set during operation may be specified.
04352            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
04353            in The UM Configuration Guide. For API functions that can access any option,
04354            see lbm_context_attr_*().
04355   \param ctx Pointer to a UM context object where the option is to be set.
04356   \param optname String containing the option name.
04357   \param optval String containing the option value. The format of the string
04358                 is specific to the options themselves.
04359   \return 0 for Success and -1 for Failure.
04360 */
04361 LBMExpDLL int lbm_context_str_setopt(lbm_context_t *ctx, const char *optname, const char *optval);
04362 
04363 /*! \brief Retrieve an option value within the given \a ctx.
04364 
04365   \param ctx Pointer to a UM context object where the option is stored.
04366   \param optname String containing the option name.
04367   \param optval Pointer to the option value structure. The structure of the option values
04368                 are specific to the options themselves.
04369   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
04370                 returned, this is the length of the filled in \a optval structure.
04371   \return 0 for Success and -1 for Failure.
04372 */
04373 LBMExpDLL int lbm_context_getopt(lbm_context_t *ctx, const char *optname, void *optval, size_t *optlen);
04374 
04375 /*! \brief Retrieve the textual option value within the given \a ctx.
04376 
04377   \param ctx Pointer to a UM context object where the option is stored.
04378   \param optname String containing the option name.
04379   \param optval String to hold the option value.
04380   \param optlen When passed, this is the max length (in bytes) of the string. When
04381                 returned, this is the length of the filled in option value.
04382   \return 0 for Success and -1 for Failure.
04383 */
04384 LBMExpDLL int lbm_context_str_getopt(lbm_context_t *ctx, const char *optname, char *optval, size_t *optlen);
04385 
04386 /*! \brief Set the callback procedure and delivery method for non-topic immediate messages.
04387   \param ctx Pointer to a UM context object that listens for messages.
04388   \param proc Pointer to a function to call when a message arrives.
04389   \param clientd Client data passed when a message is delivered.
04390   \param evq Optional Event Queue to place messages on when they arrive.
04391          If NULL causes \a proc to be called from context thread.
04392 */
04393 LBMExpDLL int lbm_context_rcv_immediate_msgs(lbm_context_t *ctx, lbm_immediate_msg_cb_proc proc, void *clientd,
04394                                                                                          lbm_event_queue_t *evq);
04395 
04396 /*! \brief Set the callback procedure and delivery method for immediate messages to a topic for which
04397                there is no receiver.
04398   \param ctx Pointer to a UM context object that listens for messages.
04399   \param proc Pointer to a function to call when a message arrives.
04400   \param clientd Client data passed when a message is delivered.
04401   \param evq Optional Event Queue to place messages on when they arrive.
04402          If NULL causes \a proc to be called from context thread.
04403 */
04404 LBMExpDLL int lbm_context_rcv_immediate_topic_msgs(lbm_context_t *ctx, lbm_immediate_msg_cb_proc proc, void *clientd,
04405                                                                                                         lbm_event_queue_t *evq);
04406 
04407 /*! \brief Set the name associated with a context.
04408   \param ctx Pointer to an existing UM context object.
04409   \param name The context name.  Context names are limited in length to 128 characters
04410          (not including the final null) and restricted to alphanumeric characters, 
04411          hyphens, and underscores.
04412 */
04413 LBMExpDLL int lbm_context_set_name(lbm_context_t *ctx, const char *name);
04414 
04415 /*! \brief Get the name associated with a context.
04416   \param ctx Pointer to an existing UM context object.
04417   \param name Pointer to a buffer into which is stored the context name.
04418   \param size Pointer to a variable holding the size of the buffer. If the buffer is not large enough,
04419               this will be filled in with the required size.
04420 */
04421 LBMExpDLL int lbm_context_get_name(lbm_context_t *ctx, char *name, size_t *size);
04422 
04423 /*! \brief Initialize the UM license from the contents of a disk file.
04424   This function will only be effective if it is called before any other
04425   UM API function.
04426   \param licfile String containing the name of a file that contains the UM license.
04427   This string is the same as that which would otherwise be specified as the
04428   value of the LBM_LICENSE_FILENAME environmental variable.
04429   \return 0 for Success and -1 for Failure
04430 */
04431 LBMExpDLL int lbm_license_file(const char *licfile);
04432 
04433 /*! \brief Initialize the UM license from a string.
04434   This function will only be effective if it is called before any other
04435   UM API function.
04436   \param licstr String containing the UM license.
04437   This string is the same as that which would otherwise be specified as the
04438   value of the LBM_LICENSE_INFO environmental variable.
04439   \return 0 for Success and -1 for Failure
04440 */
04441 LBMExpDLL int lbm_license_str(const char *licstr);
04442 
04443 /*! \brief Determine is the MnM product is licensed
04444 
04445           For internal use only.
04446         This function tests whether or not MnM is licensed for use.
04447 
04448     \return 0 for Success and -1 for Failure
04449  */
04450 LBMExpDLL int lbm_license_ummnm_valid();
04451 
04452 /*! \brief Determine is the VDS product is licensed
04453 
04454           For internal use only.
04455         This function tests whether or not VDS is licensed for use.
04456 
04457     \return 0 for Success and -1 for Failure
04458  */
04459 LBMExpDLL int lbm_license_vds_valid();
04460 
04461 /*! \brief Set one or more options from the contents of a disk file.
04462   This function will only be effective if it is called before any other
04463   UM API function.
04464   \param fname String containing the file name or URL (tftp or http) that
04465                   contains the options to parse and set. File names with a ".xml"
04466                   extension will be passed to lbm_config_xml_file() with a NULL
04467                   application name.
04468   \return 0 for Success and -1 for Failure.
04469 */
04470 LBMExpDLL int lbm_config(const char *fname);
04471 
04472 /*! \brief Load a UM XML configuration file.
04473   
04474   Parse the xml configuration file specified by url, and apply the
04475   configuration for the given application name. 
04476   UM XML configuration may only be loaded once in the lifetime of a process. If
04477   the LBM_UMM_INFO or LBM_XML_CONFIG_FILENAME environment variables are set and
04478   they are successful in setting UM XML configuration, this API will have no effect
04479   and return -1.
04480   \param url String containing the path to the XML configuration file.  A URL
04481     beginning with http:// or ftp:// may also be provided.
04482   \param application_name The name of this application which must match an
04483     application tag in the XML configuration file. This parameter may be NULL,
04484         in which case the application tag with no name is matched.
04485   \return 0 for Success and -1 for Failure.
04486 */
04487 LBMExpDLL int lbm_config_xml_file(const char *url, const char *application_name);
04488 
04489 /*! \brief Load UM XML configuration data.
04490   
04491   Parse the xml configuration data contained in xml_data, and apply the
04492   configuration for the given application name. 
04493   UM XML configuration may only be loaded once in the lifetime of a process. If
04494   the LBM_UMM_INFO or LBM_XML_CONFIG_FILENAME environment variables are set and
04495   they are successful in setting UM XML configuration, this API will have no effect
04496   and return -1.
04497   \param xml_data String containing UM XML configuration data.
04498   \param application_name The name of this application which must match an
04499     application tag in the XML configuration data. This parameter may be NULL,
04500         in which case the application tag with no name is matched.
04501   \return 0 for Success and -1 for Failure.
04502 */
04503 LBMExpDLL int lbm_config_xml_string(const char *xml_data, const char *application_name);
04504 
04505 /*! \brief Set a callback function to be called for UM log messages (warnings, notices,
04506   etc.).
04507   \param proc Function to call when a log message is generated.
04508   \param clientd Client data to pass when a log message is generated.
04509   \return 0 on Success and -1 for Failure
04510 */
04511 LBMExpDLL int lbm_log(lbm_log_cb_proc proc, void *clientd);
04512 
04513 /*!     \brief Log a message.
04514                 This is an entry to the UM logging mechanism.
04515         \param level Message log level (see LBM_LOG_*).
04516         \param format \c printf style format string, followed by zero or more
04517                 arguments.
04518 */
04519 LBMExpDLL void lbm_logf(int level, const char * format, ...);
04520 
04521 /*! \brief Return an ASCII string containing the error message last encountered
04522            by this thread.
04523         \return Pointer to a static char array holding the error message.
04524  */
04525 LBMExpDLL const char *lbm_errmsg(void);
04526 
04527 /*! \brief Return the error number last encountered by this thread.
04528         \return Integer error number.
04529 */
04530 LBMExpDLL int lbm_errnum(void);
04531 
04532 #if defined(_WIN32) || defined(DOXYGEN)
04533 /*! \brief Instructs UM that a new thread will be calling UM functions.
04534 
04535           For internal use only. 
04536         This function sets up UM Thread Local Storage used for handling error
04537         information on a per thread basis. This function only needs to be
04538         called when using the static version of the UM library on Windows.
04539 
04540     \return 0 for Success and -1 for Failure
04541  */
04542 LBMExpDLL int lbm_win32_static_thread_attach(void);
04543 
04544 /*! \brief Instructs UM that a new thread is done calling UM functions.
04545 
04546           For internal use only. 
04547           This function frees up UM Thread Local Storage used for handling error
04548         information on a per thread basis. This function only needs to be
04549         called when using the static version of the UM library on Windows.
04550 
04551     \return 0 for Success and -1 for Failure
04552  */
04553 LBMExpDLL int lbm_win32_static_thread_detach(void);
04554 #endif /* _WIN32 */
04555 
04556 /*! \brief Schedule a timer that calls \a proc when it expires.
04557 
04558   This schedules a timer that will call the function \a proc at
04559   a later time passing in specified data.  This is a one-shot timer.
04560   To implement a recurring timer, the callback function should
04561   call lbm_schedule_timer() again.
04562 
04563   A zero duration timer is legal and causes the associated callback to be
04564   called as soon as possible on the context thread or to be enqueued as an
04565   event on the associated event queue. In this case, the event queue
04566   dispatching thread calls the associated callback after all currently
04567   pending events have been dispatched.
04568 
04569   \sa lbm_cancel_timer
04570   \param ctx Pointer to the UM context object
04571   \param proc Pointer to the function to call when the timer expires.
04572   \param clientd Pointer to client data that is passed when the timer expires.
04573   \param evq Optional Event Queue to place timer events on when they occur.
04574          If NULL causes \a proc to be called from context thread.
04575   \param delay Delay until \a proc should be called (in milliseconds).
04576   \return An identifier for the timer that may be used to cancel it or -1 for Failure.
04577  */
04578 LBMExpDLL int lbm_schedule_timer(lbm_context_t *ctx,
04579                                                                  lbm_timer_cb_proc proc, void *clientd,
04580                                                                  lbm_event_queue_t *evq, lbm_ulong_t delay);
04581 
04582 /*! \brief Schedule a recurring timer that calls \a proc when it expires.
04583 
04584   This schedules a recurring timer that calls the function \a proc at
04585   the given time interval passing in the specified data. The timer
04586   will reschedule itself each time it expires and must be explicitly
04587   canceled to stop the timer. Caution should be exercised with the
04588   delay since timer events will build up if the application can not
04589   process the events fast enough.
04590 
04591   \sa lbm_cancel_timer
04592   \param ctx Pointer to the UM context object
04593   \param proc Pointer to the function to call when the timer expires.
04594   \param clientd Pointer to client data that is passed when the timer expires.
04595   \param evq Optional Event Queue to place timer events on when they occur.
04596          If NULL causes \a proc to be called from context thread.
04597   \param delay Delay until \a proc should be called (in milliseconds).
04598   \return An identifier for the timer that may be used to cancel it or -1 for Failure.
04599  */
04600 LBMExpDLL int lbm_schedule_timer_recurring(lbm_context_t *ctx,
04601                                                                  lbm_timer_cb_proc proc, void *clientd,
04602                                                                  lbm_event_queue_t *evq, lbm_ulong_t delay);
04603 
04604 /*! \brief Cancel a previously scheduled timer identified by \a id.
04605 
04606   Cancel a previously scheduled timer.  The timer is identified by
04607   the return value of the lbm_schedule_timer() function.  If the passed-in 
04608   timer ID is not valid, this cancel function returns success, which occurs 
04609   if the passed-in timer ID has already fired or if the timer ID is garbage.
04610   Note that there are rare circumstances where this function can return 
04611   while the timer callback may still be executing.  If the application needs 
04612   to know when all possible processing on the timer is complete, it must use
04613   lbm_cancel_timer_ex().
04614 
04615   \sa lbm_schedule_timer
04616   \param ctx Pointer to the UM context object.
04617   \param id The identifier specifying the timer to cancel
04618   \param clientdp Pointer to a client data pointer.  This function sets it to
04619                   the client data pointer supplied by the lbm_schedule_timer().
04620                   If the caller does not need the client data, it can pass
04621                   NULL as \a clientdp.
04622   \return 0 for Success and -1 for Failure.
04623 */
04624 LBMExpDLL int lbm_cancel_timer(lbm_context_t *ctx, int id, void **clientdp);
04625 
04626 /*! \brief Extended cancel a previously scheduled timer identified by \a id.
04627 
04628   Cancel a previously scheduled timer, with an application callback
04629   indicating when the timer is fully canceled.  The timer is identified by
04630   the return value of the lbm_schedule_timer() function.  If the passed-in 
04631   timer ID is not valid, this cancel function returns success, which occurs 
04632   if the passed-in timer ID has already fired or if the timer ID is garbage. 
04633   This extended version of the timer cancel function requires the configuration 
04634   option queue_cancellation_callbacks_enabled be set to 1.
04635 
04636   \sa lbm_schedule_timer
04637   \param ctx Pointer to the UM context object.
04638   \param id The identifier specifying the timer to cancel
04639   \param clientdp Pointer to a client data pointer.  This function sets it to
04640                   the client data pointer supplied by the lbm_schedule_timer().
04641                   If the caller does not need the client data, it can pass
04642                   NULL as \a clientdp.
04643   \param cbinfo Cancellation callback information, containing the event
04644                 queue, function pointer, and client data for the callback.
04645   \return 0 for Success and -1 for Failure.
04646 */
04647 LBMExpDLL int lbm_cancel_timer_ex(lbm_context_t *ctx, int id, void **clientdp,
04648                                                                    lbm_event_queue_cancel_cb_info_t *cbinfo);
04649 
04650 /*! \brief Process internal events in the given UM context object.
04651 
04652   When opmode is set to LBM_CTX_ATTR_OP_SEQUENTIAL (or "sequential"), then
04653   it is the responsibility of the application to explicitly process
04654   events for the UM context. This function will process timers and
04655   file descriptor/socket events for internal processing as well as
04656   API timer and file descriptor/socket events. The application thread
04657   that is processing events must remain active until the context is deleted.
04658 
04659   \warning It is not safe to call this function from a context thread callback.
04660   \param ctx Pointer to the UM context object.
04661   \param msec Continue event processing loop for at least \a msec milliseconds before returning.
04662   \return 0 for Success and -1 for Failure. For -1, which is returned for critical
04663   errors, check the resultant lbm_errnum and error message.
04664   \note It is the responsibility of the application to "unblock" this function
04665   using lbm_context_unblock() and cease further calls before deleting
04666   the UM context.
04667 */
04668 LBMExpDLL int lbm_context_process_events(lbm_context_t *ctx, lbm_ulong_t msec);
04669 
04670 /*! \brief Unblock a sequential mode UM context 
04671 
04672   When opmode is set to LBM_CTX_ATTR_OP_SEQUENTIAL (or "sequential"), then
04673   it is the responsibility of the application to explicitly process
04674   events for the UM context. This function allows an application
04675   to cause lbm_context_process_events() to immediately return instead of
04676   continuing to process events.
04677   \param ctx Pointer to the UM context object.
04678 */
04679 LBMExpDLL int lbm_context_unblock(lbm_context_t *ctx);
04680 
04681 /*! \brief Process LBT-IPC messages received.
04682  
04683   When transport_lbtipc_receiver_operational_mode is set to
04684   LBM_CTX_ATTR_OP_SEQUENTIAL (or "sequential"), then it is the responsibility
04685   of the application to explicitly process LBT-IPC messages for the UM context.
04686   This function will satisfy that requirement.
04687 
04688   \warning It is not safe to call this function from a context thread callback.
04689   \param ctx Pointer to the UM context object.
04690   \param msec Only used if transport_lbtipc_receiver_thread_behavior is set to "pend".
04691          The timeout in milliseconds of the pend waiting for new data (actual Operating
04692          System resolution may vary).  Defaults to no timeout on Operating Systems that
04693          do not support a timeout (e.g. Mac OS X).  A value of zero will result
04694          in "busy_wait" like behavior on all Operating Systems.
04695   \param loop_count Number of loops before returning whether or not data has been received. Zero
04696          results in looping forever.
04697   \return 0 for Success and -1 for Failure.
04698   \note It is the responsibility of the application to "unblock" this function
04699   using lbm_context_lbtipc_unblock() and cease further calls before deleting
04700   the UM context.
04701 */
04702 LBMExpDLL int lbm_context_process_lbtipc_messages(lbm_context_t *ctx, lbm_ulong_t msec, lbm_ulong_t loop_count);
04703 
04704 /*! \brief Unblock a sequential mode LBT-IPC processing loop.
04705 
04706   When transport_lbtipc_receiver_operational_mode is set to
04707   LBM_CTX_ATTR_OP_SEQUENTIAL (or "sequential"), then it is the responsibility
04708   of the application to explicitly process LBT-IPC messages for the UM context.
04709   This function allows an application to cause lbm_context_process_lbtipc_messages() to
04710   immediately return instead of continuing to process messages. 
04711 
04712   \param ctx Pointer to the UM context object.
04713 */
04714 LBMExpDLL int lbm_context_lbtipc_unblock(lbm_context_t *ctx);
04715 
04716 /*! \brief Register a file descriptor/socket for events that calls \a proc when a given event occurs.
04717 
04718   This registers a file descriptor/socket event that will call the function \a proc at
04719   a later time passing in specified data when the event occurs.
04720   NOTE: this functionality is not available for Windows-based contexts
04721   where completion ports are specified.  See configuration option
04722   "context fd_management_type".
04723 
04724   \sa lbm_cancel_fd
04725   \warning It is not recommended to call this function from a context thread callback.
04726   \param ctx Pointer to the UM context object
04727   \param handle file descriptor/socket of interest for event.
04728   \param proc Pointer to the function to call when the event occurs
04729   \param clientd Pointer to client data that is passed when the event occurs.
04730   \param evq Optional Event Queue to place events on when they occur.
04731          If NULL causes \a proc to be called from context thread.
04732   \param ev One or more of LBM_FD_EVENT_* (ORed to together).
04733          Mask of events of interest.
04734   \return 0 for Success and -1 for Failure.
04735  */
04736 LBMExpDLL int lbm_register_fd(lbm_context_t *ctx, lbm_handle_t handle, lbm_fd_cb_proc proc,
04737                                                           void *clientd, lbm_event_queue_t *evq, lbm_ulong_t ev);
04738 
04739 /*! \brief Cancel a previously registered file descriptor/socket event.
04740 
04741   Cancel a previously registered file descriptor/socket event.  Note
04742   that there are rare circumstances where this function can return while the
04743   fd callback may still be executing.  If the application needs to know when
04744   all possible processing on the fd is complete, it must use
04745   lbm_cancel_fd_ex().
04746 
04747   \sa lbm_register_fd
04748   \warning It is not recommended to call this function from a context thread callback.
04749   \param ctx Pointer to the UM context object.
04750   \param handle file descriptor/socket of interest for event.
04751   \param ev One or more of LBM_FD_EVENT_* (ORed to together).
04752          Mask of events to cancel.
04753   \return 0 for Success and -1 for Failure.
04754 */
04755 LBMExpDLL int lbm_cancel_fd(lbm_context_t *ctx, lbm_handle_t handle, lbm_ulong_t ev);
04756 
04757 /*! \brief Extended cancel a previously registered file descriptor/socket event.
04758 
04759   Cancel a previously registered file descriptor/socket event, with
04760   an application callback indicating when the fd is fully canceled.
04761   This extended version of the fd cancel function requires the configuration
04762   option queue_cancellation_callbacks_enabled be set to 1.
04763 
04764   \sa lbm_register_fd
04765   \param ctx Pointer to the UM context object.
04766   \param handle file descriptor/socket of interest for event.
04767   \param ev Mask of events to cancel.
04768   \param cbinfo Cancellation callback information, containing the event
04769                 queue, function pointer, and client data for the callback.
04770   \return 0 for Success and -1 for Failure.
04771 */
04772 LBMExpDLL int lbm_cancel_fd_ex(lbm_context_t *ctx, lbm_handle_t handle, lbm_ulong_t ev,
04773                                                            lbm_event_queue_cancel_cb_info_t *cbinfo);
04774 
04775 /*! \brief Retrieves all source topic attribute options.
04776 
04777         The config object is filled with source topic configuration options
04778         \param src The source object to retrieve the attributes from
04779         \param size Size of the opts array. Will return the number of items that were set in opts
04780         \param opts The options array to fill
04781         */
04782 LBMExpDLL int lbm_src_topic_dump(lbm_src_t *src, int *size, lbm_config_option_t *opts);
04783 
04784 /*! \brief Retrieves all source topic attribute options.
04785 
04786         The config object is filled with source topic configuration options
04787         \param src The source topic attribute object to retrieve the attributes from
04788         \param size Size of the opts array. Will return the number of items that were set in opts
04789         \param opts The options array to fill
04790         */
04791 LBMExpDLL int lbm_src_topic_attr_dump(lbm_src_topic_attr_t *sattr, int *size, lbm_config_option_t *opts);
04792 
04793 /*! \brief Retrieves the number of options that are of type "topic"
04794 
04795         The function returns the number of entries that are of type "topic"
04796 
04797         \return The number of entries that are of type "topic"
04798 */
04799 LBMExpDLL int lbm_src_topic_attr_option_size();
04800 
04801 /*! \brief Turn a Topic string into a UM topic object usable by sources.
04802   \warning It is not safe to call this function from a context thread callback.
04803   \param topicp A pointer to a pointer to a UM topic object. Will be filled in
04804                 by this function to point to the newly created lbm_topic_t object.
04805   \param ctx Context object for Topic
04806   \param symbol The Topic string.  Topic strings should be limited in length
04807                 to 246 characters (not including the final null).
04808   \param attr Pointer to a Src Topic attribute object for passing in options
04809   \return 0 for Success and -1 for Failure.
04810 */
04811 LBMExpDLL int lbm_src_topic_alloc(lbm_topic_t **topicp, lbm_context_t *ctx,
04812                                                                   const char *symbol, const lbm_src_topic_attr_t *attr);
04813 
04814 /*! \brief Create and fill a UM source topic attribute object with the current default values.
04815 
04816   The attribute object is filled with the current default values that are
04817   used by lbm_topic_t objects that concern sources and may have been modified by 
04818   a previously loaded configuration file.
04819 
04820   \param attr A pointer to a pointer to a UM source topic attribute structure. Will be
04821     filled in by this function to point to the newly created lbm_src_topic_attr_t object.
04822   \return 0 for Success and -1 for Failure.
04823 */
04824 LBMExpDLL int lbm_src_topic_attr_create(lbm_src_topic_attr_t * * attr);
04825 
04826 /*! \brief Create and fill a UM source topic attribute object with the initial default values.
04827 
04828   The attribute object is allocated and filled with the initial or factory default values built into LBM
04829   that are used by lbm_topic_t objects that concern sources.
04830 
04831   \param attr A pointer to a pointer to a UM source topic attribute structure. Will be
04832     filled in by this function to point to the newly created lbm_src_topic_attr_t object.
04833   \return 0 for Success and -1 for Failure.
04834 */
04835 LBMExpDLL int lbm_src_topic_attr_create_default(lbm_src_topic_attr_t * * attr);
04836 
04837 /*! \brief Create and fill a UM source topic attribute object with the current default values for the given topic name.
04838 
04839   The attribute object is allocated and filled with the current default values that are
04840   used by lbm_topic_t objects that concern sources and may have been modified by 
04841   a previously loaded configuration file.
04842   If an XML configuration file has been loaded, the attribute object is
04843   further filled with the defaults for the given context name and source topic
04844   name. If the context name or source topic name are not permitted by the XML 
04845   configuration, -1 is returned and no attribute object is created.
04846 
04847   \param attr A pointer to a pointer to a UM source topic attribute structure. Will be
04848     filled in by this function to point to the newly created lbm_src_topic_attr_t object.
04849   \param context_name The context name used to lookup the source topic in the XML 
04850     configuration. A NULL value is permitted, and will match unnamed contexts defined
04851         in the XML.
04852   \param topicname The topic name used to lookup the source topic in the XML
04853     configuration. A NULL value is *not* permitted and will result in an error.
04854   \return 0 for Success and -1 for Failure.
04855 */
04856 LBMExpDLL int lbm_src_topic_attr_create_from_xml(lbm_src_topic_attr_t * * attr, const char * context_name, const char * topicname);
04857 
04858 /*! \brief Fill a UM source topic attribute object with the current default values for the given topic name.
04859 
04860   The attribute object is filled with the defaults for the given context name 
04861   and source topic name, if an XML configuration file has been loaded. If the 
04862   context name or source topic name are not permitted by the XML 
04863   configuration, -1 is returned and the attribute object is not written to.
04864 
04865   \param attr A pointer to a UM source topic attribute structure. 
04866   \param context_name The context name used to lookup the source topic in the XML 
04867     configuration. A NULL value is permitted, and will match unnamed contexts defined
04868         in the XML.
04869   \param topicname The topic name used to lookup the source topic in the XML
04870     configuration. A NULL value is *not* permitted and will result in an error.
04871   \return 0 for Success and -1 for Failure.
04872 */
04873 LBMExpDLL int lbm_src_topic_attr_set_from_xml(lbm_src_topic_attr_t * attr, const char * context_name, const char * topicname);
04874 
04875 /*! \brief Delete a source topic attribute object.
04876 
04877   The attribute object is cleaned up and deleted.
04878 
04879   \param attr Pointer to a UM source topic attribute object as returned by ::lbm_src_topic_attr_create.
04880   \return 0 for Success and -1 for Failure.
04881 */
04882 LBMExpDLL int lbm_src_topic_attr_delete(lbm_src_topic_attr_t *attr);
04883 
04884 /*! \brief Duplicate a UM source topic attribute object.
04885 
04886   A new attribute object is created as a copy of an existing object.
04887 
04888   \param attr A pointer to a pointer to a UM source topic attribute structure. Will be
04889     filled in by this function to point to the newly created lbm_src_topic_attr_t object.
04890   \param original Pointer to a UM source topic attribute object as returned by
04891     ::lbm_src_topic_attr_create or ::lbm_src_topic_attr_create_default, from which \a attr is initialized.
04892   \return 0 for Success and -1 for Failure.
04893 */
04894 LBMExpDLL int lbm_src_topic_attr_dup(lbm_src_topic_attr_t * * attr, const lbm_src_topic_attr_t * original);
04895 
04896 /*! \brief Set an option value within the given source topic attribute.
04897 
04898            Used before the topic is allocated and the source created.
04899            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
04900 
04901   \param attr Pointer to a UM source topic attribute object where the option is to be set
04902   \param optname String containing the option name
04903   \param optval Pointer to the option value structure. The structure of the option values
04904                 are specific to the options themselves.
04905   \param optlen Length (in bytes) of the \a optval structure.
04906   \return 0 for Success and -1 for Failure.
04907 */
04908 LBMExpDLL int lbm_src_topic_attr_setopt(lbm_src_topic_attr_t *attr, const char *optname,
04909                                                                                 const void *optval, size_t optlen);
04910 
04911 /*! \brief Set an option value within the given source topic attribute.
04912 
04913            Used before the topic is allocated and the source created.
04914            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
04915 
04916   \param attr Pointer to a UM source topic attribute object where the option is to be set
04917   \param optname String containing the option name
04918   \param optval String containing the option value. The format of the string
04919                 is specific to the options themselves.
04920   \return 0 for Success and -1 for Failure.
04921 */
04922 LBMExpDLL int lbm_src_topic_attr_str_setopt(lbm_src_topic_attr_t *attr, const char *optname,
04923                                                                                         const char *optval);
04924 
04925 /*! \brief Retrieve an option value within the given source topic attribute.
04926   \param attr Pointer to a UM source topic attribute object where the option is stored
04927   \param optname String containing the option name
04928   \param optval Pointer to the option value structure. The structure of the option values
04929                 are specific to the options themselves.
04930   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
04931                 returned, this is the length of the filled in \a optval structure.
04932   \return 0 for Success and -1 for Failure.
04933 */
04934 LBMExpDLL int lbm_src_topic_attr_getopt(lbm_src_topic_attr_t *attr, const char *optname,
04935                                                                                 void *optval, size_t *optlen);
04936 
04937 /*! \brief Retrieve a textual option value within the given source topic attribute.
04938   \param attr Pointer to a UM source topic attribute object where the option is stored
04939   \param optname String containing the option name
04940   \param optval String to be filled in with the option value.
04941   \param optlen When passed, this is the max length (in bytes) of the string. When
04942                 returned, this is the length of the filled in option value.
04943   \return 0 for Success and -1 for Failure.
04944 */
04945 LBMExpDLL int lbm_src_topic_attr_str_getopt(lbm_src_topic_attr_t *attr, const char *optname,
04946                                                                                         char *optval, size_t *optlen);
04947 
04948 /*! \brief Turn a Topic string into a UM topic object usable by receivers.
04949   \warning It is not safe to call this function from a context thread callback.
04950   \param topicp A pointer to a pointer to a UM topic object. Will be filled in
04951                by this function to point to an lbm_topic_t object.
04952 
04953                NOTE: Topic objects are cached. If a previously created topic
04954                object is found, it will be returned instead of a new object.
04955   \param ctx Context object for topic
04956   \param symbol The topic string.  Topic strings should be limited in length
04957                 to 246 characters (not including the final null).
04958   \param attr Pointer to a receiver topic attributes object for passing in options
04959   \note       Setting attributes is only possible when a topic object is first
04960               created. This parameter will be ignored on subsequent lookups.
04961   \return 0 for Success and -1 for Failure.
04962  */
04963 LBMExpDLL int lbm_rcv_topic_lookup(lbm_topic_t **topicp, lbm_context_t *ctx,
04964                                                                    const char *symbol, const lbm_rcv_topic_attr_t *attr);
04965 
04966 /*! \brief Retrieves all receiver topic attribute options.
04967 
04968         The config object is filled with source topic configuration options
04969         \param rcv The receiver object to retrieve the attributes from
04970         \param size Size of the opts array. Will return the number of items that were set in opts
04971         \param opts The options array to fill
04972         */
04973 LBMExpDLL int lbm_rcv_topic_dump(lbm_rcv_t *rcv, int *size, lbm_config_option_t *opts);
04974 
04975 /*! \brief Retrieves all receiver topic attribute options.
04976 
04977         The config object is filled with source topic configuration options
04978         \param rcv The receiver topic attribute object to retrieve the attributes from
04979         \param size Size of the opts array. Will return the number of items that were set in opts
04980         \param opts The options array to fill
04981         */
04982 LBMExpDLL int lbm_rcv_topic_attr_dump(lbm_rcv_topic_attr_t *rattr, int *size, lbm_config_option_t *opts);
04983 
04984 /*! \brief Retrieves the number of options that are of type "source topic"
04985 
04986         The function returns the number of entries that are of type "source topic"
04987 
04988         \return The number of entries that are of type "source topic"
04989 */
04990 LBMExpDLL int lbm_rcv_topic_attr_option_size();
04991 
04992 /*! \brief Create and fill a UM receiver topic attribute object with the current default values.
04993 
04994   The attribute object is allocated and filled with the current default values that are
04995   used by lbm_topic_t objects that concern receivers and may have been modified by 
04996   a previously loaded configuration file.
04997 
04998   \param attr A pointer to a pointer to a UM receiver topic attribute structure. Will be
04999     filled in by this function to point to the newly created lbm_rcv_topic_attr_t object.
05000   \return 0 for Success and -1 for Failure.
05001 */
05002 LBMExpDLL int lbm_rcv_topic_attr_create(lbm_rcv_topic_attr_t * * attr);
05003 
05004 /*! \brief Create and fill a UM receiver topic attribute object with the initial default values.
05005 
05006   The attribute object is allocated and filled with the initial or factory default values built into LBM
05007   that are used by lbm_topic_t objects that concern receivers.
05008 
05009   \param attr A pointer to a pointer to a UM receiver topic attribute structure. Will be
05010     filled in by this function to point to the newly created lbm_rcv_topic_attr_t object.
05011   \return 0 for Success and -1 for Failure.
05012 */
05013 LBMExpDLL int lbm_rcv_topic_attr_create_default(lbm_rcv_topic_attr_t * * attr);
05014 
05015 /*! \brief Create and fill a UM receiver topic attribute object with the current default values for the given topic name.
05016 
05017   The attribute object is allocated and filled with the current default values that are
05018   used by lbm_topic_t objects that concern receivers and may have been modified by 
05019   a previously loaded configuration file.
05020   If an XML configuration file has been loaded, the attribute object is
05021   further filled with the defaults for the given context name and receiver topic
05022   name. If the context name or receiver topic name are not permitted by the XML 
05023   configuration, -1 is returned and no attribute object is created.
05024 
05025   \param attr A pointer to a pointer to a UM receiver topic attribute structure. Will be
05026     filled in by this function to point to the newly created lbm_rcv_topic_attr_t object.
05027   \param context_name The context name used to lookup the receiver topic in the XML 
05028     configuration. A NULL value is permitted, and will match unnamed contexts defined
05029         in the XML.
05030   \param topicname The topic name used to lookup the receiver topic in the XML
05031     configuration. A NULL value is *not* permitted and will result in an error.
05032   \return 0 for Success and -1 for Failure.
05033 */
05034 LBMExpDLL int lbm_rcv_topic_attr_create_from_xml(lbm_rcv_topic_attr_t * * attr, const char * context_name, const char * topicname);
05035 
05036 /*! \brief Fill a UM receiver topic attribute object with the current default values for the given topic name.
05037 
05038   The attribute object is filled with the defaults for the given context name 
05039   and receiver topic name, if an XML configuration file has been loaded. If the 
05040   context name or receiver topic name are not permitted by the XML 
05041   configuration, -1 is returned and the attribute object is not written to.
05042 
05043   \param attr A pointer to a UM receiver topic attribute structure. 
05044   \param context_name The context name used to lookup the receiver topic in the XML 
05045     configuration. A NULL value is permitted, and will match unnamed contexts defined
05046         in the XML.
05047   \param topicname The topic name used to lookup the receiver topic in the XML
05048     configuration. A NULL value is *not* permitted and will result in an error.
05049   \return 0 for Success and -1 for Failure.
05050 */
05051 LBMExpDLL int lbm_rcv_topic_attr_set_from_xml(lbm_rcv_topic_attr_t * attr, const char * context_name, const char * topicname);
05052 
05053 /*! \brief Delete a receiver topic attribute object.
05054 
05055   The attribute object is cleaned up and deleted.
05056 
05057   \param attr Pointer to a UM source topic attribute object as returned by ::lbm_rcv_topic_attr_create.
05058   \return 0 for Success and -1 for Failure.
05059 */
05060 LBMExpDLL int lbm_rcv_topic_attr_delete(lbm_rcv_topic_attr_t *attr);
05061 
05062 /*! \brief Duplicate a UM receiver topic attribute object.
05063 
05064   A new attribute object is created as a copy of an existing object.
05065 
05066   \param attr A pointer to a pointer to a UM receiver topic attribute structure. Will be
05067     filled in by this function to point to the newly created lbm_rcv_topic_attr_t object.
05068   \param original Pointer to a UM receiver topic attribute object as returned by
05069     ::lbm_rcv_topic_attr_create or ::lbm_rcv_topic_attr_create_default, from which \a attr is initialized.
05070 */
05071 LBMExpDLL int lbm_rcv_topic_attr_dup(lbm_rcv_topic_attr_t * * attr, const lbm_rcv_topic_attr_t * original);
05072 
05073 /*! \brief Set an option value within the given receiver topic attribute.
05074 
05075            Used before the topic is looked up and the receiver created.
05076            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
05077 
05078   \param attr Pointer to a UM receiver topic attribute object where the option is to be set.
05079   \param optname String containing the option name.
05080   \param optval Pointer to the option value structure. The structure of the option values
05081                 are specific to the options themselves.
05082   \param optlen Length (in bytes) of the \a optval structure.
05083   \return 0 for Success and -1 for Failure.
05084 */
05085 LBMExpDLL int lbm_rcv_topic_attr_setopt(lbm_rcv_topic_attr_t *attr, const char *optname,
05086                                                                                 const void *optval, size_t optlen);
05087 
05088 /*! \brief Set an option value within the given receiver topic attribute.
05089 
05090            Used before the topic is looked up and the receiver created.
05091            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
05092 
05093   \param attr Pointer to a UM receiver topic attribute object where the option is to be set.
05094   \param optname String containing the option name.
05095   \param optval String containing the option value. The format of the string
05096                 is specific to the options themselves.
05097   \return 0 for Success and -1 for Failure.
05098 */
05099 LBMExpDLL int lbm_rcv_topic_attr_str_setopt(lbm_rcv_topic_attr_t *attr, const char *optname,
05100                                                                                         const char *optval);
05101 
05102 /*! \brief Retrieve an option value within the given receiver topic attribute.
05103 
05104   \param attr Pointer to a UM receiver topic attribute object where the option is stored
05105   \param optname String containing the option name
05106   \param optval Pointer to the option value structure. The structure of the option values
05107                 are specific to the options themselves.
05108   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
05109                 returned, this is the length of the filled in \a optval structure.
05110   \return 0 for Success and -1 for Failure.
05111 */
05112 LBMExpDLL int lbm_rcv_topic_attr_getopt(lbm_rcv_topic_attr_t *attr, const char *optname,
05113                                                                                 void *optval, size_t *optlen);
05114 
05115 /*! \brief Retrieve a textual option value within the given receiver topic attribute.
05116 
05117   \param attr Pointer to a UM receiver topic attribute object where the option is stored
05118   \param optname String containing the option name
05119   \param optval String to be filled in with the option value.
05120   \param optlen When passed, this is the max length (in bytes) of the string. When
05121                 returned, this is the length of the filled in option value.
05122   \return 0 for Success and -1 for Failure.
05123 */
05124 LBMExpDLL int lbm_rcv_topic_attr_str_getopt(lbm_rcv_topic_attr_t *attr, const char *optname,
05125                                                                                         char *optval, size_t *optlen);
05126 
05127 /*! \brief Create a channel info object to send messages with the given \a channel_num.
05128 
05129   \param chnp A pointer to a pointer to a UM channel info object.  Will be filled in
05130                by this function to point to the newly created lbm_src_channel_info_t object.
05131   \param src Pointer to the UM source the channel info object will be used with.
05132   \param channel_num A channel number in the range 0-4294967295 
05133   \sa lbm_src_send_ex lbm_src_sendv_ex
05134   \return 0 for Success and -1 for Failure
05135  */
05136 LBMExpDLL int lbm_src_channel_create(lbm_src_channel_info_t **chnp, lbm_src_t *src, lbm_uint32_t channel_num);
05137 
05138 /*! \brief Release the resources associated with a source channel.
05139 
05140   \param chn A pointer to a channel info object allocated with lbm_src_channel_create.
05141   \return 0 for Success and -1 for Failure
05142   */
05143 LBMExpDLL int lbm_src_channel_delete(lbm_src_channel_info_t *chn);
05144 
05145 /*! \brief Create a UM source that will send messages to the given \a topic.
05146 
05147   \warning It is not safe to call this function from a context thread callback.
05148   \param srcp A pointer to a pointer to a UM source object. Will be filled in
05149               by this function to point to the newly created lbm_src_t object.
05150   \param ctx Pointer to the UM context object associated with the sender.
05151   \param topic Pointer to the UM topic object associated with the destination
05152                of messages sent by the source.
05153   \param proc Pointer to a function to call when events occur related to the source.
05154               If NULL, then events are not delivered to the source.
05155   \param clientd Pointer to client data that is passed when \a proc is called.
05156   \param evq Optional Event Queue to place events on when they occur.
05157          If NULL causes \a proc to be called from context thread.
05158   \return 0 for Success and -1 for Failure.
05159  */
05160 LBMExpDLL int lbm_src_create(lbm_src_t **srcp, lbm_context_t *ctx, lbm_topic_t *topic, lbm_src_cb_proc proc,
05161                                                          void *clientd, lbm_event_queue_t *evq);
05162 /*! \brief Retrieves all event queue attribute options.
05163 
05164         The config object is filled with event queue configuration options
05165         \param evq The event queue object to retrieve the attributes from
05166         \param size Size of the opts array. Will return the number of items that were set in opts
05167         \param opts The options array to fill
05168         */
05169 LBMExpDLL int lbm_event_queue_dump(lbm_event_queue_t *evq, int *size, lbm_config_option_t *opts);
05170 
05171 /*! \brief Retrieves all event queue attribute options.
05172 
05173         The config object is filled with event queue configuration options
05174         \param eattr The event queue attribute object to retrieve the attributes from
05175         \param size Size of the opts array. Will return the number of items that were set in opts
05176         \param opts The options array to fill
05177         */
05178 LBMExpDLL int lbm_event_queue_attr_dump(lbm_event_queue_attr_t *eattr, int *size, lbm_config_option_t *opts);
05179 
05180 /*! \brief Retrieves the number of options that are of type "event queue"
05181 
05182         The function returns the number of entries that are of type "event queue"
05183 
05184         \return The number of entries that are of type "event queue"
05185 */
05186 LBMExpDLL int lbm_event_queue_attr_option_size();
05187 
05188 /*! \brief Create a UM receiver that will receive messages sent to the given \a topic.
05189 
05190   The callback \a proc will be called to deliver data sent to the
05191   topics that the receiver has requested.
05192 
05193   \warning It is not safe to call this function from a context thread callback.
05194   \param rcvp A pointer to a pointer to a UM receiver object. Will be filled in
05195               by this function to point to the newly created lbm_rcv_t object.
05196   \param ctx Pointer to the UM context object associated with the receiver.
05197   \param topic Pointer to the UM topic object associated with the desired receiver topic.
05198   \warning Topic references should not be reused. Each lbm_rcv_create() call
05199                should be preceded by a call to lbm_rcv_topic_lookup().
05200   \param proc Pointer to a function to call when messages arrive.
05201   \param clientd Pointer to client data that is passed when data arrives and \a proc is called.
05202   \param evq Optional Event Queue to place message events on when they arrive.
05203   \return 0 for Success and -1 for Failure.
05204  */
05205 LBMExpDLL int lbm_rcv_create(lbm_rcv_t **rcvp, lbm_context_t *ctx, lbm_topic_t *topic,
05206                                                          lbm_rcv_cb_proc proc, void *clientd, lbm_event_queue_t *evq);
05207 
05208 /*! \brief Subscribe to a channel, with an optional callback and clientd data pointer.  
05209 
05210   The callback \a proc will be called to deliver messages sent with the
05211   specified \a channel number.  If NULL is specified for the \a proc,
05212   messages with the specified \a channel number will be delivered to the
05213   receiver's normal callback. If NULL is specified for the \a proc, any argument
05214   passed in for \a clientd will be ignored.
05215 
05216   \warning It is not safe to call this function from a context thread callback.
05217   \param rcv A pointer to a UM receiver object.
05218   \param channel A channel number to subscribe to.
05219   \param proc Pointer to a function to call when messages arrive.
05220   \param clientd Pointer to clientd data that is passed when data arrives and \a proc is called.
05221   \return 0 for Success and -1 for Failure
05222 */
05223 LBMExpDLL int lbm_rcv_subscribe_channel(lbm_rcv_t *rcv, lbm_uint32_t channel, lbm_rcv_cb_proc proc, void *clientd);
05224 
05225 /*! \brief Discontinue an existing channel subscription. 
05226 
05227   Remove a subscription to a channel previously subscribed to with \sa lbm_rcv_subscribe_channel.
05228 
05229   \param rcv A pointer to a UM receiver object.
05230   \param channel The channel number for the channel subscription to be removed.
05231   \return 0 for Success and -1 for Failure
05232 */
05233 LBMExpDLL int lbm_rcv_unsubscribe_channel(lbm_rcv_t *rcv, lbm_uint32_t channel);
05234 
05235 /*! \brief Discontinue an existing channel subscription with an application
05236   callback indicating when all messages on the channel have been delivered.  This extended
05237   version of the unsubscribe function requires the configuration option
05238   queue_cancellation_callbacks_enabled be set to 1.
05239   \param rcv A pointer to a UM receiver object.
05240   \param channel The channel number for the channel subscription to be removed.
05241   \param cbinfo Cancellation callback information, containing the event
05242                 queue, function pointer, and client data for the callback.
05243   \return 0 for Success and -1 for Failure
05244 */
05245 LBMExpDLL int lbm_rcv_unsubscribe_channel_ex(lbm_rcv_t *rcv, lbm_uint32_t channel, lbm_event_queue_cancel_cb_info_t *cbinfo);
05246 
05247 /*! \brief Subscribe to a channel, with an optional callback and clientd data pointer.
05248 
05249   The callback \a proc will be called to deliver messages sent with the
05250   specified \a channel number.  If NULL is specified for the \a proc,
05251   messages with the specified \a channel number will be delivered to the
05252   receiver's normal callback.  If NULL is specified  for the \a proc, any
05253   argument passed in for \a clientd will be ignored.
05254 
05255   \warning It is not safe to call this function from a context thread callback.
05256   \param wrcv A pointer to a UM wildcard receiver object.
05257   \param channel A channel number to subscribe to.
05258   \param proc Pointer to a function to call when messages arrive.
05259   \param clientd Pointer to clientd data that is passed when data arrives and \a proc is called.
05260   \return 0 for Success and -1 for Failure
05261 */
05262 LBMExpDLL int lbm_wildcard_rcv_subscribe_channel(lbm_wildcard_rcv_t *wrcv, lbm_uint32_t channel, lbm_rcv_cb_proc proc, void *clientd);
05263 
05264 /*! \brief Discontinue an existing channel subscription.
05265 
05266   Remove a subscription to a channel previously subscribed to with \sa lbm_wildcard_rcv_subscribe_channel.
05267 
05268   \param wrcv A pointer to a UM wildcard receiver object.
05269   \param channel The channel number for the channel subscription to be removed.
05270   \return 0 for Success and -1 for Failure
05271 */
05272 LBMExpDLL int lbm_wildcard_rcv_unsubscribe_channel(lbm_wildcard_rcv_t *wrcv, lbm_uint32_t channel);
05273 
05274 /*! \brief Discontinue an existing channel subscription with an application
05275   callback indicating when all messages on the channel have been delivered.  This extended
05276   version of the unsubscribe function requires the configuration option
05277   queue_cancellation_callbacks_enabled be set to 1.
05278   \param rcv A pointer to a UM wildcard receiver object.
05279   \param channel The channel number for the channel subscription to be removed.
05280   \param cbinfo Cancellation callback information, containing the event
05281                 queue, function pointer, and client data for the callback.
05282   \return 0 for Success and -1 for Failure
05283 */
05284 LBMExpDLL int lbm_wildcard_rcv_unsubscribe_channel_ex(lbm_wildcard_rcv_t *wrcv, lbm_uint32_t channel, lbm_event_queue_cancel_cb_info_t *cbinfo);
05285 
05286 /*! \brief Delete a UM source object.
05287 
05288   Delete a UM source object. Note that this function can return while the 
05289   source callback may still be executing if source events are being delivered 
05290   via an event queue. If the application needs to know when all possible 
05291   processing on the source is complete, it must use lbm_src_delete_ex().
05292 
05293   \warning It is not safe to call this function from a context thread callback.
05294   \param src Pointer to a UM source object to delete.
05295   \return 0 for Success and -1 for Failure.
05296 */
05297 LBMExpDLL int lbm_src_delete(lbm_src_t *src);
05298 
05299 /*! \brief Extended delete a UM source object.
05300 
05301   Delete a UM source object with an application callback indicating when
05302   the source is fully canceled.  This extended version of the source delete
05303   function requires the configuration option
05304   queue_cancellation_callbacks_enabled be set to 1.
05305 
05306   \warning It is not safe to call this function from a context thread callback.
05307   \param src Pointer to a UM source object to delete.
05308   \param cbinfo Cancellation callback information, containing the event
05309                 queue, function pointer, and client data for the callback.
05310   \return 0 for Success and -1 for Failure.
05311 */
05312 LBMExpDLL int lbm_src_delete_ex(lbm_src_t *src, lbm_event_queue_cancel_cb_info_t *cbinfo);
05313 
05314 /*!     \brief Retrieve the UM context object associated with a UM source object.
05315 
05316         \param src Pointer to a UM source object.
05317         \return A pointer to the UM context object associated with the UM source object.
05318 */
05319 LBMExpDLL lbm_context_t * lbm_context_from_src(lbm_src_t * src);
05320 
05321 /*!     \brief Retrieve the UM topic object associated with a UM source object.
05322 
05323         \param src Pointer to a UM source object.
05324         \return A pointer to the UM topic object associated with the UM source object.
05325 */
05326 LBMExpDLL lbm_topic_t * lbm_topic_from_src(lbm_src_t * src);
05327 
05328 /*!     \brief Retrieve the UM event queue object associated with a UM source object.
05329 
05330         \param src Pointer to a UM source object.
05331         \return A pointer to the UM event queue object associated with the UM source object.
05332 */
05333 LBMExpDLL lbm_event_queue_t * lbm_event_queue_from_src(lbm_src_t * src);
05334 
05335 /*! \brief Delete a UM receiver object.
05336 
05337   Delete a UM receiver object. Note that there are rare circumstances where
05338   this function can return while the receiver callback may still be executing.
05339   This would only occur if receiver events are being delivered via an event queue.
05340   If the application needs to know when all possible processing on the receiver
05341   is complete, it must use lbm_rcv_delete_ex().
05342 
05343   \warning It is not safe to call this function from a context thread callback.
05344   \param rcv Pointer to a UM receiver object to delete.
05345   \return 0 for Success and -1 for Failure.
05346 */
05347 LBMExpDLL int lbm_rcv_delete(lbm_rcv_t *rcv);
05348 
05349 /*! \brief Extended delete a UM receiver object.
05350 
05351   Delete a UM receiver object, with an application callback indicating when
05352   the receiver is fully canceled.  This extended version of the receiver
05353   delete function requires the configuration option
05354   queue_cancellation_callbacks_enabled be set to 1.
05355 
05356   \warning It is not safe to call this function from a context thread callback.
05357   \param rcv Pointer to a UM receiver object to delete.
05358   \param cbinfo Cancellation callback information, containing the event
05359                 queue, function pointer, and client data for the callback.
05360   \return 0 for Success and -1 for Failure.
05361 */
05362 LBMExpDLL int lbm_rcv_delete_ex(lbm_rcv_t *rcv, lbm_event_queue_cancel_cb_info_t *cbinfo);
05363 
05364 /*!     \brief Retrieve the UM context object associated with a UM receiver object.
05365 
05366         \param rcv Pointer to a UM receiver object.
05367         \return A pointer to the UM context object associated with the UM receiver object.
05368 */
05369 LBMExpDLL lbm_context_t * lbm_context_from_rcv(lbm_rcv_t * rcv);
05370 
05371 /*!     \brief Retrieve the UM event queue object associated with a UM receiver object.
05372 
05373         \param rcv Pointer to a UM receiver object.
05374         \return A pointer to the UM event queue object associated with the UM receiver object.
05375 */
05376 LBMExpDLL lbm_event_queue_t * lbm_event_queue_from_rcv(lbm_rcv_t * rcv);
05377 
05378 /*! \brief Set an option value within the given \a src.
05379 
05380            Only those options that can be set during operation may be specified.
05381            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
05382            in The UM Configuration Guide. For API functions that can access any option,
05383            see lbm_src_topic_attr_*().
05384   \param src Pointer to a UM source object where the option is to be set
05385   \param optname String containing the option name
05386   \param optval Pointer to the option value structure. The structure of the option values
05387                 are specific to the options themselves.
05388   \param optlen Length (in bytes) of the \a optval structure.
05389   \return 0 for Success and -1 for Failure.
05390 */
05391 LBMExpDLL int lbm_src_setopt(lbm_src_t *src, const char *optname, const void *optval, size_t optlen);
05392 
05393 /*! \brief Set an option value within the given \a src.
05394 
05395            Only those options that can be set during operation may be specified.
05396            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
05397            in The UM Configuration Guide. For API functions that can access any option,
05398            see lbm_src_topic_attr_*().
05399   \param src Pointer to a UM source object where the option is to be set
05400   \param optname String containing the option name
05401   \param optval String containing the option value. The format of the string
05402                 is specific to the options themselves.
05403   \return 0 for Success and -1 for Failure.
05404 */
05405 LBMExpDLL int lbm_src_str_setopt(lbm_src_t *src, const char *optname, const char *optval);
05406 
05407 /*! \brief Retrieve an option value within the given \a src.
05408 
05409   \param src Pointer to a UM source object where the option is stored
05410   \param optname String containing the option name
05411   \param optval Pointer to the option value structure. The structure of the option values
05412                 are specific to the options themselves.
05413   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
05414                 returned, this is the length of the filled in \a optval structure.
05415   \return 0 for Success and -1 for Failure.
05416 */
05417 LBMExpDLL int lbm_src_getopt(lbm_src_t *src, const char *optname, void *optval, size_t *optlen);
05418 
05419 /*! \brief Retrieve a textual option value within the given \a src.
05420 
05421   \param src Pointer to a UM source object where the option is stored
05422   \param optname String containing the option name
05423   \param optval String to be filled in with the option value.
05424   \param optlen When passed, this is the max length (in bytes) of the string. When
05425                 returned, this is the length of the filled in option value.
05426   \return 0 for Success and -1 for Failure.
05427 */
05428 LBMExpDLL int lbm_src_str_getopt(lbm_src_t *src, const char *optname, char *optval, size_t *optlen);
05429 
05430 /*! \brief Set an option value within the given \a rcv.
05431 
05432            Only those options that can be set during operation may be specified.
05433            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
05434            in The UM Configuration Guide. For API functions that can access any option,
05435            see lbm_rcv_topic_attr_*().
05436 
05437   \param rcv Pointer to a UM receiver object where the option is to be set
05438   \param optname String containing the option name
05439   \param optval Pointer to the option value structure. The structure of the option values
05440                 are specific to the options themselves.
05441   \param optlen Length (in bytes) of the \a optval structure.
05442   \return 0 for Success and -1 for Failure.
05443 */
05444 LBMExpDLL int lbm_rcv_setopt(lbm_rcv_t *rcv, const char *optname, const void *optval, size_t optlen);
05445 
05446 /*! \brief Set an option value within the given \a rcv.
05447 
05448            Only those options that can be set during operation may be specified.
05449            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
05450            in The UM Configuration Guide. For API functions that can access any option,
05451            see lbm_rcv_topic_attr_*().
05452   \param rcv Pointer to a UM receiver object where the option is to be set
05453   \param optname String containing the option name
05454   \param optval String containing the option value. The format of the string
05455                 is specific to the options themselves.
05456   \return 0 for Success and -1 for Failure.
05457 */
05458 LBMExpDLL int lbm_rcv_str_setopt(lbm_rcv_t *rcv, const char *optname, const char *optval);
05459 
05460 /*! \brief Retrieve an option value within the given \a rcv.
05461 
05462   \param rcv Pointer to a UM receiver object where the option is stored
05463   \param optname String containing the option name
05464   \param optval Pointer to the option value structure. The structure of the option values
05465                 are specific to the options themselves.
05466   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
05467                 returned, this is the length of the filled in \a optval structure.
05468   \return 0 for Success and -1 for Failure.
05469 */
05470 LBMExpDLL int lbm_rcv_getopt(lbm_rcv_t *rcv, const char *optname, void *optval, size_t *optlen);
05471 
05472 /*! \brief Retrieve a textual option value within the given \a rcv.
05473 
05474   \param rcv Pointer to a UM receiver object where the option is stored
05475   \param optname String containing the option name
05476   \param optval String to be filled in with the option value.
05477   \param optlen When passed, this is the max length (in bytes) of the string. When
05478                 returned, this is the length of the filled in with the option value.
05479   \return 0 for Success and -1 for Failure.
05480 */
05481 LBMExpDLL int lbm_rcv_str_getopt(lbm_rcv_t *rcv, const char *optname, char *optval, size_t *optlen);
05482 
05483 /* Send Routines */
05484 
05485 /*! \brief Send a message to the topic associated with a UM source.
05486 
05487   \warning Do not call this function from a context thread callback, as this can cause a deadlock.
05488   \param src Pointer to the UM source to send from
05489   \param msg Pointer to the data to send in this message
05490   \param len Length (in bytes) of the data to send in this message
05491   \param flags Flags indicating various conditions. ORed set of values.
05492   \arg \c LBM_MSG_START_BATCH - Message starts a batch of messages
05493   \arg \c LBM_MSG_END_BATCH - Message ends a batch of messages.
05494           Batch should be sent to the implicit batching buffer.
05495   \arg \c LBM_MSG_COMPLETE_BATCH - Message constitutes a complete batch
05496           and should be sent to the implicit batching buffer.
05497   \arg \c LBM_MSG_FLUSH - Message is to be sent ASAP (not implicitly or explicitly batched).
05498           This also flushes waiting messages that were explicitly or implicitly batched.
05499   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
05500           and error and signal LBM_EWOULDBLOCK.
05501   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
05502           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
05503           nor LBM_SRC_BLOCK are supplied.)
05504   \return -1 for Failure or 0 for Success.
05505 */
05506 LBMExpDLL int lbm_src_send(lbm_src_t *src, const char *msg, size_t len, int flags);
05507 
05508 /*! \brief Extended send of a message to the topic associated with a UM source.
05509 
05510   \warning  If called from a context thread callback, use the LBM_SRC_NONBLOCK flag and 
05511   handle any LBM_EWOULDBLOCK errors internally.
05512   \warning Calling this function from a context thread
05513   callback for stability and confirmation events could cause a deadlock
05514   \param src Pointer to the UM source to send from
05515   \param msg Pointer to the data to send in this message
05516   \param len Length (in bytes) of the data to send in this message
05517   \param flags Flags indicating various conditions. ORed set of values.
05518   \arg \c LBM_MSG_START_BATCH - Message starts a batch of messages
05519   \arg \c LBM_MSG_END_BATCH - Message ends a batch of messages.
05520           Batch should be sent to the implicit batching buffer.
05521   \arg \c LBM_MSG_COMPLETE_BATCH - Message constitutes a complete batch
05522           and should be sent to the implicit batching buffer.
05523   \arg \c LBM_MSG_FLUSH - Message is to be sent ASAP (not implicitly or explicitly batched).
05524           This also flushes waiting messages that were explicitly or implicitly batched.
05525   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
05526           and error and signal LBM_EWOULDBLOCK.
05527   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
05528           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
05529           nor LBM_SRC_BLOCK are supplied.)
05530   \param info Pointer to lbm_src_send_ex_info_t options
05531   \return -1 for Failure or 0 for Success.
05532 */
05533 LBMExpDLL int lbm_src_send_ex(lbm_src_t *src, const char *msg, size_t len, int flags, lbm_src_send_ex_info_t *info);
05534 
05535 /*! \brief Send messages from both the explicit and implicit batches ASAP.
05536 
05537   \warning Calling this function from a context thread
05538   callback for stability and confirmation events could cause a deadlock
05539   \param src Pointer to the UM source to send from
05540   \return -1 for Failure or 0 for Success.
05541 */
05542 LBMExpDLL int lbm_src_flush(lbm_src_t *src);
05543 
05544 /*! \brief Send a set of messages to the topic associated with a UM source.
05545 
05546   The messages are specified as an array of iovecs.  Be aware that each
05547   iovec element is considered as a full application message unless LBM_MSG_IOV_GATHER
05548   is used in the flags field. In that case, the elements of the array are gathered
05549   together into a single message.
05550 
05551   \warning It is not recommended to call this function from a context thread callback. If called 
05552   from a context thread callback, use the LBM_SRC_NONBLOCK flag and handle any LBM_EWOULDBLOCK 
05553   errors internally.
05554   \param src Pointer to the UM source to send from.
05555   \param iov Pointer to an array of iovecs that hold message information.
05556   \param num Number of elements of the iov array to send.
05557   \param flags Flags indicating various conditions. ORed set of values.
05558   \arg \c LBM_MSG_START_BATCH - Messages start a batch of messages
05559   \arg \c LBM_MSG_END_BATCH - Messages end a batch of messages.
05560           Batch should be sent to the implicit batching buffer.
05561   \arg \c LBM_MSG_COMPLETE_BATCH - Messages constitute a complete batch
05562           and should be sent to the implicit batching buffer.
05563   \arg \c LBM_MSG_FLUSH - Messages are to be sent ASAP (not implicitly batched or explicitly batched).
05564   \arg \c LBM_SRC_NONBLOCK - If messages could not be sent immediately return
05565           and error and signal LBM_EWOULDBLOCK.
05566   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the messages
05567           are all sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
05568           nor LBM_SRC_BLOCK are supplied.)
05569   \arg \c LBM_MSG_IOV_GATHER - iovec elements should be gather into a single message.
05570   \return -1 for Failure or 0 for Success.
05571 */
05572 LBMExpDLL int lbm_src_sendv(lbm_src_t *src, const lbm_iovec_t *iov, int num, int flags);
05573 
05574 /*! \brief Extended send of a set of messages to the topic associated with a UM source.
05575 
05576   The messages are specified as an array of iovecs. The elements of the array are gathered
05577   together into a single message.
05578 
05579   \warning  If called from a context thread callback, use the LBM_SRC_NONBLOCK flag and 
05580   handle any LBM_EWOULDBLOCK errors internally.
05581   \warning Calling this function from a context thread
05582   callback for stability and confirmation events could cause a deadlock
05583   \param src Pointer to the UM source to send from
05584   \param iov Pointer to an array of iovecs that hold message information.
05585   \param num Number of elements of the iov array to send.
05586   \param flags Flags indicating various conditions. ORed set of values.
05587   \arg \c LBM_MSG_START_BATCH - Message starts a batch of messages
05588   \arg \c LBM_MSG_END_BATCH - Message ends a batch of messages.
05589           Batch should be sent to the implicit batching buffer.
05590   \arg \c LBM_MSG_COMPLETE_BATCH - Message constitutes a complete batch
05591           and should be sent to the implicit batching buffer.
05592   \arg \c LBM_MSG_FLUSH - Message is to be sent ASAP (not implicitly or explicitly batched).
05593           This also flushes waiting messages that were explicitly or implicitly batched.
05594   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
05595           and error and signal LBM_EWOULDBLOCK.
05596   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
05597           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
05598           nor LBM_SRC_BLOCK are supplied.)
05599   \param info Pointer to lbm_src_send_ex_info_t options
05600   \return -1 for Failure or 0 for Success.
05601 */
05602 LBMExpDLL int lbm_src_sendv_ex(lbm_src_t *src, const lbm_iovec_t *iov, int num, int flags, lbm_src_send_ex_info_t *info);
05603 
05604 /*! \brief Set the pointer value to set in the messages received for the given receiver from a specific source.
05605 
05606   \param rcv Pointer to the UM receiver to look for the source on.
05607   \param source String version of the source to look for.
05608   \param source_clientd Pointer value to set in subsequent messages delivered.
05609   \return -1 for Failure and 0 for Success.
05610 */
05611 LBMExpDLL int lbm_rcv_msg_source_clientd(lbm_rcv_t *rcv, const char *source, void *source_clientd);
05612 
05613 /*! \brief Retrieve the transport statistics for the transport used by the given source.
05614 
05615   \param src Pointer to the UM source to retrieve statistics for.
05616   \param stats Pointer to a stats structure to fill in.
05617   \return -1 for Failure and 0 for Success.
05618 */
05619 LBMExpDLL int lbm_src_retrieve_transport_stats(lbm_src_t *src, lbm_src_transport_stats_t *stats);
05620 
05621 /*! \brief Reset the transport statistics for the transport used by the given source.
05622 
05623   \param src Pointer to the UM source to reset statistics for.
05624   \return -1 for Failure and 0 for Success.
05625 */
05626 LBMExpDLL int lbm_src_reset_transport_stats(lbm_src_t *src);
05627 
05628 /*! \brief Retrieve the transport statistics for the transport used by the given receiver from a specific source.
05629 
05630   \param rcv Pointer to the UM receiver to retrieve statistics for.
05631   \param source String version of the source, excluding the topic index, to retrieve stats for. See also option source_includes_topic_index.
05632   \param stats Pointer to a stats structure to fill in.
05633   \return -1 for Failure and 0 for Success.
05634 */
05635 LBMExpDLL int lbm_rcv_retrieve_transport_stats(lbm_rcv_t *rcv, const char *source, lbm_rcv_transport_stats_t *stats);
05636 
05637 /*! \brief Reset the transport statistics for the transport used by the given receiver from a specific source.
05638 
05639   \param rcv Pointer to the UM receiver to reset statistics for.
05640   \param source String version of the source to reset statistics for.
05641   \return -1 for Failure and 0 for Success.
05642 */
05643 LBMExpDLL int lbm_rcv_reset_transport_stats(lbm_rcv_t *rcv, const char *source);
05644 
05645 /*! \brief Retrieve the transport stats for all the sources seen by the given receiver.
05646 
05647   \param rcv Pointer to the UM receiver to retrieve statistics for.
05648   \param num Pointer to an integer that must hold the maximum number of elements in the stats array when passed in.
05649              Upon return, this value is set to the number of sources filled in.
05650   \param stats Array of lbm_rcv_transport_stats_t objects to fill in transport stats for.
05651   \return -1 for Failure and 0 for Success.
05652   \note If -1 is returned, and lbm_errnum() returns LBM_EINVAL, then \a *num may
05653   contain a larger number than the value originally passed into this function.
05654   This return value represents the number of lbm_rcv_transport_stats_t objects
05655   required in the \a stats array and can be used to dynamically determine
05656   how many entries are needed.
05657 */
05658 LBMExpDLL int lbm_rcv_retrieve_all_transport_stats(lbm_rcv_t *rcv, int *num, lbm_rcv_transport_stats_t *stats);
05659 
05660 LBMExpDLL int lbm_rcv_retrieve_all_transport_stats_ex(lbm_rcv_t *rcv, int *num, int size, lbm_rcv_transport_stats_t *stats);
05661 
05662 #ifndef LBM_INTERNAL_USE_ONLY
05663 #define lbm_rcv_retrieve_all_transport_stats(r,n,s) \
05664             lbm_rcv_retrieve_all_transport_stats_ex(r,n,sizeof(lbm_rcv_transport_stats_t),s)
05665 #endif
05666 
05667 /*! \brief Reset the transport stats for all the sources seen by the given receiver.
05668 
05669   \param rcv Pointer to the UM receiver to reset statistics for.
05670   \return -1 for Failure and 0 for Success.
05671 */
05672 LBMExpDLL int lbm_rcv_reset_all_transport_stats(lbm_rcv_t *rcv);
05673 
05674 /*! \brief Retrieve the transport stats for all receivers in a given context.
05675 
05676   \param ctx Pointer to the UM context to retrieve statistics for.
05677   \param num Pointer to an integer that must hold the maximum number of elements in the stats array when passed in.
05678              Upon return, this value is set to the number of sources filled in.
05679   \param stats Array of lbm_rcv_transport_stats_t objects to fill in transport stats for.
05680   \return -1 for Failure and 0 for Success.
05681   \note If -1 is returned, and lbm_errnum() returns LBM_EINVAL, then \a *num may
05682   contain a larger number than the value originally passed into this function.
05683   This return value represents the number of lbm_rcv_transport_stats_t objects
05684   required in the \a stats array and can be used to dynamically determine
05685   how many entries are needed.
05686 */
05687 LBMExpDLL int lbm_context_retrieve_rcv_transport_stats(lbm_context_t *ctx, int *num, lbm_rcv_transport_stats_t *stats);
05688 
05689 LBMExpDLL int lbm_context_retrieve_rcv_transport_stats_ex(lbm_context_t *ctx, int *num, int size, lbm_rcv_transport_stats_t *stats);
05690 
05691 #ifndef LBM_INTERNAL_USE_ONLY
05692 #define lbm_context_retrieve_rcv_transport_stats(c,n,s) \
05693             lbm_context_retrieve_rcv_transport_stats_ex(c,n,sizeof(lbm_rcv_transport_stats_t),s)
05694 #endif
05695 
05696 /*! \brief Reset the transport stats for all receivers in a given context.
05697 
05698   \param ctx Pointer to the UM context to reset statistics for.
05699   \return -1 for Failure and 0 for Success.
05700 */
05701 LBMExpDLL int lbm_context_reset_rcv_transport_stats(lbm_context_t *ctx);
05702 
05703 /*! \brief Retrieve the transport stats for all the sources in a given context.
05704 
05705   \param ctx Pointer to the UM context to retrieve statistics for.
05706   \param num Pointer to an integer that must hold the maximum number of elements in the stats array when passed in.
05707              Upon return, this value is set to the number of sources filled in.
05708   \param stats Array of lbm_src_transport_stats_t objects to fill in transport stats for.
05709   \return -1 for Failure and 0 for Success.
05710   \note If -1 is returned, and lbm_errnum() returns LBM_EINVAL, then \a *num may
05711   contain a larger number than the value originally passed into this function.
05712   This return value represents the number of lbm_src_transport_stats_t objects
05713   required in the \a stats array and can be used to dynamically determine
05714   how many entries are needed.
05715 */
05716 LBMExpDLL int lbm_context_retrieve_src_transport_stats(lbm_context_t *ctx, int *num, lbm_src_transport_stats_t *stats);
05717 
05718 LBMExpDLL int lbm_context_retrieve_src_transport_stats_ex(lbm_context_t *ctx, int *num, int size, lbm_src_transport_stats_t *stats);
05719 
05720 #ifndef LBM_INTERNAL_USE_ONLY
05721 #define lbm_context_retrieve_src_transport_stats(c,n,s) \
05722             lbm_context_retrieve_src_transport_stats_ex(c,n,sizeof(lbm_src_transport_stats_t),s)
05723 #endif
05724 
05725 /*! \brief Reset the transport stats for all the sources in a given context.
05726 
05727   \param ctx Pointer to the UM context to reset statistics for.
05728   \return -1 for Failure and 0 for Success.
05729 */
05730 LBMExpDLL int lbm_context_reset_src_transport_stats(lbm_context_t *ctx);
05731 
05732 /*! \brief Retrieve the stats for an event queue.
05733 
05734   \param evq Pointer to the UM event queue to retrieve statistics for.
05735   \param stats Pointer to a stats structure to fill in.
05736   \return -1 for Failure and 0 for Success.
05737 */
05738 LBMExpDLL int lbm_event_queue_retrieve_stats(lbm_event_queue_t *evq, lbm_event_queue_stats_t *stats);
05739 
05740 /*! \brief Reset the stats for an event queue.
05741 
05742   \param evq Pointer to the UM event queue to reset statistics for.
05743   \return -1 for Failure and 0 for Success.
05744 */
05745 LBMExpDLL int lbm_event_queue_reset_stats(lbm_event_queue_t *evq);
05746 
05747 /*! \brief Retrieve the stats for a context.
05748 
05749   \param ctx Pointer to the UM context to retrieve statistics for.
05750   \param stats Pointer to a stats structure to fill in.
05751   \return -1 for Failure and 0 for Success.
05752 */
05753 LBMExpDLL int lbm_context_retrieve_stats(lbm_context_t *ctx, lbm_context_stats_t *stats);
05754 
05755 /*! \brief Reset the stats for a context.
05756 
05757   \param ctx Pointer to the UM context to reset statistics for.
05758   \return -1 for Failure and 0 for Success.
05759 */
05760 LBMExpDLL int lbm_context_reset_stats(lbm_context_t *ctx);
05761 
05762 /*! \brief Retrieve the IM source stats for a context.
05763 
05764   \param ctx Pointer to the UM context to retrieve statistics for.
05765   \param num Pointer to an integer that must hold the maximum number of elements in the stats array when passed in.
05766              Upon return, this value is set to the number of sources filled in.
05767   \param size Size in bytes of each entry in \a stats
05768   \param stats Array of lbm_src_transport_stats_t objects to fill in transport stats for.
05769   \return -1 for Failure and 0 for Success.
05770   \note If -1 is returned, and lbm_errnum() returns LBM_EINVAL, then \a *num may
05771   contain a larger number than the value originally passed into this function.
05772   This return value represents the number of lbm_src_transport_stats_t objects
05773   required in the \a stats array and can be used to dynamically determine
05774   how many entries are needed.
05775 */
05776 LBMExpDLL int lbm_context_retrieve_im_src_transport_stats(lbm_context_t *ctx, int *num, int size, lbm_src_transport_stats_t *stats);
05777 
05778 /*! \brief Reset the IM source stats for a context.
05779 
05780   \param ctx Pointer to the UM context to reset statistics for.
05781   \param stats Pointer to a stats structure to fill in.
05782   \return -1 for Failure and 0 for Success.
05783 */
05784 LBMExpDLL int lbm_context_reset_im_src_transport_stats(lbm_context_t *ctx);
05785 
05786 /*! \brief Retrieve the IM receiver stats for a context.
05787 
05788   \param ctx Pointer to the UM context to retrieve statistics for.
05789   \param num Pointer to an integer that must hold the maximum number of elements in the stats array when passed in.
05790              Upon return, this value is set to the number of sources filled in.
05791   \param size Size in bytes of each entry in \a stats
05792   \param stats Array of lbm_rcv_transport_stats_t objects to fill in transport stats for.
05793   \return -1 for Failure and 0 for Success.
05794   \note If -1 is returned, and lbm_errnum() returns LBM_EINVAL, then \a *num may
05795   contain a larger number than the value originally passed into this function.
05796   This return value represents the number of lbm_rcv_transport_stats_t objects
05797   required in the \a stats array and can be used to dynamically determine
05798   how many entries are needed.
05799 */
05800 LBMExpDLL int lbm_context_retrieve_im_rcv_transport_stats(lbm_context_t *ctx, int *num, int size, lbm_rcv_transport_stats_t *stats);
05801 
05802 /*! \brief Reset the IM receiver stats for a context.
05803 
05804   \param ctx Pointer to the UM context to reset statistics for.
05805   \param stats Pointer to a stats structure to fill in.
05806   \return -1 for Failure and 0 for Success.
05807 */
05808 LBMExpDLL int lbm_context_reset_im_rcv_transport_stats(lbm_context_t *ctx);
05809 
05810 /*! \brief Instruct UM that the API is going to retain ownership of a UM message object.
05811 
05812   This function should be called from inside a receiver callback function to
05813   prevent UM from automatically deleting the message when the callback
05814   function returns (LBM's normal behavior).
05815 
05816   Once retained, the application has the responsibility to dispose of the
05817   message when it is finished with it by calling lbm_msg_delete().
05818 
05819   \param msg Pointer to a UM message object to retain.
05820   \return 0 for Success and -1 for Failure.
05821 */
05822 LBMExpDLL int lbm_msg_retain(lbm_msg_t *msg);
05823 
05824 /*! \brief Retrieve fragment information from a UM message.
05825 
05826   \param msg Pointer to a UM message object to retrieve fragment information from.
05827   \param info Pointer to fragment information structure to fill in.
05828   \return 0 for Success and -1 for Failure.
05829 */
05830 LBMExpDLL int lbm_msg_is_fragment(lbm_msg_t *msg);
05831 
05832 /*! \brief Returns 1 if lbm message is a fragment, else 0 is returned
05833 
05834   \param msg Pointer to a UM message object 
05835   \return 1 for Success and 0 for Failure.
05836 */
05837 LBMExpDLL int lbm_msg_retrieve_fragment_info(lbm_msg_t *msg, lbm_msg_fragment_info_t *info);
05838 
05839 /*! \brief Retrieve gateway information from a UM message.
05840 
05841   This function is deprecated.
05842 
05843   \param msg Pointer to a UM message object to retrieve gateway information from.
05844   \param info Pointer to gateway information structure to fill in.
05845   \return 0 for Success and -1 for Failure.
05846 */
05847 LBMExpDLL int lbm_msg_retrieve_gateway_info(lbm_msg_t *msg, lbm_msg_gateway_info_t *info);
05848 
05849 /*! \brief Retrieve UMQ Message ID information from a UM message.
05850 
05851   \param msg Pointer to a UM message object to retrieve UMQ Message ID info from.
05852   \param id Pointer to UMQ Message ID structure to fill in.
05853   \return 0 for Success and -1 for Failure.
05854 */
05855 LBMExpDLL int lbm_msg_retrieve_msgid(lbm_msg_t *msg, lbm_umq_msgid_t *id);
05856 
05857 /*! \brief Retrieve UMQ index information from a UM message.
05858 
05859   \param msg Pointer to a UM message object to retrieve UMQ index info from.
05860   \param info Pointer to UMQ index structure to fill in.
05861   \return 0 for Success and -1 for Failure.
05862  */
05863 LBMExpDLL int lbm_msg_retrieve_umq_index(lbm_msg_t *msg, lbm_umq_index_info_t *info);
05864 
05865 LBMExpDLL int lbm_msg_retrieve_delivery_latency(lbm_msg_t *msg, lbm_int64_t *latency_nsecs);
05866 
05867 /*! \brief Delete a UM message object.
05868 
05869   This should only be called if the message was previously saved via
05870   lbm_msg_retain().
05871   Any associated lbm_response_t objects for this message are cleaned up
05872   automatically in this function.
05873 
05874   \note A receive callback should never delete the message that was passed
05875   in.  It should either let UM delete it when the callback returns, or it
05876   should retain it and delete it later.
05877 
05878   \param msg Pointer to a UM message object to delete.
05879   \return 0 for Success and -1 for Failure.
05880 */
05881 LBMExpDLL int lbm_msg_delete(lbm_msg_t *msg);
05882 
05883 /*! \brief Send an Explicit UMP ACK for a UM message object.
05884 
05885   This function causes a UMP Explicit ACK to be sent that acknowledges previous
05886   messages since the last UMP Explicit ACK for the source was performed.
05887 
05888   \param msg Pointer to a UM message object to acknowledge up to.
05889   \return 0 for Success and -1 for Failure.
05890 */
05891 LBMExpDLL int lbm_msg_ume_send_explicit_ack(lbm_msg_t *msg);
05892 
05893 /*! \brief Check to see if Explicit UMP ACK for a UM message object can be called.
05894 
05895   \param msg Pointer to a UM message object to acknowledge up to.
05896   \return 1 for true and 0 for False.
05897 */
05898 LBMExpDLL int lbm_msg_ume_can_send_explicit_ack(lbm_msg_t *msg);
05899 
05900 /*! \brief Deregister a source from the UMP stores
05901  *
05902  * This function causes a UMP deregistration to be sent to all stores the
05903  * source is currently registered to, and disallows any future registrations
05904  * from taking place.
05905  *
05906  * \param src Pointer to a UM source object 
05907  * \return 0 for Success and -1 for Failure.
05908  */
05909 LBMExpDLL int lbm_src_ume_deregister(lbm_src_t *src);
05910 
05911 /*! \brief Deregister a receiver from all known UMP stores.
05912  *
05913  *  This function causes a UMP deregistration request to be sent to all stores the
05914  *  receiver is currently registered to, and disallows any future registrations.
05915  *
05916  *  \param rcv Pointer to an UM receiver object
05917  *  \return 0 for Success and -1 for Failure
05918  */
05919 LBMExpDLL int lbm_rcv_ume_deregister(lbm_rcv_t *rcv);
05920 
05921 /*! \brief Deregister a wildcard receiver from all known UMP stores
05922  *
05923  * This function causes a UMP deregistration request to be sent to all stores the
05924  * wildcard receiver is currently registered to, and disallows any future registrations.
05925  *
05926  * \param wrcv Pointer to a UM wildcard receiver object
05927  * \return 0 for Success and -1 for Failure
05928  */
05929 LBMExpDLL int lbm_wrcv_ume_deregister(lbm_wildcard_rcv_t *wrcv);
05930 
05931 /*! \brief Do not acknowledge the given message and instead request that the message be reassigned.
05932 
05933   \param msg Pointer to a UM message to request to be reassigned.
05934   \param flags Flags indicating various conditions. ORed set of values.
05935   \arg \c LBM_MSG_UMQ_REASSIGN_FLAG_DISCARD - Message should be discarded instead of being assigned.
05936   \return 0 for Success and -1 for Failure.
05937  */
05938 LBMExpDLL int lbm_msg_umq_reassign(lbm_msg_t *msg, int flags);
05939         
05940 /*! \brief De-Register the given receiver from the given UMQ queue or all UMQ queues.
05941 
05942   \param rcv Pointer to receiver object to de-register.
05943   \param queue_name Name of the queue or ULB source to deregister from. A NULL means de-register from all UMQ queues
05944   and ULB sources.
05945   \return 0 for Success and -1 for Failure.
05946 */
05947 LBMExpDLL int lbm_rcv_umq_deregister(lbm_rcv_t *rcv, const char *queue_name);
05948 
05949 /*! \brief Stop assignment of new UMQ indices to the given receiver from the given UMQ queue or all UMQ queues.
05950 
05951   This function causes new UMQ indices to not be assigned to the given receiver from the given UMQ queue(s).
05952   Messages with previously assigned UMQ indices may continue to be delivered to the given receiver from
05953   the given UMQ queue(s).
05954 
05955   \param rcv Pointer to receiver object to stop assignment for.
05956   \param queue_name Name of the queue to stop assignment from. A NULL means stop assignment from all UMQ queues.
05957   \return 0 for Success and -1 for Failure.
05958  */
05959 LBMExpDLL int lbm_rcv_umq_index_stop_assignment(lbm_rcv_t *rcv, const char *queue_name);
05960 
05961 /*! \brief Start assignment of new UMQ indices to the given receiver from the given UMQ queue or all UMQ queues.
05962 
05963   \param rcv Pointer to receiver object to start assignment for.
05964   \param queue_name Name of the queue to start assignment from. A NULL means start assignment from all UMQ queues.
05965   \return 0 for Success and -1 for Failure.
05966  */
05967 LBMExpDLL int lbm_rcv_umq_index_start_assignment(lbm_rcv_t *rcv, const char *queue_name);
05968 
05969 /*! \brief Instruct the given UMQ queue(s) to reserve an index for assignment to this receiver.
05970 
05971   This function causes the UMQ queue(s) or ULB sources to assign the specified index to this receiver
05972   if the queue ever happens to see a message sent on the specified index.  If the index is already
05973   assigned, an error is returned as a LBM_MSG_UMQ_INDEX_ASSIGNMENT_ERROR receiver event.  Otherwise,
05974   if the reservation is successful, the receiver will get a LBM_MSG_UMQ_INDEX_ASSIGNED_EX event.
05975 
05976   \param rcv Pointer to receiver object that wishes to release the index.
05977   \param queue_name Name of the queue(s) at which to reserve the index. A NULL means reassign the index for all UMQ queues.
05978   \param index_info Index to reserve, or NULL to reserve a random unused numeric index.
05979   \return 0 for Success and -1 for Failure.
05980  */
05981 LBMExpDLL int lbm_rcv_umq_index_reserve(lbm_rcv_t *rcv, const char *queue_name, lbm_umq_index_info_t *index_info);
05982 
05983 /*! \brief Instruct the given UMQ queue(s) to release the given UMQ index that is assigned to the given receiver.
05984 
05985   This function causes the UMQ indices to be assigned to another receiver.
05986 
05987   \param rcv Pointer to receiver object that wishes to release the index.
05988   \param queue_name Name of the queue to reassign the index. A NULL means reassign the index for all UMQ queues.
05989   \return 0 for Success and -1 for Failure.
05990  */
05991 LBMExpDLL int lbm_rcv_umq_index_release(lbm_rcv_t *rcv, const char *queue_name, lbm_umq_index_info_t *index_info);
05992 
05993 /*! \brief Stop assignment of new UMQ indices to the given wildcard receiver from the given UMQ queue or all UMQ queues.
05994 
05995   This function causes new UMQ indices to not be assigned to the given wildcard receiver from the given UMQ queue(s).
05996   Messages with previously assigned UMQ indices may continue to be delivered to the given wildcard receiver from
05997   the given UMQ queue(s).
05998 
05999   \param wrcv Pointer to wildcard receiver object to stop assignment for.
06000   \param queue_name Name of the queue to stop assignment from. A NULL means stop assignment from all UMQ queues.
06001   \return 0 for Success and -1 for Failure.
06002  */
06003 LBMExpDLL int lbm_wildcard_rcv_umq_index_stop_assignment(lbm_wildcard_rcv_t *wrcv, const char *queue_name);
06004 
06005 /*! \brief Start assignment of new UMQ indices to the given wildcard receiver from the given UMQ queue or all UMQ queues.
06006 
06007   \param wrcv Pointer to wildcard receiver object to start assignment for.
06008   \param queue_name Name of the queue to start assignment from. A NULL means start assignment from all UMQ queues.
06009   \return 0 for Success and -1 for Failure.
06010  */
06011 LBMExpDLL int lbm_wildcard_rcv_umq_index_start_assignment(lbm_wildcard_rcv_t *wrcv, const char *queue_name);
06012 
06013 /*! \brief Instruct the given UMQ queue(s) to release the given UMQ index that is assigned to the given wildcard receiver.
06014 
06015   This function causes the UMQ indices to be assigned to another receiver.
06016 
06017   \param wrcv Pointer to wildcard receiver object that wishes to release the index.
06018   \param queue_name Name of the queue to reassign the index. A NULL means reassign the index for all UMQ queues.
06019   \return 0 for Success and -1 for Failure.
06020  */
06021 LBMExpDLL int lbm_wildcard_rcv_umq_index_release(lbm_wildcard_rcv_t *wrcv, const char *queue_name, lbm_umq_index_info_t *index_info);
06022 
06023 /*! \brief De-Register the given wildcard receiver from the given UMQ queue or all UMQ queues.
06024 
06025   \param wrcv Pointer to wildcard receiver object to de-register.
06026   \param queue_name Name of the queue to deregister from. A NULL means de-register from all UMQ queues.
06027   \return 0 for Success and -1 for Failure.
06028 */
06029 LBMExpDLL int lbm_wildcard_rcv_umq_deregister(lbm_wildcard_rcv_t *wrcv, const char *queue_name);
06030 
06031 /*! \brief Send a response for a given \a resp response.
06032 
06033   \param resp A pointer to an lbm_response_t object given in a lbm_msg_t object.
06034   \param data Buffer to send as the response data.
06035   \param len Length (in bytes) of the data to send as the response data.
06036   \param flags Flags indicating various conditions. ORed set of values.
06037   \arg \c LBM_SRC_NONBLOCK - If messages could not be sent immediately return
06038           and error and signal LBM_EWOULDBLOCK.
06039   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
06040           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06041           nor LBM_SRC_BLOCK are supplied.)
06042   \return -1 for Failure or the number of bytes sent if Successful.
06043 */
06044 LBMExpDLL int lbm_send_response(lbm_response_t *resp, const char *data, size_t len, int flags);
06045 
06046 /*! \brief Delete a UM response object.
06047 
06048            When an application receives a \a request, the message object
06049            \a lbm_msg_t contains a response object \a response which is used
06050            by lbm_send_response().  Normally, when the receive callback
06051            returns, both the message and the response object are deleted by
06052            UM.  However the receive callback can optionally save the response
06053            object and set \a msg->response=NULL to prevent UM from deleting
06054            it when the receive callback returns.  It then becomes the
06055            application's responsibility to delete the response when appropriate.
06056 
06057   \sa lbm_msg_t, lbm_msg_delete
06058   \param resp A pointer to an lbm_response_t object given in a lbm_msg_t object.
06059   \return 0 for Success and -1 for Failure.
06060 */
06061 LBMExpDLL int lbm_response_delete(lbm_response_t *resp);
06062 
06063 
06064 /*! \brief Delete a UM serialized response object.
06065 
06066            After a serialized UM response object has been copied or used, it
06067            is the application's responsibility to delete the serialized response
06068            object.
06069 
06070   \param serialized_response A pointer to an lbm_serialized_response_t object.
06071   \return 0 for Success and -1 for Failure.
06072 */
06073 LBMExpDLL int lbm_serialized_response_delete(lbm_serialized_response_t* serialized_response);
06074 
06075 
06076 /*! \brief Serialize a UM response object.
06077 
06078            An UM response object (lbm_response_t) may be serialized to allow
06079            applications other than the one originally receiving a request to
06080            respond to that request.
06081 
06082   \param resp A pointer to an lbm_response_t object.
06083   \return A pointer to an lbm_serialized_response_t object.
06084 */
06085 LBMExpDLL lbm_serialized_response_t* lbm_serialize_response(lbm_response_t *resp);
06086 
06087 /*! \brief De-serialize a UM response object.
06088 
06089            De-serializes a serialized UM response object, making it usable
06090            for lbm_send_response().  Note that the returned lbm_response_t
06091            object should be treated as any other normal response object,
06092            and deleted by the application using lbm_response_delete() as
06093            appropriate.
06094 
06095   \param ctx A pointer to a UM context object.
06096   \param serialized_response A pointer to a serialized UM response object.
06097   \return A pointer to a lbm_response_t object or NULL for failure.
06098 */
06099 LBMExpDLL lbm_response_t* lbm_deserialize_response(lbm_context_t *ctx, lbm_serialized_response_t* serialized_response);
06100 
06101 /*! \brief Send a request on the given src that contains the given data.
06102 
06103            This function creates a request object \a reqp which is used by
06104            UM to route responses to the desired application callback \a proc
06105            and must be retained until all responses are received.  When
06106            the requestor does not expect any additional responses, it deletes
06107            the request object using lbm_request_delete().
06108 
06109   \sa lbm_src_send
06110   \warning It is not recommended to call this function from a context thread callback. If called 
06111   from a context thread callback, use the LBM_SRC_NONBLOCK flag and handle any LBM_EWOULDBLOCK 
06112   errors internally.
06113   \param reqp A pointer to a pointer for the lbm_request_t object created to be stored.
06114   \param src The UM source to send the request out.
06115   \param data Buffer to be included as data in the request.
06116   \param len Length (in bytes) of the data included with the request.
06117   \param proc Pointer to function to call when responses come in for this request.
06118   \param clientd Client data returned in the callback proc \a proc.
06119   \param evq Optional Event Queue to place message events on when they occur.
06120          If NULL causes \a proc to be called from context thread.
06121   \param send_flags Flags used to instruct UM how to handle this message. See \a lbm_src_send()
06122                     for more information.
06123   \return 0 for Success and -1 for Failure.
06124 */
06125 LBMExpDLL int lbm_send_request(lbm_request_t **reqp, lbm_src_t *src, const char *data,
06126                                                            size_t len, lbm_request_cb_proc proc, void *clientd, lbm_event_queue_t *evq,
06127                                                            int send_flags);
06128 
06129 /*! \brief Send a request on the given src that contains the given data.
06130 
06131            This function creates a request object \a reqp which is used by
06132            UM to route responses to the desired application callback \a proc
06133            and must be retained until all responses are received.  When
06134            the requestor does not expect any additional responses, it deletes
06135            the request object using lbm_request_delete().
06136 
06137   \sa lbm_src_send
06138   \warning It is not recommended to call this function from a context thread callback. If called
06139   from a context thread callback, use the LBM_SRC_NONBLOCK flag and handle any LBM_EWOULDBLOCK
06140   errors internally.
06141   \param reqp A pointer to a pointer for the lbm_request_t object created to be stored.
06142   \param src The UM source to send the request out.
06143   \param data Buffer to be included as data in the request.
06144   \param len Length (in bytes) of the data included with the request.
06145   \param proc Pointer to function to call when responses come in for this request.
06146   \param clientd Client data returned in the callback proc \a proc.
06147   \param evq Optional Event Queue to place message events on when they occur.
06148          If NULL causes \a proc to be called from context thread.
06149   \param send_flags Flags used to instruct UM how to handle this message. See \a lbm_src_send()
06150                     for more information.
06151   \param exinfo Pointer to lbm_src_send_ex_info_t options
06152   \return 0 for Success and -1 for Failure.
06153 */
06154 LBMExpDLL int lbm_send_request_ex(lbm_request_t **reqp, lbm_src_t *src, const char *data,
06155                                                            size_t len, lbm_request_cb_proc proc, void *clientd, lbm_event_queue_t *evq,
06156                                                            int send_flags, lbm_src_send_ex_info_t *exinfo);
06157 
06158 /*! \brief Delete a UM request object.
06159 
06160   Delete a UM request object. When this function is used, subsequent
06161   responses for this given request object will be ignored.  Note that this 
06162   function can return while the callback may still be executing if request events 
06163   are being delivered via an event queue. If the application needs to know when
06164   all possible processing on the request is complete, it must use
06165   lbm_request_delete_ex().
06166 
06167   \param req A pointer to an lbm_request_t object returned by \a lbm_send_request.
06168   \return 0 for Success and -1 for Failure.
06169 */
06170 LBMExpDLL int lbm_request_delete(lbm_request_t *req);
06171 
06172 /*! \brief Extended delete a UM request object.
06173 
06174   Delete a UM request object, with an application callback indicating when
06175   the request is fully canceled.  When this function is used, any more
06176   responses for this given request object will be ignored.  This extended
06177   version of the request cancel function requires the configuration option
06178   queue_cancellation_callbacks_enabled be set to 1.
06179 
06180   \param req A pointer to an lbm_request_t object returned by \a lbm_send_request.
06181   \param cbinfo Cancellation callback information, containing the event
06182                 queue, function pointer, and client data for the callback.
06183   \return 0 for Success and -1 for Failure.
06184 */
06185 LBMExpDLL int lbm_request_delete_ex(lbm_request_t *req, lbm_event_queue_cancel_cb_info_t *cbinfo);
06186 
06187 /*! \brief Create a UM event queue object.
06188 
06189   This function creates an event queue that may be passed in several functions in
06190   order for events/callbacks to be queued for execution.
06191 
06192   \param evqp A pointer to a pointer for the lbm_event_queue_t object created to be stored.
06193   \param proc Pointer to function to call when monitoring the event queue.
06194   \param clientd Client data returned in the callback proc \a proc.
06195   \param attr A pointer to an event queue attribute object or NULL for default attributes.
06196   \return 0 for Success and -1 for Failure.
06197 */
06198 LBMExpDLL int lbm_event_queue_create(lbm_event_queue_t **evqp, lbm_event_queue_monitor_proc proc,
06199                                                                          void *clientd, const lbm_event_queue_attr_t *attr);
06200 
06201 /*! \brief Create and fill a UM event queue attribute object with the current default values.
06202 
06203   The attribute object is allocated and filled with the current default values that are
06204   used by lbm_event_queue_t objects and may have been modified by a previously loaded configuration file.
06205 
06206   \param attr A pointer to a pointer to a UM event queue attribute structure. Will be
06207     filled in by this function to point to the newly created lbm_event_queue_attr_t object.
06208   \return 0 for Success and -1 for Failure.
06209 */
06210 LBMExpDLL int lbm_event_queue_attr_create(lbm_event_queue_attr_t * * attr);
06211 
06212 /*! \brief Create and fill a UM event queue attribute object with the initial default values.
06213 
06214   The attribute object is allocated and filled with the initial or factory default values built into LBM
06215   that are used by lbm_event_queue_t objects that concern receivers.
06216 
06217   \param attr A pointer to a pointer to a UM event queue attribute structure. Will be
06218     filled in by this function to point to the newly created lbm_event_queue_attr_t object.
06219   \return 0 for Success and -1 for Failure.
06220 */
06221 LBMExpDLL int lbm_event_queue_attr_create_default(lbm_event_queue_attr_t * * attr);
06222 
06223 /*! \brief Create and fill a UM event queue attribute object with the current default values for the given event queue name.
06224 
06225   The attribute object is allocated and filled with the current default values 
06226   that are used by lbm_event_queue_t objects and may have been modified by a 
06227   previously loaded configuration file.
06228   Then, if an XML configuration file has been loaded, the attribute object is
06229   further filled with the defaults for the given event queue name. If the event queue
06230   name is not permitted by the XML configuration, -1 is returned and no
06231   attribute object is created.
06232 
06233   \param attr A pointer to a pointer to a UM event queue attribute structure. Will be
06234     filled in by this function to point to the newly created lbm_event_queue_attr_t object.
06235   \param event_queue_name The event queue name used to lookup this event queue in the XML 
06236     configuration. A NULL value is permitted, and will match unnamed event queues defined
06237         in the XML. The event queue name is also written into the attribute object.
06238   \return 0 for Success and -1 for Failure.
06239 */
06240 LBMExpDLL int lbm_event_queue_attr_create_from_xml(lbm_event_queue_attr_t * * attr, const char * event_queue_name);
06241 
06242 /*! \brief Fill a UM event queue attribute object with the current default values for the given event queue name.
06243 
06244   The attribute object is filled with the default values for the given event queue
06245   name, if an XML configuration file has been loaded.
06246   If the event queue name is not permitted by the XML configuration, -1 is 
06247   returned and no values are set.
06248 
06249   \param attr A pointer to a UM event queue attribute structure. 
06250   \param event_queue_name The event queue name used to lookup this event queue in the XML 
06251     configuration. A NULL value is permitted, and will match unnamed event queues defined
06252         in the XML. The event queue name is also written into the attribute object.
06253   \return 0 for Success and -1 for Failure.
06254 */
06255 LBMExpDLL int lbm_event_queue_attr_set_from_xml(lbm_event_queue_attr_t * attr, const char * event_queue_name);
06256 
06257 /*! \brief Delete an event queue attribute object.
06258 
06259   The attribute object is cleaned up and deleted.
06260 
06261   \param attr Pointer to a UM event queue attribute object as returned by ::lbm_event_queue_attr_create.
06262   \return 0 for Success and -1 for Failure.
06263 */
06264 LBMExpDLL int lbm_event_queue_attr_delete(lbm_event_queue_attr_t *attr);
06265 
06266 /*! \brief Duplicate a UM event queue attribute object.
06267 
06268   A new attribute object is created as a copy of an existing object.
06269 
06270   \param attr A pointer to a pointer to a UM event queue attribute structure. Will be
06271     filled in by this function to point to the newly created lbm_event_queue_attr_t object.
06272   \param original Pointer to a UM event queue attribute object as returned by ::lbm_event_queue_attr_create
06273         or ::lbm_event_queue_attr_create_default, from which \a attr is initialized.
06274   \return 0 for Success and -1 for Failure.
06275 */
06276 LBMExpDLL int lbm_event_queue_attr_dup(lbm_event_queue_attr_t * * attr, const lbm_event_queue_attr_t * original);
06277 
06278 /*! \brief Set an option value within the given event queue attribute.
06279 
06280            Used before the event queue is created.
06281            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
06282 
06283   \param attr Pointer to a UM event queue attribute object where the option is to be set
06284   \param optname String containing the option name
06285   \param optval Pointer to the option value structure. The structure of the option values
06286                 are specific to the options themselves.
06287   \param optlen Length (in bytes) of the \a optval structure.
06288   \return 0 for Success and -1 for Failure.
06289 */
06290 LBMExpDLL int lbm_event_queue_attr_setopt(lbm_event_queue_attr_t *attr, const char *optname,
06291                                                                                   const void *optval, size_t optlen);
06292 
06293 /*! \brief Set an option value within the given event queue attribute.
06294 
06295            Used before the event queue is created.
06296            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
06297 
06298   \param attr Pointer to a UM event queue attribute object where the option is to be set
06299   \param optname String containing the option name
06300   \param optval String containing the option value. The format of the string
06301                 is specific to the options themselves.
06302   \return 0 for Success and -1 for Failure.
06303 */
06304 LBMExpDLL int lbm_event_queue_attr_str_setopt(lbm_event_queue_attr_t *attr, const char *optname,
06305                                                                                           const char *optval);
06306 
06307 /*! \brief Retrieve an option value within the given event queue attribute.
06308   \param attr Pointer to a UM event queue attribute object where the option is stored
06309   \param optname String containing the option name
06310   \param optval Pointer to the option value structure. The structure of the option values
06311                 are specific to the options themselves.
06312   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
06313                 returned, this is the length of the filled in \a optval structure.
06314   \return 0 for Success and -1 for Failure.
06315 */
06316 LBMExpDLL int lbm_event_queue_attr_getopt(lbm_event_queue_attr_t *attr, const char *optname,
06317                                                                                   void *optval, size_t *optlen);
06318 
06319 /*! \brief Retrieve a textual option value within the given event queue attribute.
06320 
06321   \param attr Pointer to a UM event queue attribute object where the option is stored
06322   \param optname String containing the option name
06323   \param optval String to be filled in with the option value.
06324   \param optlen When passed, this is the max length (in bytes) of the string. When
06325                 returned, this is the length of the filled in option value.
06326   \return 0 for Success and -1 for Failure.
06327 */
06328 LBMExpDLL int lbm_event_queue_attr_str_getopt(lbm_event_queue_attr_t *attr, const char *optname,
06329                                                                                           char *optval, size_t *optlen);
06330 
06331 /*! \brief Set an option value within the given \a evq.
06332 
06333            Only those options that can be set during operation may be specified.
06334            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
06335            in The UM Configuration Guide. For API functions that can access any option,
06336            see lbm_event_queue_attr_*().
06337   \param evq Pointer to a UM event queue where the option is to be set
06338   \param optname String containing the option name
06339   \param optval Pointer to the option value structure. The structure of the option values
06340                 are specific to the options themselves.
06341   \param optlen Length (in bytes) of the \a optval structure.
06342   \return 0 for Success and -1 for Failure.
06343 */
06344 LBMExpDLL int lbm_event_queue_setopt(lbm_event_queue_t *evq, const char *optname, const void *optval, size_t optlen);
06345 
06346 /*! \brief Set an option value within the given \a event queue.
06347 
06348            Only those options that can be set during operation may be specified.
06349            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
06350            in The UM Configuration Guide. For API functions that can access any option,
06351            see lbm_event_queue_attr_*().
06352   \param evq Pointer to a UM event queue object where the option is to be set
06353   \param optname String containing the option name
06354   \param optval String containing the option value. The format of the string
06355                 is specific to the options themselves.
06356   \return 0 for Success and -1 for Failure.
06357 */
06358 LBMExpDLL int lbm_event_queue_str_setopt(lbm_event_queue_t *evq, const char *optname, const char *optval);
06359 
06360 /*! \brief Retrieve an option value within the given \a event queue.
06361 
06362   \param evq Pointer to a UM event queue object where the option is stored
06363   \param optname String containing the option name
06364   \param optval Pointer to the option value structure. The structure of the option values
06365                 are specific to the options themselves.
06366   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
06367                 returned, this is the length of the filled in \a optval structure.
06368   \return 0 for Success and -1 for Failure.
06369 */
06370 LBMExpDLL int lbm_event_queue_getopt(lbm_event_queue_t *evq, const char *optname, void *optval, size_t *optlen);
06371 
06372 /*! \brief Retrieve a textual option value within the given \a event queue.
06373 
06374   \param evq Pointer to a UM event queue object where the option is stored
06375   \param optname String containing the option name
06376   \param optval String to be filled in with the option value.
06377   \param optlen When passed, this is the max length (in bytes) of the string. When
06378                 returned, this is the length of the filled in with the option value.
06379   \return 0 for Success and -1 for Failure.
06380 */
06381 LBMExpDLL int lbm_event_queue_str_getopt(lbm_event_queue_t *evq, const char *optname, char *optval, size_t *optlen);
06382 
06383 /*! \brief Dispatch waiting events to appropriate callback functions.
06384 
06385   \param evq Event Queue that holds the events to dispatch.
06386   \param tmo The number of milliseconds to block before returning from the function.
06387                 Note that if no events are posted, the call will continue to block
06388                 even after the time has past. 
06389                 See https://communities.informatica.com/infakb/faq/5/Pages/80007.aspx for details. 
06390                 In addition to numeric values, the following special values are valid:
06391   \arg \c LBM_EVENT_QUEUE_BLOCK - block indefinitely processing events.
06392   \arg \c LBM_EVENT_QUEUE_POLL - poll and dispatch a single event and return.
06393   \return > 0 for Success (number returned is the number of events serviced) or -1 for Failure.
06394 */
06395 LBMExpDLL int lbm_event_dispatch(lbm_event_queue_t *evq, lbm_ulong_t tmo);
06396 
06397 /*! \brief Unblock the given UM event queue object so that a thread waiting in
06398            lbm_event_dispatch returns as soon as feasible.
06399 
06400   This function enqueues a special event into the event queue that,
06401   when processed, causes the thread calling lbm_event_dispatch to return.
06402 
06403   \param evq Event Queue on which to enqueue the UNBLOCK event.
06404   \return 0 for Success and -1 for Failure.
06405 */
06406 LBMExpDLL int lbm_event_dispatch_unblock(lbm_event_queue_t *evq);
06407 
06408 /*! \brief Determine the number of queued events in the event queue.
06409 
06410   This call is only supported when the queue_size_warning config variable is set.
06411   If not set, then this function will return -1 and set an EINVAL error.
06412 
06413   \param evq Event Queue to determine the size for.
06414   \return > 0 indicates the size of the event queue and -1 for Failure.
06415 */
06416 LBMExpDLL int lbm_event_queue_size(lbm_event_queue_t *evq);
06417 
06418 /*! \brief Shutdown the event queue by purging any pending events and not allowing
06419            additional events to be added to the queue.
06420 
06421   \param evq Event Queue to shutdown.
06422   \return 0 for Success and -1 for Failure.
06423 */
06424 LBMExpDLL int lbm_event_queue_shutdown(lbm_event_queue_t *evq);
06425 
06426 /*! \brief Delete a given UM event queue object.
06427   \warning An event queue should not be deleted before all other dependent
06428    objects (source, receivers, and timers using the event queue) have also
06429    been deleted or canceled.
06430   \param evq Event Queue to be deleted.
06431   \return 0 for Success and -1 for Failure.
06432 */
06433 LBMExpDLL int lbm_event_queue_delete(lbm_event_queue_t *evq);
06434 
06435 /*! \brief Unicast an immediate message to the target and topic.
06436            Note that immediate messages are processed somewhat less efficiently
06437            than source-based messages.
06438 
06439   \param ctx Pointer to UM context to send from
06440   \param target Target address of the receiver of the form "TCP:ip:port" or "TCP:domain:ip:port"
06441   \param topic Topic name to send message to or NULL for non-topic. Topic names should be limited
06442                 to 246 characters (not including the final null).
06443   \param data Pointer to the data to send in this message
06444   \param len Length (in bytes) of the data to send in this message.  Unicast
06445              immediate messages must be 65281 bytes or less in length.
06446   \param flags Flags indicating various conditions. ORed set of values.
06447   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
06448           and error and signal LBM_EWOULDBLOCK.
06449   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
06450           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06451           nor LBM_SRC_BLOCK are supplied.)
06452   \return -1 for Failure or 0 for Success.
06453 */
06454 LBMExpDLL int lbm_unicast_immediate_message(lbm_context_t *ctx, const char *target, const char *topic,
06455                                                                                         const char *data, size_t len, int flags);
06456 
06457 /*! \brief Unicast an immediate request to the target and topic.
06458            Note that immediate messages are processed somewhat less efficiently
06459            than source-based messages.
06460 
06461   \param reqp A pointer to a pointer for the lbm_request_t object created to be stored.
06462   \param ctx Pointer to UM context to send from.
06463   \param target Target address of the receiver of the form "TCP:ip:port" or "TCP:domain:ip:port"
06464   \param topic Topic name to send message to or NULL for non-topic. Topic names should be limited
06465                 to 246 characters (not including the final null).
06466   \param data Buffer to be included as data in the request.
06467   \param len Length (in bytes) of the data to send in this message.  Unicast
06468              immediate messages must be 65281 bytes or less in length.
06469   \param proc Pointer to function to call when responses come in for this request.
06470   \param clientd Client data returned in the callback proc \a proc.
06471   \param evq optional Event Queue to place message events on when they occur.
06472          If NULL causes \a proc to be called from context thread.
06473   \param flags Flags used to instruct UM how to handle this message. See \a lbm_unicast_immediate_message
06474                for more information.
06475   \return 0 for Success and -1 for Failure.
06476 */
06477 LBMExpDLL int lbm_unicast_immediate_request(lbm_request_t **reqp, lbm_context_t *ctx, const char *target,
06478                                                                                         const char *topic, const char *data, size_t len,
06479                                                                                         lbm_request_cb_proc proc, void *clientd,
06480                                                                                         lbm_event_queue_t *evq, int flags);
06481 
06482 /*! \brief Submit a message to a given UMQ queue and to a given topic.
06483                         Note that immediate messages are processed somewhat less efficiently than source-based messages.
06484 
06485   \param ctx Pointer to UM context to submit from.
06486   \param qname Queue to submit message to. Queue names should be limited to 246 bytes characters
06487                                 (not including the final NULL).
06488   \param topic Topic name to send message to. Topic names should be limited
06489                 to 246 characters (not including the final NULL).
06490   \param data Pointer to the data to send in this message
06491   \param len Length (in bytes) of the data to send in this message.
06492   \param flags Flags used to instruct UM how to handle this message. See \a lbm_unicast_immediate_message
06493                for more information.
06494   \param info Pointer to lbm_src_send_ex_info_t options
06495   \return 0 for Success and -1 for Failure.
06496 */
06497 LBMExpDLL int lbm_queue_immediate_message(lbm_context_t *ctx, const char *qname, const char *topic, const char *data,
06498                                                                                   size_t len, int flags, lbm_src_send_ex_info_t *info);
06499 
06500 /*! \brief Multicast an immediate message to the topic.
06501            Note that immediate messages are processed somewhat less efficiently
06502            than source-based messages.
06503 
06504   \warning Multicast immediate messages are NOT guaranteed to maintain order.
06505            A loss-recovery event can lead to messages received out of order.
06506   \param ctx Pointer to UM context to send from
06507   \param topic Topic name to send message to or NULL for non-topic. Topic names should be limited
06508                 to 246 characters (not including the final null).
06509   \param data Pointer to the data to send in this message
06510   \param len Length (in bytes) of the data to send in this message.  Multicast
06511              immediate messages must be 7866 bytes or less in length.
06512   \param flags Flags indicating various conditions. ORed set of values.
06513   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
06514           and error and signal LBM_EWOULDBLOCK.
06515   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
06516           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06517           nor LBM_SRC_BLOCK are supplied.)
06518   \arg \c LBM_MSG_FLUSH - Messages are to be sent ASAP (not implicitly batched).
06519   \return -1 for Failure or 0 for Success.
06520 */
06521 LBMExpDLL int lbm_multicast_immediate_message(lbm_context_t *ctx, const char *topic,
06522                                                                                           const char *data, size_t len, int flags);
06523 
06524 /*! \brief Multicast an immediate request to the target and topic.
06525            Note that immediate messages are processed somewhat less efficiently
06526            than source-based messages.
06527   \warning Multicast immediate messages are NOT guaranteed to maintain order.
06528            A loss-recovery event can lead to messages received out of order.
06529   \param reqp A pointer to a pointer for the lbm_request_t object created to be stored.
06530   \param ctx Pointer to UM context to send from.
06531   \param topic Topic name to send message to or NULL for non-topic. Topic names should be limited
06532                 to 246 characters (not including the final null).
06533   \param data Buffer to be included as data in the request.
06534   \param len Length (in bytes) of the data to send in this message.  Multicast
06535              immediate messages must be 7866 bytes or less in length.
06536   \param proc Pointer to function to call when responses come in for this request.
06537   \param clientd Client data returned in the callback proc \a proc.
06538   \param evq Optional Event Queue to place message events on when they occur.
06539          If NULL causes \a proc to be called from context thread.
06540   \param flags Flags used to instruct UM how to handle this message. See \a lbm_multicast_immediate_message
06541                for more information.
06542   \return 0 for Success and -1 for Failure.
06543 */
06544 LBMExpDLL int lbm_multicast_immediate_request(lbm_request_t **reqp, lbm_context_t *ctx,
06545                                                                                           const char *topic, const char *data,
06546                                                                                           size_t len, lbm_request_cb_proc proc,
06547                                                                                           void *clientd, lbm_event_queue_t *evq,
06548                                                                                           int flags);
06549 
06550 /*! \brief Retrieves all wildcard receiver attribute options.
06551 
06552         The config object is filled with wildcard receiver configuration options
06553         \param wrcv The wildcard receiver object to retrieve the attributes from
06554         \param size Size of the opts array. Will return the number of items that were set in opts
06555         \param opts The options array to fill
06556         */
06557 LBMExpDLL int lbm_wildcard_rcv_dump(lbm_wildcard_rcv_t *wrcv, int *size, lbm_config_option_t *opts);
06558 
06559 /*! \brief Retrieves all wildcard receiver attribute options.
06560 
06561         The config object is filled with wildcard receiver configuration options
06562         \param wattr The wildcard receiver attribute object to retrieve the attributes from
06563         \param size Size of the opts array. Will return the number of items that were set in opts
06564         \param opts The options array to fill
06565         */
06566 LBMExpDLL int lbm_wildcard_rcv_attr_dump(lbm_wildcard_rcv_attr_t *wattr, int *size, lbm_config_option_t *opts);
06567 
06568 /*! \brief Retrieves the number of options that are of type "wildcard receiver"
06569 
06570         The function returns the number of entries that are of type "wildcard receiver"
06571 
06572         \return The number of entries that are of type "wildcard receiver"
06573 */
06574 LBMExpDLL int lbm_wildcard_rcv_attr_option_size();
06575 
06576 
06577 /*! \brief Create and fill a UM wildcard receiver attribute object with the current default values.
06578 
06579   The attribute object is allocated and filled with the current default values that are
06580   used by lbm_wildcard_rcv_t objects and may have been modified by a previously loaded configuration file.
06581 
06582   \param attr A pointer to a pointer to a UM wildcard receiver attribute structure. Will be
06583     filled in by this function to point to the newly created lbm_wildcard_rcv_attr_t object.
06584   \return 0 for Success and -1 for Failure.
06585 */
06586 LBMExpDLL int lbm_wildcard_rcv_attr_create(lbm_wildcard_rcv_attr_t * * attr);
06587 
06588 /*! \brief Create and fill a UM wildcard receiver attribute object with the initial default values.
06589 
06590   The attribute object is allocated and filled with the initial or factory default values built into LBM
06591   that are used by lbm_wildcard_rcv_t.
06592 
06593   \param attr A pointer to a pointer to a UM wildcard receiver attribute structure. Will be
06594     filled in by this function to point to the newly created lbm_wildcard_rcv_attr_t object.
06595   \return 0 for Success and -1 for Failure.
06596 */
06597 LBMExpDLL int lbm_wildcard_rcv_attr_create_default(lbm_wildcard_rcv_attr_t * * attr);
06598 
06599 /*! \brief Create and fill a UM wildcard receiver attribute object with the current default values for the given topic name.
06600 
06601   The attribute object is allocated and filled with the current default values that are
06602   used by lbm_topic_t objects that concern receivers and may have been modified by 
06603   a previously loaded configuration file.
06604   If an XML configuration file has been loaded, the attribute object is
06605   further filled with the defaults for the given context name and wildcard receiver 
06606   pattern. If the context name or wildcard receiver pattern are not permitted by the XML 
06607   configuration, -1 is returned and no attribute object is created.
06608 
06609   \param attr A pointer to a pointer to a UM wildcard receiver attribute structure. Will be
06610     filled in by this function to point to the newly created lbm_wildcard_rcv_attr_t object.
06611   \param context_name The context name used to lookup the wildcard receiver pattern in the XML 
06612     configuration. A NULL value is permitted, and will match unnamed contexts defined
06613         in the XML.
06614   \param pattern The pattern used to lookup the wildcard receiver in the XML
06615     configuration. A NULL value is *not* permitted and will result in an error.
06616   \param pattern_type They type of pattern. Both pattern_type and pattern must match in XML configuration.
06617   \return 0 for Success and -1 for Failure.
06618 */
06619 LBMExpDLL int lbm_wildcard_rcv_attr_create_from_xml(lbm_wildcard_rcv_attr_t * * attr, const char * context_name, const char * pattern, int pattern_type);
06620 
06621 /*! \brief Fill a UM wildcard receiver attribute object with the current default values for the given topic name.
06622 
06623   The attribute object is filled with the defaults for the given context name,
06624   wildcard pattern, and pattern_type, if an XML configuration file has been loaded. If the 
06625   context name or pattern and pattern_type combination are are not permitted by the XML 
06626   configuration, -1 is returned and the attribute object is not written to.
06627 
06628   \param attr A pointer to a UM wildcard receiver attribute structure.
06629   \param context_name The context name used to lookup the wildcard receiver pattern in the XML 
06630     configuration. A NULL value is permitted, and will match unnamed contexts defined
06631         in the XML.
06632   \param pattern The pattern used to lookup the wildcard receiver in the XML
06633     configuration. A NULL value is *not* permitted and will result in an error.
06634   \param pattern_type They type of pattern. Both pattern_type and pattern must match in XML configuration.
06635   \return 0 for Success and -1 for Failure.
06636 */
06637 LBMExpDLL int lbm_wildcard_rcv_attr_set_from_xml(lbm_wildcard_rcv_attr_t * attr, const char * context_name, const char * pattern, int pattern_type);
06638 
06639 /*! \brief Delete a wildcard receiver attribute object.
06640 
06641   The attribute object is cleaned up and deleted.
06642 
06643   \param attr Pointer to a UM wildcard receiver attribute object as returned by ::lbm_wildcard_rcv_attr_create.
06644   \return 0 for Success and -1 for Failure.
06645 */
06646 LBMExpDLL int lbm_wildcard_rcv_attr_delete(lbm_wildcard_rcv_attr_t *attr);
06647 
06648 /*! \brief Duplicate a UM wildcard receiver attribute object.
06649 
06650   A new attribute object is created as a copy of an existing object.
06651 
06652   \param attr A pointer to a pointer to a UM wildcard receiver attribute structure. Will be
06653     filled in by this function to point to the newly created lbm_wildcard_rcv_attr_t object.
06654   \param original Pointer to a UM wildcard receiver attribute object as returned by
06655     ::lbm_wildcard_rcv_attr_create or ::lbm_wildcard_rcv_attr_create_default, from which \a attr is initialized.
06656   \return 0 for Success and -1 for Failure.
06657 */
06658 LBMExpDLL int lbm_wildcard_rcv_attr_dup(lbm_wildcard_rcv_attr_t * * attr, const lbm_wildcard_rcv_attr_t * original);
06659 
06660 /*! \brief Set an option value within the given wildcard receiver attribute.
06661 
06662            Used before the wildcard receiver is created.
06663            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
06664 
06665   \param attr Pointer to a UM wildcard receiver attribute object where the option is to be set
06666   \param optname String containing the option name
06667   \param optval Pointer to the option value structure. The structure of the option values
06668                 are specific to the options themselves.
06669   \param optlen Length (in bytes) of the \a optval structure.
06670   \return 0 for Success and -1 for Failure.
06671 */
06672 LBMExpDLL int lbm_wildcard_rcv_attr_setopt(lbm_wildcard_rcv_attr_t *attr, const char *optname,
06673                                                                                    const void *optval, size_t optlen);
06674 
06675 /*! \brief Set an option value within the given wildcard receiver attribute.
06676 
06677            Used before the wildcard receiver is created.
06678            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
06679 
06680   \param attr Pointer to a UM wildcard receiver attribute object where the option is to be set
06681   \param optname String containing the option name
06682   \param optval String containing the option value. The format of the string
06683                 is specific to the options themselves.
06684   \return 0 for Success and -1 for Failure.
06685 */
06686 LBMExpDLL int lbm_wildcard_rcv_attr_str_setopt(lbm_wildcard_rcv_attr_t *attr, const char *optname,
06687                                                                                            const char *optval);
06688 
06689 /*! \brief Retrieve an option value within the given wildcard receiver attribute.
06690   \param attr Pointer to a UM wildcard receiver attribute object where the option is stored
06691   \param optname String containing the option name
06692   \param optval Pointer to the option value structure. The structure of the option values
06693                 are specific to the options themselves.
06694   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
06695                 returned, this is the length of the filled in \a optval structure.
06696   \return 0 for Success and -1 for Failure.
06697 */
06698 LBMExpDLL int lbm_wildcard_rcv_attr_getopt(lbm_wildcard_rcv_attr_t *attr, const char *optname,
06699                                                                                    void *optval, size_t *optlen);
06700 
06701 /*! \brief Retrieve a textual option value within the given wildcard receiver attribute.
06702 
06703   \param attr Pointer to a UM wildcard receiver attribute object where the option is stored
06704   \param optname String containing the option name
06705   \param optval String to be filled in with the option value.
06706   \param optlen When passed, this is the max length (in bytes) of the string. When
06707                 returned, this is the length of the filled in option value.
06708   \return 0 for Success and -1 for Failure.
06709 */
06710 LBMExpDLL int lbm_wildcard_rcv_attr_str_getopt(lbm_wildcard_rcv_attr_t *attr, const char *optname,
06711                                                                                            char *optval, size_t *optlen);
06712 
06713 /*! \brief Set an option value within the given \a wrcv.
06714 
06715            Only those options that can be set during operation may be specified.
06716            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
06717            in The UM Configuration Guide. For API functions that can access any option,
06718            see lbm_wildcard_rcv_attr_*().
06719   \param wrcv Pointer to a UM wildcard receiver object where the option is to be set.
06720   \param optname String containing the option name.
06721   \param optval Pointer to the option value structure. The structure of the option values
06722                 are specific to the options themselves.
06723   \param optlen Length (in bytes) of the \a optval structure.
06724   \return 0 for Success and -1 for Failure.
06725 */
06726 LBMExpDLL int lbm_wildcard_rcv_setopt(lbm_wildcard_rcv_t *wrcv, const char *optname, const void *optval, size_t optlen);
06727 
06728 /*! \brief Set an option value within the given \a wrcv.
06729 
06730            Only those options that can be set during operation may be specified.
06731            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
06732            in The UM Configuration Guide. For API functions that can access any option,
06733            see lbm_wildcard_rcv_attr_*().
06734   \param wrcv Pointer to a UM wildcard receiver object where the option is to be set.
06735   \param optname String containing the option name.
06736   \param optval String containing the option value. The format of the string
06737                 is specific to the options themselves.
06738   \return 0 for Success and -1 for Failure.
06739 */
06740 LBMExpDLL int lbm_wildcard_rcv_str_setopt(lbm_wildcard_rcv_t *wrcv, const char *optname, const char *optval);
06741 
06742 /*! \brief Retrieve an option value within the given \a wrcv.
06743 
06744   \param wrcv Pointer to a UM wildcard receiver object where the option is stored.
06745   \param optname String containing the option name.
06746   \param optval Pointer to the option value structure. The structure of the option values
06747                 are specific to the options themselves.
06748   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
06749                 returned, this is the length of the filled in \a optval structure.
06750   \return 0 for Success and -1 for Failure.
06751 */
06752 LBMExpDLL int lbm_wildcard_rcv_getopt(lbm_wildcard_rcv_t *wrcv, const char *optname, void *optval, size_t *optlen);
06753 
06754 /*! \brief Retrieve the textual option value within the given \a wrcv.
06755 
06756   \param wrcv Pointer to a UM wildcard receiver object where the option is stored.
06757   \param optname String containing the option name.
06758   \param optval String to hold the option value.
06759   \param optlen When passed, this is the max length (in bytes) of the string. When
06760                 returned, this is the length of the filled in option value.
06761   \return 0 for Success and -1 for Failure.
06762 */
06763 LBMExpDLL int lbm_wildcard_rcv_str_getopt(lbm_wildcard_rcv_t *wrcv, const char *optname, char *optval, size_t *optlen);
06764 
06765 /*! \brief Create a UM wildcard receiver that will receive messages sent to any topic matching
06766            the given pattern.  Note that if wildcard queries are enabled,
06767            LBM will query a maximum of 250 patterns (receivers).
06768 
06769   The callback \a proc will be called to deliver data sent to the
06770   topics that the receiver has requested.
06771 
06772   \warning It is not safe to call this function from a context thread callback.
06773   \param wrcvp A pointer to a pointer to a UM wildcard receiver object. Will be filled in
06774               by this function to point to the newly created lbm_wildcard_rcv_t object.
06775   \param ctx Pointer to the LBM context object associated with the wildcard receiver.
06776   \param pattern Pattern to match the topic strings on for this wildcard. This is by default
06777                  a regular expression. But more options may be supported.
06778   \param tattr Pointer to a UM receive topic attribute structure used for specifying attributes
06779                for topics created for this wildcard receiver.
06780   \param wattr Pointer to a UM wildcard receiver attribute structure specifying the options for
06781                this wildcard receiver.
06782   \param proc Pointer to a function to call when messages arrive.
06783   \param clientd Pointer to client data that is passed when data arrives and \a proc is called.
06784   \param evq Optional Event Queue to place message events on when they arrive.
06785          If NULL causes \a proc to be called from context thread.
06786   \return 0 for Success and -1 for Failure.
06787 */
06788 LBMExpDLL int lbm_wildcard_rcv_create(lbm_wildcard_rcv_t **wrcvp, lbm_context_t *ctx, const char *pattern,
06789                                                                           const lbm_rcv_topic_attr_t *tattr, const lbm_wildcard_rcv_attr_t *wattr,
06790                                                         lbm_rcv_cb_proc proc, void *clientd, lbm_event_queue_t *evq);
06791 
06792 /*! \brief Delete a UM wildcard receiver object.
06793 
06794   Delete a UM wildcard receiver object. Note that this 
06795   function can return while the receiver callback may still be executing if receiver events 
06796   are being delivered via an event queue. If the application needs to know when
06797   all possible processing on the receiver is complete, it must use
06798   lbm_wildcard_rcv_delete_ex().
06799 
06800   \warning It is not safe to call this function from a context thread callback.
06801   \param wrcv Pointer to a UM wildcard receiver object to delete.
06802   \return 0 for Success and -1 for Failure.
06803 */
06804 LBMExpDLL int lbm_wildcard_rcv_delete(lbm_wildcard_rcv_t *wrcv);
06805 
06806 /*! \brief Extended delete a UM wildcard receiver object.
06807 
06808   Delete a UM wildcard receiver object, with an application callback
06809   indicating when the receiver is fully canceled.  This extended version of
06810   the receiver delete function requires the configuration option
06811   queue_cancellation_callbacks_enabled be set to 1.
06812 
06813   \warning It is not safe to call this function from a context thread callback.
06814   \param wrcv Pointer to a UM wildcard receiver object to delete.
06815   \param cbinfo Cancellation callback information, containing the event
06816                 queue, function pointer, and client data for the callback.
06817   \return 0 for Success and -1 for Failure.
06818 */
06819 LBMExpDLL int lbm_wildcard_rcv_delete_ex(lbm_wildcard_rcv_t *wrcv,
06820                                                                                  lbm_event_queue_cancel_cb_info_t *cbinfo);
06821 
06822 /*!     \brief Retrieve the LBM context object associated with a UM wildcard receiver object.
06823 
06824         \param wcrcv Pointer to a UM wildcard receiver object.
06825         \return A pointer to the LBM context object associated with the LBM wildcard
06826                 receiver object.
06827 */
06828 LBMExpDLL lbm_context_t * lbm_context_from_wildcard_rcv(lbm_wildcard_rcv_t * wcrcv);
06829 
06830 /*!     \brief Retrieve the LBM event queue object associated with a UM wildcard receiver object.
06831 
06832         \param wcrcv Pointer to a UM wildcard receiver object.
06833         \return A pointer to the LBM event queue object associated with the LBM wildcard
06834                 receiver object.
06835 */
06836 LBMExpDLL lbm_event_queue_t * lbm_event_queue_from_wildcard_rcv(lbm_wildcard_rcv_t * wcrcv);
06837 
06838 /*! \brief Create a UM Hot Failover (HF) source that will send messages to the given \a topic.  
06839 See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
06840 
06841   \sa lbm_src_create
06842   \warning It is not safe to call this function from a context thread callback.
06843   \param srcp A pointer to a pointer to a UM source object. Will be filled in
06844               by this function to point to the newly created lbm_src_t object.
06845   \param ctx Pointer to the LBM context object associated with the sender.
06846   \param topic Pointer to the LBM topic object associated with the destination
06847                of messages sent by the source.
06848   \param proc Pointer to a function to call when events occur related to the source.
06849               If NULL, then events are not delivered to the source.
06850   \param clientd Pointer to client data that is passed when \a proc is called.
06851   \param evq Optional Event Queue to place events on when they occur.
06852          If NULL causes \a proc to be called from context thread.
06853   \return 0 for Success and -1 for Failure.
06854 */
06855 LBMExpDLL int lbm_hf_src_create(lbm_src_t **srcp, lbm_context_t *ctx, lbm_topic_t *topic, lbm_src_cb_proc proc,
06856                                                                 void *clientd, lbm_event_queue_t *evq);
06857 
06858 /*! \brief Send a Hot Failover (HF) message to the topic associated with a UM source. See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
06859 
06860   The LBM source must have been created with lbm_hf_src_create and not lbm_src_create
06861   \sa lbm_src_send
06862 
06863   \warning It is not recommended to call this function from a context thread callback. If called 
06864   from a context thread callback, use the LBM_SRC_NONBLOCK flag and handle any LBM_EWOULDBLOCK 
06865   errors internally.
06866   \param src Pointer to the LBM source to send from
06867   \param msg Pointer to the data to send in this message
06868   \param len Length (in bytes) of the data to send in this message
06869   \param sqn The application sequence number to associate with this message.
06870   \param flags Flags indicating various conditions. ORed set of values.
06871   \arg \c LBM_MSG_START_BATCH - Message starts a batch of messages
06872   \arg \c LBM_MSG_END_BATCH - Message ends a batch of messages.
06873           Batch should be sent to the implicit batching buffer.
06874   \arg \c LBM_MSG_COMPLETE_BATCH - Message constitutes a complete batch
06875           and should be sent to the implicit batching buffer.
06876   \arg \c LBM_MSG_FLUSH - Message is to be sent ASAP (not implicitly or explicitly batched).
06877           This also flushes waiting messages that were explicitly or implicitly batched.
06878   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
06879           and error and signal LBM_EWOULDBLOCK.
06880   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
06881           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06882           nor LBM_SRC_BLOCK are supplied.)
06883   \return -1 for Failure or 0 for Success.
06884 */
06885 LBMExpDLL int lbm_hf_src_send(lbm_src_t *src, const char *msg, size_t len, lbm_uint_t sqn, int flags);
06886 
06887 /*! \brief Send a Hot Failover (HF) message to the topic associated with a UM source.  See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
06888 
06889   The LBM source must have been created with lbm_hf_src_create and not lbm_src_create
06890   \sa lbm_src_send_ex
06891 
06892   \warning  If called from a context thread callback, use the LBM_SRC_NONBLOCK flag and 
06893   handle any LBM_EWOULDBLOCK errors internally.
06894   \warning Calling this function from a context thread
06895   callback for stability and confirmation events could cause a deadlock
06896   \param src Pointer to the LBM source to send from
06897   \param msg Pointer to the data to send in this message
06898   \param len Length (in bytes) of the data to send in this message
06899   \param sqn The application sequence number to associate with this message.
06900   \param flags Flags indicating various conditions. ORed set of values.
06901   \arg \c LBM_MSG_START_BATCH - Message starts a batch of messages
06902   \arg \c LBM_MSG_END_BATCH - Message ends a batch of messages.
06903           Batch should be sent to the implicit batching buffer.
06904   \arg \c LBM_MSG_COMPLETE_BATCH - Message constitutes a complete batch
06905           and should be sent to the implicit batching buffer.
06906   \arg \c LBM_MSG_FLUSH - Message is to be sent ASAP (not implicitly or explicitly batched).
06907           This also flushes waiting messages that were explicitly or implicitly batched.
06908   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
06909           and error and signal LBM_EWOULDBLOCK.
06910   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
06911           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06912           nor LBM_SRC_BLOCK are supplied.)
06913   \param exinfo Pointer to lbm_src_send_ex_info_t options that includes the 32 or 64 bit hot-failover sequence number to send.
06914   \return -1 for Failure or 0 for Success.
06915 */
06916 LBMExpDLL int lbm_hf_src_send_ex(lbm_src_t *src, const char *msg, size_t len, lbm_uint_t sqn, int flags, lbm_src_send_ex_info_t *exinfo);
06917 
06918 /*! \brief Send a set of Hot Failover (HF) messages to the topic associated with a UM source. See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
06919 
06920   The LBM source must have been created with lbm_hf_src_create and not lbm_src_create.
06921   The message is specified as an array of iovecs.
06922 
06923   NOTE: Unlike lbm_src_sendv, which by default sends N number of messages where N is
06924   the length of the iovec; lbm_hf_src_sendv will gather the elements of the array
06925   into one message.
06926   \sa lbm_hf_src_sendv
06927 
06928   \warning It is not recommended to call this function from a context thread callback. If called 
06929   from a context thread callback, use the LBM_SRC_NONBLOCK flag and handle any LBM_EWOULDBLOCK 
06930   errors internally.
06931   \param src Pointer to the LBM source to send from.
06932   \param iov Pointer to an array of iovecs that hold message information.
06933   \param num Number of elements of the iov array to send.
06934   \param sqn The application sequence number to associate with this message.
06935   \param flags Flags indicating various conditions. ORed set of values.
06936   \arg \c LBM_MSG_START_BATCH - Messages start a batch of messages
06937   \arg \c LBM_MSG_END_BATCH - Messages end a batch of messages.
06938           Batch should be sent to the implicit batching buffer.
06939   \arg \c LBM_MSG_COMPLETE_BATCH - Messages constitute a complete batch
06940           and should be sent to the implicit batching buffer.
06941   \arg \c LBM_MSG_FLUSH - Messages are to be sent ASAP (not implicitly batched or explicitly batched).
06942   \arg \c LBM_SRC_NONBLOCK - If messages could not be sent immediately return
06943           and error and signal LBM_EWOULDBLOCK.
06944   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the messages
06945           are all sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06946           nor LBM_SRC_BLOCK are supplied.)
06947   \return -1 for Failure or 0 for Success.
06948 */
06949 LBMExpDLL int lbm_hf_src_sendv(lbm_src_t *src, const lbm_iovec_t *iov, int num, lbm_uint_t sqn, int flags);
06950 
06951 /*! \brief Retrieves all receiver attribute options for an HF receiver.
06952 
06953         The config object is filled with receiver configuration options
06954         \param hfrcv The HF receiver object to retrieve the attributes from
06955         \param size Size of the opts array. Will return the number of items that were set in opts
06956         \param opts The options array to fill
06957         */
06958 LBMExpDLL int lbm_hf_rcv_topic_dump(lbm_hf_rcv_t *hfrcv, 
06959                                                                         int *size, 
06960                                                                         lbm_config_option_t *opts);
06961 
06962 /*! \brief Extended send of a set of Hot Failover (HF) messages to the topic associated with a UM source.
06963 
06964   The LBM source must have been created with lbm_hf_src_create and not lbm_src_create.
06965   The message is specified as an array of iovecs.
06966 
06967   NOTE: Unlike lbm_src_sendv, which by default sends N number of LBM Messages where N is
06968   the length of the iovec array; lbm_hf_src_sendv will gather the elements of the array
06969   into a single message.
06970   \sa lbm_hf_src_sendv_ex
06971 
06972   \warning  If called from a context thread callback, use the LBM_SRC_NONBLOCK flag and 
06973   handle any LBM_EWOULDBLOCK errors internally.
06974   \warning Calling this function from a context thread
06975   callback for stability and confirmation events could cause a deadlock
06976   \param src Pointer to the LBM source to send from
06977   \param iov Pointer to an array of iovecs that hold message information.
06978   \param num Number of elements of the iov array to send.
06979   \param sqn The application sequence number to associate with this message.
06980   \param flags Flags indicating various conditions. ORed set of values.
06981   \arg \c LBM_MSG_START_BATCH - Message starts a batch of messages
06982   \arg \c LBM_MSG_END_BATCH - Message ends a batch of messages.
06983           Batch should be sent to the implicit batching buffer.
06984   \arg \c LBM_MSG_COMPLETE_BATCH - Message constitutes a complete batch
06985           and should be sent to the implicit batching buffer.
06986   \arg \c LBM_MSG_FLUSH - Message is to be sent ASAP (not implicitly or explicitly batched).
06987           This also flushes waiting messages that were explicitly or implicitly batched.
06988   \arg \c LBM_SRC_NONBLOCK - If message could not be sent immediately return
06989           and error and signal LBM_EWOULDBLOCK.
06990   \arg \c LBM_SRC_BLOCK - Block the caller indefinitely until the message
06991           is sent.  (This behavior is the default if neither LBM_SRC_NONBLOCK
06992           nor LBM_SRC_BLOCK are supplied.)
06993   \param exinfo Pointer to lbm_src_send_ex_info_t options which includes the 32 or 64 bit hot-failover sequence number to send.
06994   \return -1 for Failure or 0 for Success.
06995 */
06996 LBMExpDLL int lbm_hf_src_sendv_ex(lbm_src_t *src, const lbm_iovec_t *iov, int num, lbm_uint_t sqn, int flags, lbm_src_send_ex_info_t *exinfo);
06997 
06998 /*! \brief Send a message that will reset order and loss information for hot failover receivers on this topic.
06999 
07000         Send a message that instructs hot-failover receivers to reset their state. In, and only in, the case that hf receivers
07001         cannot be manually restarted, this function can be used to allow delivering of previously sent sequence numbers. The
07002         hot-failover receiver will deliver a message of type LBM_MSG_HF_RESET and will include the new expected sequence number.
07003         The sequence number contained with the reset will be used as the next expected sequence number to be sent. The LBM source 
07004         must have been created with lbm_hf_src_create and not lbm_src_create.
07005 
07006         NOTE: The best way to reset a hot-failover receiver's state is to restart the receiver itself. This function should be used
07007         only when that is impossible. 
07008 
07009         \param src Pointer to the LBM source to send from, must be a hot failover source
07010         \param exinfo Pointer to the lbm_src_send_ex_info_t containing the hf sequence number
07011         \return -1 for Failure or 0 for Success
07012 */
07013 LBMExpDLL int lbm_hf_src_send_rcv_reset(lbm_src_t * src, int flags, lbm_src_send_ex_info_t * exinfo);
07014 
07015 /*! \brief Create and LBM receiver that will receive LBM Hot Failover (HF) messages sent to the given \a topic.  See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
07016 
07017   \warning It is not safe to call this function from a context thread callback.
07018   \sa lbm_rcv_create
07019   \param hfrcvp A pointer to a pointer to a UM Hot Failover (HF) receiver object. Will be filled
07020                 in by this function to point to the newly created lbm_fd_rcv_t object.
07021   \param ctx Pointer to the LBM context object associated with the sender.
07022   \param topic Pointer to the LBM topic object associated with the desired receiver topic.
07023   \warning Topic references should not be reused. Each lbm_hf_rcv_create() call
07024                should be preceded by a call to lbm_rcv_topic_lookup().
07025   \param proc Pointer to a function to call when messages arrive.
07026   \param clientd Pointer to client data that is passed when data arrives and \a proc is called.
07027   \param evq Optional Event Queue to place message events on when they arrive.
07028          If NULL causes \a proc to be called from context thread.
07029   \return 0 for Success and -1 for Failure.
07030 */
07031 LBMExpDLL int lbm_hf_rcv_create(lbm_hf_rcv_t **hfrcvp, lbm_context_t *ctx, lbm_topic_t *topic, lbm_rcv_cb_proc proc,
07032                                                                 void *clientd, lbm_event_queue_t *evq);
07033 
07034 /*! \brief Delete a UM Hot Failover (HF) receiver object.  See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
07035 
07036   Delete a UM Hot Failover (HF) receiver object. Note that this 
07037   function can return while the receivercallback may still be executing if receiver events 
07038   are being delivered via an event queue. If the application needs to know when
07039   all possible processing on the receiver is complete, it must use
07040   lbm_hf_rcv_delete_ex().
07041 
07042   \warning It is not safe to call this function from a context thread callback.
07043   \param hfrcv Pointer to a UM HF receiver object to delete.
07044   \return 0 for Success and -1 for Failure.
07045 */
07046 LBMExpDLL int lbm_hf_rcv_delete(lbm_hf_rcv_t *hfrcv);
07047 
07048 /*! \brief Extended delete a UM Hot Failover (HF) receiver object.  See https://communities.informatica.com/infakb/faq/5/Pages/80060.aspx for details and restrictions.
07049 
07050   Delete a UM Hot Failover (HF) receiver object, with
07051   an application callback indicating when the receiver is fully canceled.
07052   This extended version of the receiver delete function requires the
07053   configuration option queue_cancellation_callbacks_enabled be set to 1.
07054 
07055   \warning It is not safe to call this function from a context thread callback.
07056   \param hfrcv Pointer to a UM HF receiver object to delete.
07057   \param cbinfo Cancellation callback information, containing the event
07058                 queue, function pointer, and client data for the callback.
07059   \return 0 for Success and -1 for Failure.
07060 */
07061 LBMExpDLL int lbm_hf_rcv_delete_ex(lbm_hf_rcv_t *hfrcv, lbm_event_queue_cancel_cb_info_t *cbinfo);
07062 
07063 /*! \brief Return the LBM Hot Failover (HF) receiver object (if any) from a UM receiver object.
07064 
07065   \param rcv Pointer to a UM receiver object.
07066   \return Pointer to a UM HF receiver for the receiver object or NULL if none exists.
07067 */
07068 LBMExpDLL lbm_hf_rcv_t *lbm_hf_rcv_from_rcv(lbm_rcv_t *rcv);
07069 
07070 /*! \brief Return the LBM receiver object associated with a UM Hot Failover (HF) receiver object.
07071 
07072   \param hfrcv Pointer to a UM HF receiver object.
07073   \return Pointer to a UM receiver for the LBM HF receiver object.
07074 */
07075 LBMExpDLL lbm_rcv_t *lbm_rcv_from_hf_rcv(lbm_hf_rcv_t *hfrcv);
07076 
07077 
07078 /*! \brief Retrieves all HFX attribute options.
07079 
07080         The config object is filled with HFX configuration options
07081         \param hfx The HFX object to retrieve the attributes from
07082         \param size Size of the opts array. Will return the number of items that were set in opts
07083         \param opts The options array to fill
07084         */
07085 LBMExpDLL int lbm_hfx_dump(lbm_hfx_t *hfx, int *size, lbm_config_option_t *opts);
07086 
07087 /*! \brief Retrieves all HFX attribute options.
07088 
07089         The config object is filled with HFX configuration options
07090         \param cattr The HFX attribute object to retrieve the attributes from
07091         \param size Size of the opts array. Will return the number of items that were set in opts
07092         \param opts The options array to fill
07093         */
07094 LBMExpDLL int lbm_hfx_attr_dump(lbm_hfx_attr_t *attr, int *size, lbm_config_option_t *opts);
07095 
07096 /*! \brief Retrieves the number of options that are of type "hfx".
07097         The function returns the number of entries that are of type "hfx"
07098         \return The number of entries that are of type "hfx"
07099  */
07100 LBMExpDLL int lbm_hfx_attr_option_size();
07101 
07102 /*! \brief Create and fill a UM HFX attribute object with the current default values.
07103 
07104         The attribute object is allocated and filled with the current default values that are used
07105         by lbm_hfx_t objects and may have been modified by a previously loaded configuration
07106         file.
07107 
07108         \param attr A pointer to a pointer to a UM hfx attributes structure.  Will be
07109                 filled in by this function to point to the newly created lbm_hfx_attr_t object.
07110         \return 0 for Success and -1 for Failure
07111 */
07112 LBMExpDLL int lbm_hfx_attr_create(lbm_hfx_attr_t **attr);
07113 
07114 /*! \brief Create and fill a UM HFX attribute object with the initial default values.
07115         
07116         The attribute object is allocated and filled with the initial or factory default values built into
07117         LBM that are used by lbm_hfx_t objects.
07118 
07119         \param attr A pointer to a pointer to a UM hfx attribute structure.  Will be filled
07120                 in by this function to point to the newly created lbm_hfx_attr_t object.
07121         \return 0 for Success and -1 for Failure
07122 */
07123 LBMExpDLL int lbm_hfx_attr_create_default(lbm_hfx_attr_t **attr);
07124 
07125 /*! \brief Create and fill a UM hfx attribute object with the current default values for the given topic name.
07126 
07127   The attribute object is allocated and filled with the current default values 
07128   that are used by lbm_hfx_t objects and may have been modified by a 
07129   previously loaded configuration file.
07130   Then, if an XML configuration file has been loaded, the attribute object is
07131   further filled with the defaults for the given topic name. If the topic
07132   name is not permitted by the XML configuration, -1 is returned and no
07133   attribute object is created.
07134 
07135   \param attr A pointer to a pointer to a UM hfx attribute structure. Will be
07136     filled in by this function to point to the newly created lbm_hfx_attr_t object.
07137   \param topicname The topic name used to lookup this topic in the XML 
07138     configuration.
07139   \return 0 for Success and -1 for Failure.
07140 */
07141 LBMExpDLL int lbm_hfx_attr_create_from_xml(lbm_hfx_attr_t * * attr, const char * topicname);
07142 
07143 /*! \brief Fill a UM hfx attribute object with the current default values for the given topic name.
07144 
07145   The attribute object is filled with the default values for the given topic
07146   name, if an XML configuration file has been loaded.
07147   If the topic name is not permitted by the XML configuration, -1 is 
07148   returned and no values are set.
07149 
07150   \param attr A pointer to a UM hfx attribute structure. 
07151   \param topicname The topic name used to lookup this topic in the XML 
07152     configuration.
07153   \return 0 for Success and -1 for Failure.
07154 */
07155 LBMExpDLL int lbm_hfx_attr_set_from_xml(lbm_hfx_attr_t * attr, const char * topicname);
07156 
07157 /*! \brief Delete a UM hfx attribute object.
07158 
07159   The attribute object is cleaned up and deleted.
07160 
07161   \param attr Pointer to a UM hfx attribute object as returned by ::lbm_hfx_attr_create.
07162   \return 0 for Success and -1 for Failure.
07163 */
07164 LBMExpDLL int lbm_hfx_attr_delete(lbm_hfx_attr_t *attr);
07165 
07166 /*! \brief Duplicate a UM hfx attribute object.
07167 
07168   A new attribute object is created as a copy of an existing object.
07169 
07170   \param attr A pointer to a pointer to a UM hfx attribute structure. Will be
07171     filled in by this function to point to the newly created lbm_hfx_attr_t object.
07172   \param original Pointer to a UM hfx attribute object as returned by ::lbm_hfx_attr_create
07173         or ::lbm_hfx_attr_create_default, from which \a attr is initialized.
07174   \return 0 for Success and -1 for Failure.
07175 */
07176 LBMExpDLL int lbm_hfx_attr_dup(lbm_hfx_attr_t **attr, 
07177                                                                                         const lbm_hfx_attr_t *original);
07178 
07179 /*! \brief Set an option for the given LBM hfx attribute.
07180 
07181            Used before the hfx is created.
07182            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
07183 
07184   \param attr Pointer to a UM hfx attribute object.
07185   \param optname String containing the option name.
07186   \param optval Pointer to the option value structure. The structure of the option values
07187                 are specific to the options themselves.
07188   \param optlen Length (in bytes) of the \a optval structure.
07189   \return 0 for Success and -1 for Failure.
07190 */
07191 LBMExpDLL int lbm_hfx_attr_setopt(lbm_hfx_attr_t *attr, const char *optname,
07192                                                                                         const void *optval, size_t optlen);
07193 
07194 /*! \brief Set an option for the given LBM hfx attribute using a string.
07195 
07196            Used before the hfx is created.
07197            NOTE: the attribute object must first be initialized with the corresponding _attr_create() function.
07198 
07199   \param attr Pointer to a UM hfx attributed object.
07200   \param optname String containing the option name.
07201   \param optval String containing the option value. The format of the string is
07202                 specific to the option itself.
07203   \return 0 for Success and -1 for Failure.
07204 */
07205 LBMExpDLL int lbm_hfx_attr_str_setopt(lbm_hfx_attr_t *attr, const char *optname,
07206                                                                                         const char *optval);
07207 
07208 /*! \brief Retrieve the value of an option for the given LBM hfx attribute.
07209 
07210   \param attr Pointer to a UM hfx attributed object.
07211   \param optname String containing the option name.
07212   \param optval Pointer to the option value structure to be filled.
07213                 The structure of the option values are specific to the options themselves.
07214   \param optlen Length (in bytes) of the \a optval structure when passed in. Upon return,
07215                 this is set to the size of the optval filled in structure.
07216   \return 0 for Success and -1 for Failure.
07217 */
07218 LBMExpDLL int lbm_hfx_attr_getopt(lbm_hfx_attr_t *attr, const char *optname,
07219                                                                                         void *optval, size_t *optlen);
07220 
07221 /*! \brief Retrieve the textual value of an option for the given LBM hfx attribute.
07222 
07223   \param attr Pointer to a UM hfx attributed object.
07224   \param optname String containing the option name.
07225   \param optval Pointer to the string to be filled in.
07226   \param optlen Maximum length (in bytes) of the \a string when passed in. Upon return,
07227                 this is set to the size of the formatted string.
07228   \return 0 for Success and -1 for Failure.
07229 */
07230 LBMExpDLL int lbm_hfx_attr_str_getopt(lbm_hfx_attr_t *attr, const char *optname,
07231                                                                                         char *optval, size_t *optlen);
07232 
07233 /*! \brief Set an option value within the given \a hfx.
07234 
07235            Only those options that can be set during operation may be specified.
07236            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
07237            in The UM Configuration Guide. For API functions that can access any option,
07238            see lbm_hfx_attr_*().
07239   \param hfx Pointer to a UM hfx object where the option is to be set.
07240   \param optname String containing the option name.
07241   \param optval Pointer to the option value structure. The structure of the option values
07242                 are specific to the options themselves.
07243   \param optlen Length (in bytes) of the \a optval structure.
07244   \return 0 for Success and -1 for Failure.
07245 */
07246 LBMExpDLL int lbm_hfx_setopt(lbm_hfx_t *hfx, const char *optname, const void *optval, size_t optlen);
07247 
07248 /*! \brief Set an option value within the given \a hfx.
07249 
07250            Only those options that can be set during operation may be specified.
07251            See "Options That May Be Set During Operation" (doc/Config/maybesetduringoperation.html)
07252            in The UM Configuration Guide. For API functions that can access any option,
07253            see lbm_hfx_attr_*().
07254   \param hfx Pointer to a UM hfx object where the option is to be set.
07255   \param optname String containing the option name.
07256   \param optval String containing the option value. The format of the string
07257                 is specific to the options themselves.
07258   \return 0 for Success and -1 for Failure.
07259 */
07260 LBMExpDLL int lbm_hfx_str_setopt(lbm_hfx_t *hfx, const char *optname, const char *optval);
07261 
07262 /*! \brief Retrieve an option value within the given \a hfx.
07263 
07264   \param hfx Pointer to a UM hfx object where the option is stored.
07265   \param optname String containing the option name.
07266   \param optval Pointer to the option value structure. The structure of the option values
07267                 are specific to the options themselves.
07268   \param optlen When passed, this is the max length (in bytes) of the \a optval structure. When
07269                 returned, this is the length of the filled in \a optval structure.
07270   \return 0 for Success and -1 for Failure.
07271 */
07272 LBMExpDLL int lbm_hfx_getopt(lbm_hfx_t *hfx, const char *optname, void *optval, size_t *optlen);
07273 
07274 /*! \brief Retrieve the textual option value within the given \a hfx.
07275 
07276   \param hfx Pointer to a UM hfx object where the option is stored.
07277   \param optname String containing the option name.
07278   \param optval String to hold the option value.
07279   \param optlen When passed, this is the max length (in bytes) of the string. When
07280                 returned, this is the length of the filled in option value.
07281   \return 0 for Success and -1 for Failure.
07282 */
07283 LBMExpDLL int lbm_hfx_str_getopt(lbm_hfx_t *hfx, const char *optname, char *optval, size_t *optlen);
07284 
07285 /*! \brief Create and initialize an lbm_hfx_t object.
07286 
07287         \sa lbm_hfx_delete()
07288         \param hfxp A pointer to a pointer to a UM hfx object. Will be filled in
07289              by this function to point to the newly created lbm_hfx_t object.
07290         \param cattr A pointer to a UM hfx attribute object. A value of NULL will
07291              use default attributes.
07292         \param symbol The symbol string to be used for all hot failover receivers managed by
07293                         this HFX.
07294         \param proc Pointer to a function to call when messages arrive.
07295         \param evq Optional Event Queue to place message events on when they arrive.
07296                         If NULL, causes \a proc to be called from context thread.
07297         \return 0 for Success and -1 for Failure.
07298  */
07299 LBMExpDLL int lbm_hfx_create(lbm_hfx_t **hfxp,
07300                                                                                 lbm_hfx_attr_t *cattr,
07301                                                                                 const char *symbol,
07302                                                                                 lbm_rcv_cb_proc proc,
07303                                                                                 lbm_event_queue_t *evq);
07304 
07305 /*! \brief Delete a UM hfx object.
07306         \warning It is not safe to call this function from a context thread callback.
07307         \param hfx Pointer to a UM hfx object to delete.
07308         \return 0 for Success and -1 for Failure.
07309 */
07310 LBMExpDLL int lbm_hfx_delete(lbm_hfx_t *hfx);
07311 
07312 /*! \brief Delete an LBM hfx object and receive a callback when the deletion is complete.
07313         Delete an LBM HFX object, with an application callback
07314         indicating when the object is fully cancelled.
07315         This extended version of the delete function requires the
07316         configuration option queue_cancellation_callbacks_enabled to be set to 1 if
07317         an event queue is in use.
07318         Unlike \sa lbm_hf_rcv_delete_ex or \sa lbm_rcv_delete_ex, this extended callback
07319         can be used whether or not an event queue is associated with the HFX.
07320         \warning It is not safe to call this function from a context thread callback.   \warning When deleting an hfx object, wait for the delete_ex callback before deleting any of the associated contexts.
07321         \param hfx Pointer to an LBM hfx object to delete.
07322         \param cbinfo Cancellation callback information containing the (optional) event
07323                 queue, function pointer, and client data for the callback.
07324         \return 0 for Success and -1 for Failure.
07325 */
07326 LBMExpDLL int lbm_hfx_delete_ex(lbm_hfx_t *hfx, lbm_event_queue_cancel_cb_info_t *cbinfo);
07327 
07328 /*! \brief Retrieves all receiver attribute options for an HFX receiver.
07329 
07330         The config object is filled with receiver configuration options
07331         \param hfxrcv The HFX receiver object to retrieve the attributes from
07332         \param size Size of the opts array. Will return the number of items that were set in opts
07333         \param opts The options array to fill
07334         */
07335 LBMExpDLL int lbm_hfx_rcv_topic_dump(lbm_hfx_rcv_t *hfxrcv, 
07336                                                                          int *size, 
07337                                                                          lbm_config_option_t *opts);
07338 
07339 /*! \brief Create a HFX receiver. 
07340         \warning It is not safe to call this function from a context thread callback.
07341         \param hfrcvp A pointer to a pointer to a UM hfx_rcv_t object.  Will be filled in
07342                         by this function to point to the newly created lbm_hfx_rcv_t object.
07343         \param hfx An lbm_hfx_t object created by \sa lbm_hfx_create
07344         \param ctx The lbm_context_t object on which to create the new receiver.
07345         \param rattr The receiver attributes to be used when creating new hot failover receivers.
07346         \param clientd Pointer to client data to be delivered when a message is received and the
07347                         lbm_hfx_t object's proc is called.
07348  */
07349 LBMExpDLL int lbm_hfx_rcv_create(lbm_hfx_rcv_t **hfrcvp,
07350                                                                                         lbm_hfx_t *hfx,
07351                                                                                         lbm_context_t *ctx,
07352                                                                                         lbm_rcv_topic_attr_t *rattr,
07353                                                                                         void *clientd);
07354 
07355 /*! \brief Retrieve the underlying receiver from an lbm_hfx_rcv_t.
07356         \param hfxrcv A pointer to a UM hfx_rcv_t object.
07357  */
07358 LBMExpDLL lbm_rcv_t *lbm_rcv_from_hfx_rcv(lbm_hfx_rcv_t *hfxrcv);
07359 
07360 /*! \brief Delete a HFX receiver.
07361         \warning It is not safe to call this function from a context thread callback.
07362         \param hfrcv Pointer to a UM HFX receiver object to delete.
07363         \return 0 for Success and -1 for Failure
07364 */
07365 LBMExpDLL int lbm_hfx_rcv_delete(lbm_hfx_rcv_t *hfrcv);
07366 
07367 /*! \brief Extended delete a UM HFX receiver object.
07368         
07369         Delete a UM Hot Failover receiver object, with an application callback
07370         indicating when the receiver is fully cancelled.
07371         This extended version of the receiver delete function requires the
07372         configuration option queue_cancellation_callbacks_enabled to be set to 1 if
07373         an event queue is in use.
07374 
07375         Unlike \sa lbm_hf_rcv_delete_ex or \sa lbm_rcv_delete_ex, this extended callback
07376         can be used whether or not an event queue is associated with the HFX.
07377         This allows an application to delete a receiver from a single context and be notified
07378         when any messages currently held in the order map are no longer required.
07379 
07380         \warning It is not safe to call this function from a context thread callback.
07381         \param hfrcv Pointer to a UM HFX receiver to delete.
07382         \param cbinfo Cancellation callback information containing the (optional) event
07383                         queue, function pointer, and client data for the callback.
07384         \return 0 for Success and -1 for Failure.
07385 */
07386 LBMExpDLL int lbm_hfx_rcv_delete_ex(lbm_hfx_rcv_t *hfrcv, lbm_event_queue_cancel_cb_info_t *cbinfo);
07387 
07388 /*! \brief Set the file to receive LBM debug log entries
07389 
07390   \warning May be overridden by environment variable
07391   \param filename to open and send log events to
07392 */
07393 LBMExpDLL void lbm_debug_filename(const char *filename);
07394 
07395 /*! \brief Set the debug mask for LBM debug log entries
07396 
07397 \warning May be overridden by environment variable
07398   \param mask of debug log events to log (contact support for more information)
07399 */
07400 LBMExpDLL void lbm_debug_mask(lbm_uint64_t mask);
07401 
07402 /*! \brief Set the noflush flag for the debug logs.
07403     This can dramatically increase performance when a debug mask is set
07404  */
07405 LBMExpDLL void lbm_debug_noflush(int on);
07406 
07407 /*! \brief Enable logging of debug messages to the application logging callback set by lbm_log().
07408         By default, if lbm debug logging is enabled it is sent to the filename
07409         specified by lbm_debug_filename(), or stderr. Calling lbm_log_debug() with
07410         a value of 1 will redirect debug logging to the application logging
07411         callback set by lbm_log(), or stderr if no callback is set.
07412  */
07413 LBMExpDLL void lbm_log_debug(int on);
07414 
07415 /*! \brief Dump a running rollback debug log to the given filename
07416 
07417   \param filename to open and dump debug log events to
07418   \param append Flag to indicate that the dump should be appended to the file or overwrite the file
07419 */
07420 LBMExpDLL int lbm_debug_dump(const char *filename, int append);
07421 
07422 /*!     \brief Dynamically set the UIM loss rate.
07423 
07424         Set the UIM loss rate. This is equivalent to setting the environment variable
07425         LBM_UIM_LOSS_RATE, but allows the loss rate to be changed under program control.
07426         \param rate Loss rate (from 0 to 100).
07427 */
07428 LBMExpDLL void lbm_set_uim_loss_rate(int rate);
07429 
07430 /*!     \brief Dynamically set the LBT-RM loss rate.
07431 
07432         Set the LBT-RM loss rate. This is equivalent to setting the environment variable
07433         LBTRM_LOSS_RATE, but allows the loss rate to be changed under program control.
07434         \param rate Loss rate (from 0 to 100).
07435 */
07436 LBMExpDLL void lbm_set_lbtrm_loss_rate(int rate);
07437 
07438 /*!     \brief Dynamically set the LBT-RM source loss rate.
07439 
07440         Set the LBT-RM source loss rate. This is equivalent to setting the environment variable
07441         LBTRM_SRC_LOSS_RATE, but allows the loss rate to be changed under program control.
07442         \param rate Loss rate (from 0 to 100).
07443 */
07444 LBMExpDLL void lbm_set_lbtrm_src_loss_rate(int rate);
07445 
07446 /*!     \brief Dynamically set the LBT-RU loss rate.
07447 
07448         Set the LBT-RU loss rate. This is equivalent to setting the environment variable
07449         LBTRU_LOSS_RATE, but allows the loss rate to be changed under program control.
07450         \param rate Loss rate (from 0 to 100).
07451 */
07452 LBMExpDLL void lbm_set_lbtru_loss_rate(int rate);
07453 
07454 /*!     \brief Dynamically set the LBT-RU source loss rate.
07455 
07456         Set the LBT-RU source loss rate. This is equivalent to setting the environment variable
07457         LBTRU_SRC_LOSS_RATE, but allows the loss rate to be changed under program control.
07458         \param rate Loss rate (from 0 to 100).
07459 */
07460 LBMExpDLL void lbm_set_lbtru_src_loss_rate(int rate);
07461 
07462 /*!     \brief Parse a UM transport source string into its components.
07463 
07464         \param source Source string.
07465         \param info Pointer to a transport source info structure into which the components
07466                 are parsed.
07467         \param infosize Size (in bytes) of \a info.
07468         \return 0 for success, -1 for failure.
07469  */
07470 LBMExpDLL int lbm_transport_source_parse(const char *source, lbm_transport_source_info_t *info, size_t infosize);
07471 
07472 /*!     \brief Format a UM transport source string from its components.
07473 
07474         \param info Pointer to a transport source info structure containing the transport source
07475                 components.
07476         \param infosize Size (in bytes) of \a info.
07477         \param source Pointer to a buffer to receive the formatted transport source string.
07478         \param size Size of \a source in bytes.
07479         \return 0 for success, -1 for failure.
07480  */
07481 LBMExpDLL int lbm_transport_source_format(const lbm_transport_source_info_t *info, size_t infosize, char *source, size_t *size);
07482         
07483 /*! \brief An iterator (opaque) used to iterate over elements of an app header chain. */
07484 struct lbm_apphdr_chain_iter_t_stct;
07485 typedef struct lbm_apphdr_chain_iter_t_stct lbm_apphdr_chain_iter_t;
07486 
07487 /*! \brief Structure that represents an element in an app header chain */
07488 typedef struct lbm_apphdr_chain_elem_t_stct {
07489         /*! Code representing the type of data in this element. */
07490         lbm_uchar_t type;
07491         /*! Code representing the subtype (if any) of the data in this element. */
07492         lbm_ushort_t subtype;
07493         /*! length of the data pointed to by \c data */
07494         size_t len;
07495         /*! Pointer to the app header data */
07496         void *data;
07497 } lbm_apphdr_chain_elem_t;
07498 
07499 /*! \brief Create a new app header chain that can be used to include metadata with a message
07500   \param chain Pointer to a pointer to an app header chain.  This will be filled in with the
07501                newly created chain.
07502   \return 0 for success, -1 for failure
07503 */
07504 LBMExpDLL int lbm_apphdr_chain_create(lbm_apphdr_chain_t **chain);
07505 
07506 /*! \brief Delete an app header chain previously created with lbm_apphdr_chain_create.
07507   \param chain Pointer to an app header chain.
07508   \return 0 for success, -1 for failure
07509 */
07510 LBMExpDLL int lbm_apphdr_chain_delete(lbm_apphdr_chain_t *chain);
07511 
07512 /*! \brief Appends a user-created app header to an app header chain.
07513   \param chain Pointer to an app header chain.
07514   \param elem Pointer to a user-created app header element.
07515   \return 0 for success, -1 for failure
07516  */
07517 LBMExpDLL int lbm_apphdr_chain_append_elem(lbm_apphdr_chain_t *chain, lbm_apphdr_chain_elem_t *elem);
07518 
07519 /*! \brief Create an iterator (an lbm_apphdr_chain_iter_t structure) to point to
07520            the first element in an apphdr chain.
07521   \param chain_iter Pointer to a pointer to an lbm_apphdr_chain_iter_t structure to be filled in.
07522   \param chain Pointer to an app header chain from which to create the iterator.
07523   \return 0 if the iterator points to the first element in the chain, -1 if there are no elements in the chain
07524 */
07525 LBMExpDLL int lbm_apphdr_chain_iter_create(lbm_apphdr_chain_iter_t **chain_iter, lbm_apphdr_chain_t *chain);
07526 
07527 /*! \brief Create an iterator (an lbm_apphdr_chain_iter_t structure) to point to
07528            the first element in an apphdr chain associated with a UM message.
07529     \param chain_iter Pointer to a pointer to an lbm_apphdr_chain_elem_t structure to be filled in
07530     \param msg  Pointer to a UM message from which to retrieve the app header chain.
07531     \return 0 if the iterator points to the first element in the chain, -1 if there are no elements in the chain
07532 */
07533 LBMExpDLL int lbm_apphdr_chain_iter_create_from_msg(lbm_apphdr_chain_iter_t **chain_iter, lbm_msg_t *msg);
07534 
07535 /*! \brief Delete an iterator allocated by one of the lbm_apphdr_chain_iter functions.
07536     \param chain_iter Pointer to an lbm_apphdr_chain_iter_t created by one of the
07537                 lbm_apphdr_chain_iter_create functions.
07538     \return 0 for success, -1 for failure
07539 */
07540 LBMExpDLL int lbm_apphdr_chain_iter_delete(lbm_apphdr_chain_iter_t *chain_iter);
07541 
07542 /*! \brief Initializes an app header chain iterator to the first element in the chain.
07543 
07544     \param chain_iter Pointer to pointer to an lbm_apphdr_chain_iter_t iterator.
07545     \return 0 for Success and -1 for Failure.
07546  */
07547 LBMExpDLL int lbm_apphdr_chain_iter_first(lbm_apphdr_chain_iter_t **chain_iter);
07548 
07549 /*! \brief Tests an lbm_apphdr_chain_iter_t iterator to see if more elements in the chain remain.
07550 
07551    \param chain_iter Pointer to pointer to an lbm_apphdr_chain_iter_t iterator.
07552    \return 1 if there is a next element in an app header chain, 0 otherwise.
07553 */
07554 LBMExpDLL int lbm_apphdr_chain_iter_done(lbm_apphdr_chain_iter_t **chain_iter);
07555 
07556 /*! \brief Advances the iterator to the next element in an app header chain, if any.
07557 
07558     \param chain_iter Pointer to pointer to an lbm_apphdr_chain_iter_t iterator.
07559     \return 0 for Success, -1 for failure if there is no next element in the chain (iterator is unmodified).
07560 */
07561 LBMExpDLL int lbm_apphdr_chain_iter_next(lbm_apphdr_chain_iter_t **chain_iter);
07562 
07563 /*! \brief Returns the current element of an app header chain pointed to by an lbm_apphdr_chain_iter_t iterator.
07564 
07565     \param chain_iter Pointer to pointer to an lbm_apphdr_chain_iter_t iterator.
07566     \return lbm_apphdr_chain_elem_t pointer to the current app header chain element.
07567  */
07568 LBMExpDLL lbm_apphdr_chain_elem_t * lbm_apphdr_chain_iter_current(lbm_apphdr_chain_iter_t **chain_iter);
07569 
07570 
07571 /*! \brief A struct used for iterating over properties pointed to by an lbm_msg_properties_t */
07572 typedef struct lbm_msg_properties_iter_t_stct {
07573     const char *name;
07574         char *data;
07575         size_t size;
07576     int type;
07577 } lbm_msg_properties_iter_t;
07578 
07579 /*! \brief Creates a new properties object, used for sending messages with properties.
07580      \sa lbm_src_send_ex
07581     \sa lbm_msg_properties_delete
07582     \sa lbm_msg_properties_set
07583     \sa lbm_msg_properties_get
07584     \param properties A pointer to a pointer to be filled in by this function.
07585     \return LBM_OK for success, LBM_FAILURE for failure if the memory cannot be allocated.
07586  */
07587 LBMExpDLL int lbm_msg_properties_create(lbm_msg_properties_t **properties);
07588 
07589 /*! \brief Deletes a properties object.
07590     \sa lbm_src_send_ex
07591     \sa lbm_msg_properties_create
07592     \sa lbm_msg_properties_set
07593     \sa lbm_msg_properties_get
07594     \param properties A pointer to a properties object.
07595     \return LBM_OK for success, LBM_FAILURE for failure.
07596  */
07597 LBMExpDLL int lbm_msg_properties_delete(lbm_msg_properties_t *properties);
07598 
07599 /*! \brief Sets the value of the property with the specified name.
07600     Each property name may be associated with one and only one value.
07601     \sa lbm_src_send_ex
07602     \sa lbm_msg_properties_create
07603     \sa lbm_msg_properties_get
07604     \param properties The properties object that the new value should be set on
07605     \param name The name of the property to be set
07606     \param value The value to set.
07607     \param type The type of value being specified.
07608     \param size The size of the value being specified. For string types, the specified number of bytes will be copied, and a null terminator will be appended.
07609     \return LBM_OK for success, LBM_FAILURE for failure, and changes the current value of lbm_errnum() and lbm_errstr().
07610 */
07611 LBMExpDLL int lbm_msg_properties_set(lbm_msg_properties_t *properties, const char *name, const void *value, int type, size_t size);
07612 
07613 /*! \brief Clear the value associated with the name in the specified properties object
07614     \sa lbm_msg_properties_create
07615     \sa lbm_msg_properties_set
07616     \sa lbm_msg_properties_get
07617     \param properties Properties object from which the named property should be cleared.
07618     \param name Property to be cleared.
07619     \return LBM_OK for success, LBM_FAILURE if the property was not present.
07620 */
07621 LBMExpDLL int lbm_msg_properties_clear(lbm_msg_properties_t *properties, const char *name);
07622 
07623 /*! \brief Gets the value of the property with the specified name.
07624     \sa lbm_src_send_ex
07625     \sa lbm_msg_properties_create
07626     \sa lbm_msg_properties_get
07627     \param properties The properties object that the new value should be retrieved from 
07628     \param name The name of the property to be retrieved
07629     \param value A pointer to the memory to be filled in with the value.
07630     \param type A pointer to the type the value should be retrieved as.  If the specified type is not compatible with the property, this field will be filled in with the required type.
07631     \param size A pointer to a size_t holding the size of the memory block available to be filled in.  If a block of insufficient size is specified, this field will be filled in with the required size. For string types, the block of memory must be of sufficient size to hold the string as well as the null terminator.
07632     \return LBM_OK for success, LBM_FAILURE for failure, and changes the current value of lbm_errnum() and lbm_errstr().
07633 */
07634 LBMExpDLL int lbm_msg_properties_get(lbm_msg_properties_t *properties, const char *name, void *value, int *type, size_t *size);
07635 
07636 /*! \brief Creates a new msg properties iterator.
07637     The newly created iterator is not associated with any properties object.  Use \sa lbm_msg_properties_iter_first to begin iterating over a properties object.
07638     \param iterp A pointer to a pointer that will be filled in with the newly-created iterator object.
07639     \return LBM_OK for success, LBM_FAILURE for failure.
07640 */
07641 LBMExpDLL int lbm_msg_properties_iter_create(lbm_msg_properties_iter_t **iterp);
07642 
07643 /*! \brief Deletes an lbm_msg_properties_iterator 
07644     \sa lbm_msg_properties_iter_create
07645     \param iter A pointer to an iterator created via \sa lbm_msg_properties_iter_create
07646     \return LBM_OK for success, LBM_FAILURE for failure.
07647  */
07648 LBMExpDLL int lbm_msg_properties_iter_delete(lbm_msg_properties_iter_t *iter);
07649 
07650 /*! \brief Begin iterating over an \sa lbm_msg_properties_t object, starting at the first element.
07651     Calling lbm_msg_properties_iter_first associates an iterator with a properties object, and sets its current position to the first property available.  An iterator can be used to iterate over more than one properties object as long as lbm_msg_properties_iter_first is called to associate it with each new properties object.
07652     \sa lbm_msg_properties_iter_next
07653     \param iter An iterator object allocated via \sa lbm_msg_properties_iter_create
07654     \param properties A properties object, either retrieved from an lbm_msg_t, or created via \sa lbm_msg_properties_create
07655     \return LBM_OK for success, LBM_FAILURE if there are no elements contained in the properties object.
07656 */
07657 LBMExpDLL int lbm_msg_properties_iter_first(lbm_msg_properties_iter_t *iter, lbm_msg_properties_t *properties);
07658 
07659 /*! \brief Iterate to the next property in an \sa lbm_msg_properties_t object.
07660     \sa lbm_msg_properties_iter_first
07661     \sa lbm_msg_properties_iter_prev
07662     \param iter Iterate to the next element in the currently associated lbm_msg_properties_t object.
07663     \return LBM_OK for success, LBM_FAILURE if the iterator already points to the last element.
07664 */
07665 LBMExpDLL int lbm_msg_properties_iter_next(lbm_msg_properties_iter_t *iter);
07666 
07667 /*! \brief Retrieves the current number of inflight messages of a given type from the src pointed to by lbm_src_t *src.
07668 
07669     \sa lbm_flight_size_set_inflight_cb_proc
07670     \param src Pointer to the source.
07671     \param type Type of flight size.
07672     \arg \c LBM_FLIGHT_SIZE_TYPE_UME - Specifies a UM flight size
07673     \arg \c LBM_FLIGHT_SIZE_TYPE_ULB - Specifies a ULB flight size
07674     \arg \c LBM_FLIGHT_SIZE_TYPE_UMQ - Specifies a UMQ flight size
07675     \param inflight Pointer to an int whose value will be filled in to reflect the current inflight.
07676     \param proc Optional callback that allows an application to set the current inflight.
07677     \param clientd Optional client data passed into the proc.
07678     \return 0 for Success, -1 for failure if the proc returns a negative value.
07679 */
07680 LBMExpDLL int lbm_src_get_inflight(lbm_src_t *src, int type, int *inflight, lbm_flight_size_set_inflight_cb_proc proc, void *clientd);
07681 
07682 /*! \brief Retrieves the current number of inflight information of a given type from the src pointed to by lbm_src_t *src.
07683 
07684     \sa lbm_flight_size_set_inflight_cb_proc
07685     \param src Pointer to the source.
07686     \param type Type of flight size.
07687     \arg \c LBM_FLIGHT_SIZE_TYPE_UME - Specifies a UM flight size
07688     \arg \c LBM_FLIGHT_SIZE_TYPE_ULB - Specifies a ULB flight size
07689     \arg \c LBM_FLIGHT_SIZE_TYPE_UMQ - Specifies a UMQ flight size
07690     \param inflight Pointer to a structure to be filled in with the current inflight values.
07691     \param proc Optional callback that allows an application to set the current inflight.
07692     \param clientd Optional client data passed into the proc.
07693     \return 0 for Success, -1 for failure if the proc returns a negative value.
07694 */
07695 LBMExpDLL int lbm_src_get_inflight_ex(lbm_src_t *src, int type, lbm_flight_size_inflight_t *inflight, lbm_flight_size_set_inflight_ex_cb_proc proc, void *clientd);
07696 
07697 /*! \brief Retrieves the current number of inflight UMQ messages from the ctx pointed to by lbm_context_t *ctx.
07698 
07699     \sa lbm_flight_size_set_inflight_cb_proc
07700     \param ctx Pointer to the context.
07701     \param qname Name of the queue.
07702     \param inflight Pointer to an int whose value will be filled in to reflect the current inflight.
07703     \param proc Optional callback that allows an application to set the current inflight.
07704     \param clientd Optional client data passed into the proc.
07705     \return 0 for Success, -1 for failure if the proc returns a negative value.
07706 */
07707 LBMExpDLL int lbm_ctx_umq_get_inflight(lbm_context_t *ctx, const char *qname, int *inflight, lbm_flight_size_set_inflight_cb_proc proc, void *clientd);
07708 
07709 /*! \brief Mark a specific sqn as stable at a store, triggering a source event notification if configured to do so. Also adjusts the current number 
07710 of inflight messages for the src if necessary.
07711 
07712     \param src Pointer to the source.
07713     \param sqn Sqn of the fragment to mark stable.
07714     \return 0 for Success, -1 for failure if sqn is not found or sqn is already stable
07715 */
07716 LBMExpDLL int lbm_ume_src_msg_stable(lbm_src_t *src, lbm_uint32_t sqn);
07717 
07718 /*! \brief Mark a specific msg_id as stable at qname, triggering a source event notification if configured to do so. Also adjusts the current number 
07719 of inflight messages for the src if necessary.
07720 
07721     \param ctx Pointer to the context.
07722     \param qname Name of the queue.
07723     \param msg_id Msg_id of the message to mark stable.
07724     \return 0 for Success, -1 for failure if msg_id is not found or msg_id is already stable
07725 */
07726 LBMExpDLL int lbm_umq_ctx_msg_stable(lbm_context_t *ctx, const char *qname, lbm_umq_msgid_t *msg_id);
07727 
07728 /*! \brief Retrieves the ack structure from a UMP message.
07729 
07730     \sa lbm_ume_ack_delete
07731     \param msg Pointer to the message object from which to extract the ack structure.
07732     \return the ack structure for Success, NULL for failure.
07733 */
07734 LBMExpDLL lbm_ume_rcv_ack_t *lbm_msg_extract_ume_ack(lbm_msg_t *msg);
07735 
07736 /*! \brief Deletes an ack structure.
07737 
07738     \sa lbm_msg_extract_ume_ack.
07739     \param ack Pointer to the ack structure to be deleted.
07740     \return 0 for Success, -1 for failure.
07741 */
07742 LBMExpDLL int lbm_ume_ack_delete(lbm_ume_rcv_ack_t *ack);
07743 
07744 /*! \brief Sends an explicit ack up to the sequence number provided
07745 
07746     \sa lbm_msg_extract_ume_ack.
07747     \param ack Pointer to the previously extracted ack structure of a message on the same stream that is currently being explicitly acked.
07748     \param sqn The sequence number up to which to send the explicit ack.
07749     \return 0 for Success and -1 for Failure.
07750 */
07751 LBMExpDLL int lbm_ume_ack_send_explicit_ack(lbm_ume_rcv_ack_t *ack, lbm_uint_t sqn);
07752 
07753 /*! \brief Retrieves a list of currently available topics from a queue (asynchronous operation)
07754 
07755         The returned list of topics is complete once the asynchronous operation callback is
07756         called with an LBM_ASYNC_OP_STATUS_COMPLETE.  Each returned lbm_umq_queue_topic_t
07757         object also contains the application sets associated with that topic and receiver type IDs
07758         associated with each application set.
07759 
07760         This function is deprecated.
07761 
07762     \sa lbm_umq_queue_topic_t
07763     \param ctx LBM context object.
07764     \param queue_name Name of the queue to retrieve a topic list from.
07765     \param async_opfunc The asynchronous operation callback the topic list will be delivered to.
07766     \return 0 for Success and -1 for Failure.
07767 */
07768 LBMExpDLL int lbm_ctx_umq_queue_topic_list(lbm_context_t *ctx, const char *queue_name, lbm_async_operation_func_t *async_opfunc);
07769 
07770 /*! \brief Opaque handle to a message selector. */
07771 struct lbm_umq_msg_selector_t_stct;
07772 typedef struct lbm_umq_msg_selector_t_stct lbm_umq_msg_selector_t;
07773 
07774 /*! \brief Create an umq message selector (an lbm_umq_msg_selector_t structure).
07775     \param selector Pointer to a pointer to an lbm_umq_msg_selector_t structure to be filled in
07776     \param str Pointer to the character string of the message selector.
07777     \param len Length of the above character string.
07778     \return the length of message selector string for Success and negative values for Failure.
07779  */
07780 LBMExpDLL int lbm_umq_msg_selector_create(lbm_umq_msg_selector_t **selector, char* str, lbm_uint16_t len);
07781 
07782 /*! \brief Delete the lbm_umq_msg_selector_t object previously created with lbm_umq_msg_selector_create.        
07783     \param selector Pointer to lbm_umq_msg_selector_t object.
07784  */
07785 LBMExpDLL int lbm_umq_msg_selector_delete(lbm_umq_msg_selector_t *selector);
07786 
07787 /*! \brief Retrieves a list of all currently-queued messages from a queue (asynchronous operation).
07788 
07789         Results are valid once the asynchronous operation callback is called with the LBM_ASYNC_OP_STATUS_COMPLETE status.
07790         An array of lbm_umq_queue_msg_status_t objects is returned, each with its msgid field set to a valid
07791         UMQ message ID of a message that is currently in the queue within the application set to which the observer
07792         receiver belongs.  All message IDs of all currently enqueued messages are returned.
07793         NOTE: The only valid field of each lbm_umq_queue_msg_status_t object will be the msgid field; all other fields
07794         will be NULL or 0 and should not be relied upon to be accurate.
07795 
07796         This function is deprecated.
07797 
07798     \param rcv Pointer to observer receiver object
07799     \param queue_name Name of the queue to retrieve the list of messages from.
07800     \param selector Not currently supported; please pass NULL.
07801     \param async_opfunc The asynchronous operation callback the topic list will be delivered to.
07802  */
07803 LBMExpDLL int lbm_rcv_umq_queue_msg_list(lbm_rcv_t *rcv, const char *queue_name, lbm_umq_msg_selector_t *selector, lbm_async_operation_func_t *async_opfunc);
07804 
07805 /*! \brief Retrieves a set of queued messages from the queue (asynchronous operation).
07806 
07807         Results are valid once the asynchronous operation callback is called with the LBM_ASYNC_OP_STATUS_COMPLETE status.
07808         An array of lbm_umq_queue_msg_status_t objects is returned; the size of the array returned will match the size
07809         of the msgids array originally passed in.  Each returned lbm_umq_queue_msg_status_t object contains
07810         state information (LBM_UMQ_QUEUE_MSG_STATUS_UNASSIGNED, LBM_UMQ_QUEUE_MSG_STATUS_CONSUMED, etc.), and
07811         possibly message data, for each requested message.  If message data was available, the msg field of the
07812         lbm_umq_queue_msg_status_t object will be non-NULL; otherwise it will be NULL.  Message data is not
07813         always still available for a given message ID (in the case of a message that has been fully consumed across
07814         all configured application sets in the queue, for example).
07815 
07816         This function is deprecated.
07817 
07818         \sa LBM_UMQ_QUEUE_MSG_STATUS_UNKNOWN
07819         \sa LBM_UMQ_QUEUE_MSG_STATUS_UNASSIGNED
07820         \sa LBM_UMQ_QUEUE_MSG_STATUS_ASSIGNED
07821         \sa LBM_UMQ_QUEUE_MSG_STATUS_REASSIGNING
07822         \sa LBM_UMQ_QUEUE_MSG_STATUS_CONSUMED
07823 
07824         \param rcv Pointer to observer receiver object
07825         \param queue_name Name of the queue to retrieve the messages from.
07826         \param msgids Array of UMQ message IDs to retrieve.
07827         \param num_msgids Length of message ID array.
07828         \param async_opfunc The asynchronous operation callback the retrieved messages will be delivered to.
07829  */
07830 LBMExpDLL int lbm_rcv_umq_queue_msg_retrieve(lbm_rcv_t *rcv, const char *queue_name, lbm_umq_msgid_t *msgids, int num_msgids, lbm_async_operation_func_t *async_opfunc);
07831 
07832 /*! \brief Query the current status of an outstanding asynchronous operation.
07833 
07834    Calling this function will cause the associated asynchronous operation's
07835    async operation callback function to be called with current status information.
07836    This is a merely a polling mechanism, and the information returned is guaranteed
07837    to be correct only for the duration of the async operation callback function.
07838    It may change immediately afterwards.
07839 
07840   \warning It is not safe to call this function from within an asynchronous operation callback for the same handle that status is being requested for.
07841   \param handle Handle to the asynchronous operation.
07842   \param flags Flags to affect the behavior of the status request. ORed set of values.
07843   \arg \c LBM_ASYNC_OPERATION_STATUS_FLAG_NONBLOCK - If the operation's status cannot be retrieved immediately, just return without blocking. The default behavior is to block until the operation's status can be retrieved.
07844   \return -1 for Failure or 0 for Success.
07845 */
07846 LBMExpDLL int lbm_async_operation_status(lbm_async_operation_handle_t handle, int flags);
07847 
07848 /*! \brief Cancel an outstanding asynchronous operation.
07849 
07850    Calling this function will cause the associated asynchronous operation's
07851    async operation callback function to be called with a canceled status.
07852    If the operation could not be canceled (either it has already completed,
07853    it never existed, or it is currently executing and past the point of
07854    no return), then -1 is returned and lbm_errnum() is set to indicate
07855    why the operation could not be canceled.  Otherwise, 0 is returned
07856    for a successful cancel, indicating that the operation was found
07857    and guaranteed to have been truly canceled.
07858 
07859   \warning It is generally not safe to call this function from within an asynchronous operation callback for the same handle that is being canceled.
07860   There is one exception: it is safe to call cancel on a handle from within the initial LBM_ASYNC_OP_STATUS_IN_PROGRESS that
07861   delivers the handle; this is in fact a reasonable way to simulate a non-blocking synchronous call.
07862   \warning Once an operation has been canceled, any associated lbm_async_operation_info_t objects are no longer valid and should not be
07863   accessed.  This includes access to the opinfo parameter from within an initial LBM_ASYNC_OP_STATUS_IN_PROGRESS callback at any point in
07864   that callback after cancel has been called.
07865   \param handle Handle to the asynchronous operation.
07866   \param flags Flags to affect the behavior of the cancel. ORed set of values.
07867   \arg \c LBM_ASYNC_OPERATION_CANCEL_FLAG_NONBLOCK - If operation cannot be canceled immediately, return without canceling. The default behavior is to block until the operation can be successfully canceled.
07868   \return -1 for Failure or 0 for Success.
07869 */
07870 LBMExpDLL int lbm_async_operation_cancel(lbm_async_operation_handle_t handle, int flags);
07871 
07872 typedef int (*lbm_cred_callback_fn)(const char* name, size_t name_len, const char* passwd, size_t passwd_len, void *clientd);
07873 
07874 /*! \brief Set the user's credential and authentication requirement.
07875 
07876    Calling this function will set the credential of the user and make the
07877    requirement for the authentication. There are two ways to set credential:
07878    either setting the user's name and password parameters or passing the
07879    callback function pointer to retrieve credential information. The callback
07880    function method will override the credentials set by the input parameters.
07881    Once the parameter of auth_required is set to "1", the authentication results
07882    will be examined and errors will be reported if authentication checks fail.
07883    If the "auth_required" is set to "0", then the authentication failure will be 
07884    ignored and there is no impact on the undergoing process.
07885 
07886   \param ctx LBM context object.
07887   \param name the user name string.
07888   \param name_len the length of the user name string.
07889   \param passwd the user password string.
07890   \param passwd_len the length of the user password string.
07891   \param cbfn the callback function pointer.
07892   \param clientd the parameter of the callback function.
07893   \param auth_required the variable to require authentication service
07894   \return -1 for Failure or 0 for Success.
07895 */
07896 LBMExpDLL int lbm_auth_set_credentials(lbm_context_t *ctx, 
07897                                                                           const char* name, size_t name_len,
07898                                                                           const char* passwd, size_t passwd_len,
07899                                                                           lbm_cred_callback_fn cbfn, void *clientd,
07900                                                                           int auth_required);
07901 
07902 /*! \brief Create the storage object from XML password file
07903 
07904    Calling this function will create the storage object which contains all users' authentication and authorization information
07905    from the XML password file with the name specified in the input parameter. If that file does not exist, a default password
07906    information will be used instead.
07907   
07908   \param filename the xml file name string.
07909   \return  0 for Success or     negative for failure (-1:invalid parameter; -2: storage exist; -3: creation failed)
07910 */
07911 LBMExpDLL int lbm_authstorage_open_storage_xml(char *filename);
07912 
07913 /*! \brief Release the storage object.
07914 
07915    Calling this function will release the storage object created by lbm_authstorage_open_storage_xml().
07916   
07917   \param None.
07918   \return None.
07919 */
07920 LBMExpDLL void lbm_authstorage_close_storage_xml(void);
07921 
07922 /*! \brief Check if the user is authorized to execute the specified command
07923 
07924    Calling this function will check if the user is authorized to execute the specified command.
07925 
07926   \param username the user's name string.
07927   \param command the command string.
07928   \return -1 for Failure or 0 for Denial or 1 for Success.
07929 */
07930 LBMExpDLL int lbm_authstorage_checkpermission(char *username, char* command);
07931 
07932 /*! \brief Add the new user credential to the password file
07933 
07934    Calling this function will generate new credential entry for the user and save it to the password file. Setting  
07935    parameter of "flags" to "1" will overwrite the existing entry for the same user.
07936 
07937   \param username the user's name string.
07938   \param pass the password string.
07939   \param flags overwriting flag.
07940   \return negative values for Failure or 0 and positive values for Success.
07941 */
07942 LBMExpDLL int lbm_authstorage_addtpnam(const char* username, const char* pass, unsigned char flags);
07943 
07944 /*! \brief Delete the user credential from the password file
07945 
07946    Calling this function will remove the credential entry for the user from the password file.
07947 
07948   \param username the user's name string.
07949   \return -1 for Failure or 0 for Success.
07950 */
07951 LBMExpDLL int lbm_authstorage_deltpnam(const char* username);
07952 
07953 /*! \brief  Add one role entry for the user to the password file
07954 
07955    Calling this function will add a new role entry for the specified user to the password file.
07956 
07957   \param username the user's name string.
07958   \param role the role string.
07959   \return -1 for Failure or 0 for Success.
07960 */
07961 LBMExpDLL int lbm_authstorage_user_add_role(const char* username, const char* role);
07962 
07963 /*! \brief  Delete the role entry for the user from the password file
07964 
07965    Calling this function will remove the role entry for the specified user from the password file.
07966 
07967   \param username the user's name string.
07968   \param role the role string.
07969   \return -1 for Failure or 0 for Success.
07970 */
07971 LBMExpDLL int lbm_authstorage_user_del_role(const char *username, const char*  role); 
07972 
07973 /*! \brief  Load the role table from the password file
07974 
07975    Calling this function will create an internal data object to hold the role table from the password file.
07976 
07977   \param None.
07978   \return -1 for Failure or 0 for Success.
07979 */
07980 LBMExpDLL int lbm_authstorage_load_roletable();
07981 
07982 /*! \brief  Unload the role table
07983 
07984    Calling this function will release the role table saved in the internal data object.
07985 
07986   \param None.
07987   \return -1 for Failure or 0 for Success.
07988 */
07989 LBMExpDLL int lbm_authstorage_unload_roletable();
07990 
07991 /*! \brief  Add a new authorized action for the specified role.
07992 
07993    Calling this function will authorize users assuming the specified role to perform the assigned action.
07994 
07995   \param rolename the role name string.
07996   \param action the action name string
07997   \return -1 for Failure or 0 for Success.
07998 */
07999 LBMExpDLL int lbm_authstorage_roletable_add_role_action(const char* rolename, const char* action);
08000 
08001 /*! \brief  Print the role table saved in the internal data object
08002 
08003    Calling this function will print out the role table saved in the internal data object created by
08004    lbm_authstorage_load_roletable() function.
08005 
08006   \param None.
08007   \return -1 for Failure or 0 for Success.
08008 */
08009 LBMExpDLL int lbm_authstorage_print_roletable();
08010 
08011 /*! \brief Structure for specifying UMM daemon connection options */
08012 typedef struct lbm_umm_info_t_stct {
08013         /*! The UMM user name. */
08014         char username[LBM_UMM_USER_NAME_LENGTH_MAX];
08015         /*! The UMM user password. */
08016         char password[LBM_UMM_PASSWORD_LENGTH_MAX];
08017         /*! The UMM application name. */
08018         char appname[LBM_UMM_APP_NAME_LENGTH_MAX];
08019         /*! The list of UMM daemons in ip:port string format. Connections are tried in a round robin fashion, starting with index 0. Only the first contiguous set of non-blank entries are considered. */
08020         char servers[LBM_UMM_NUM_SERVERS_MAX][LBM_UMM_SERVER_LENGTH_MAX];
08021         /*! Flags, currently used to enable SSL. */
08022         lbm_uint32_t flags;
08023         /*! Path to a pem-encoded certificate file. If non-NULL, SSL is enabled and is used to validate the the UMM daemon certificate. */
08024         char * cert_file;
08025         /*! Certificate file password. Required only if certificate file is password-protected. */
08026         char * cert_file_password;
08027 } lbm_umm_info_t;
08028 
08029 /*! \brief Connect to and retrieve configuration from a UMM daemon
08030 
08031         In order to be effective, this function *must* be called before any other LBM API function. 
08032 
08033     \sa lbm_umm_info_t
08034     \param info lbm_umm_info_t struct specifying options for connecting to a UMM daemon.
08035     \return 0 for Success and -1 for Failure.
08036 */
08037 LBMExpDLL int lbm_set_umm_info(lbm_umm_info_t * info);
08038 
08039 /*! \brief Determine if the LBM library is capable of UME operations
08040 
08041         \return 1 if the library is capable of UME operations, 0 if the library is not capable of UME operations.
08042 */
08043 LBMExpDLL int lbm_is_ume_capable(void);
08044 
08045 /*! \brief Determine if the LBM library is capable of UMQ operations
08046 
08047         \return 1 if the library is capable of UMQ operations, 0 if the library is not capable of UMQ operations.
08048 */
08049 LBMExpDLL int lbm_is_umq_capable(void);
08050 
08051 /* internal error management function(s) */
08052 LBMExpDLL void lbm_seterr(int eno, const char *str);
08053 LBMExpDLL void lbm_seterrf(int eno, const char *format, ...);
08054 LBMExpDLL const char *lbm_strerror(void);
08055 LBMExpDLL const char *lbm_strerror_errnum(int errnum);
08056 LBMExpDLL void lbm_sock_init();
08057 /*! \brief Create a random id to be used in conjunction with  lbm_get_jms_msg_id for JMS compatibility.
08058 
08059         \return a random 64 bit long.
08060 */
08061 LBMExpDLL lbm_uint64_t lbm_create_random_id();
08062 /*! \brief Create JMS message ID.
08063 
08064         \return a JMS Message ID string.
08065 */
08066 LBMExpDLL char * lbm_get_jms_msg_id(lbm_uint64_t source_id, lbm_uint64_t seqno_id, char *topic);
08067 
08068 /*! \brief Acquires a pointer to a buffer of the specified length, to be filled in and sent later.
08069   \warning lbm_src_buff_acquire is NOT thread safe between sources on the same transport session
08070   \param src The source object
08071   \param bufp A pointer to a pointer to a buffer; the pointer will be set to non-NULL upon success.
08072   \param len The length of the buffer, in bytes, that is being requested.
08073   \param flags Flags field to control blocking (the default) or non-blocking (if LBM_SRC_NONBLOCK is set) behavior.
08074   \return 0 for Success and -1 for Failure.
08075 */
08076 LBMExpDLL int lbm_src_buff_acquire(lbm_src_t * const src, void ** const bufp, const size_t len, const int flags);
08077 
08078 /*! \brief Sends all buffers on a transport session that had been previously been acquired.
08079   \warning lbm_src_buffs_complete is NOT thread safe between sources on the same transport session
08080   \param src The source object
08081   \return 0 for Success and -1 for Failure.
08082 */
08083 LBMExpDLL int lbm_src_buffs_complete(lbm_src_t * const src);
08084 
08085 /*! \brief First sends all buffers on a transport session that had been previously acquired, and then
08086      acquires a pointer to a buffer of the specified length, to be filled in and sent later.
08087      Equivalent to calling lbm_src_buffs_complete followed by lbm_src_buff_acquire; included for
08088      convenience.
08089   \warning lbm_src_buff_acquire is NOT thread safe between sources on the same transport session
08090   \param src The source object
08091   \param bufp A pointer to a pointer to a buffer; the pointer will be set to non-NULL upon success.
08092   \param len The length of the buffer, in bytes, that is being requested.
08093   \param flags Flags field to control blocking (the default) or non-blocking (if LBM_SRC_NONBLOCK is set) behavior.
08094   \return 0 for Success and -1 for Failure.
08095 */
08096 LBMExpDLL int lbm_src_buffs_complete_and_acquire(lbm_src_t * const src, void ** const bufp, const size_t len, const int flags);
08097 
08098 /*! \brief Cancels all outstanding (not yet completed) buffers previously acquired using lbm_src_buff_acquire for
08099         this source.  All such acquired-but-not-completed buffers for this source (only) will no longer be received
08100         by any receivers.
08101         \warning lbm_src_buffs_cancel is NOT thread safe between sources on the same transport session
08102         \param src The source object
08103         \return 0 for Success and -1 for Failure
08104 */
08105 LBMExpDLL int lbm_src_buffs_cancel(lbm_src_t * const src);
08106 
08107 
08108 #if defined(__cplusplus)
08109 }
08110 #endif /* __cplusplus */
08111 
08112 #endif /* LBM_H */

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