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 */