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