doc/src/library/api_qref.im

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19
  20 .if false
  21         Mnemonic:       api_qr.im
  22         Abstract:       A quick reference to all external function calls
  23         Date:           2 August, 2019
  24         Author:         E. Scott Daniels
  25 .fi
  26
  27 &h1(Appendix &qr_appendix -- Quick Reference)
  28
  29 The prototypes for all externally available functions which comprise
  30 the RMR API are listed in alphabetical order below.  For each
  31 prototype a brief description of the function is given.  The developer
  32 is encouraged to install the RMR development package which contains
  33 the manual pages.  The manual pages completely describe each function
  34 in a level of detail consistent with UNIX man pages.
  35
  36 &h2(Context Specific Functions)
  37 These functions require that the RMR context (provided as the result
  38 of an &func(rmr_init:) call, be passed as the first argument (vctx).
  39
  40 &proto_start
  41 rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size );
  42 &proto_end
  43 This function allocates a &ital(zero copy) message buffer.  The
  44 payload portion is allocated from the underlying transport space such
  45 that on send the buffer does not require a second copy.  The size
  46 parameter is the size of the payload portion of the buffer. If the
  47 recipient of the message is expected to send a response, this should
  48 be large enough to accomodate the response which will enable the
  49 remote application to reuse the message for the response and avoid a
  50 costly reallocation.
  51
  52 &proto_start
  53 rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
  54 &proto_end
  55 The call function accepts a message, selects an endpoint to receive
  56 the message and sends the message.  RMR will block the return to the
  57 application until a matching response is received, or a timeout period
  58 is reached.  The transaction ID in the outbound message is used to
  59 match a response, so it is imperative that the application making the
  60 response reuse the received message, or copy the transaction ID to the
  61 new message before sending.  Messages arriving which do not match the
  62 expected response are queued and will be delivered to the application
  63 on subsequent calls to &func(rmr_rcv_msg:.)
  64
  65 &proto_start
  66 void rmr_close( void* vctx );
  67 &proto_end
  68 This function terminates all sessions with the underlying transport
  69 mechanism.  Buffers pending may or may not be flushed (depending on
  70 the underlying mechanism), thus it is recommended that before using
  71 this function the application pause for a second or two to ensure that
  72 the pending transmissions have completed.
  73
  74 &proto_start
  75 int rmr_get_rcvfd( void* vctx );
  76 &proto_end
  77 When the underlying transport mechanism supports this, a file
  78 descriptor suitable for use with the &cw(select, poll) and &cw(epoll)
  79 system calls is returned.  The file descriptor may not be used for
  80 read or write operations; doing so will have unpredictable results.
  81
  82 &proto_start
  83 void* rmr_init( char* proto_port, int max_msg_size, int flags );
  84 &proto_end
  85 This function must be used before all other RMR functions to
  86 initialize the environment.  The &cw(max_msg_size) parameter defines
  87 the maximum receive buffer size which will be used if required by the
  88 underlying transport mechanism.  The value is also used as the default
  89 payload size if a zero length is given to &func(rmr_alloc_msg:.)
  90
  91 &proto_start
  92 rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait );
  93 &proto_end
  94 Similar to the &func(rmr_call:) function, the message is sent to an
  95 endpoint and a response message is waited for.  This call is thread
  96 safe, and while the thread that invokes this function blocks on the
  97 response, it is possible for other application threads to continue to
  98 receive messages via the &func(rmr_rcv_msg:) function.
  99 &space
 100 In order to use the multi-threaded call functions, the option to
 101 enable threaded receive support must be set on the call to
 102 &func(rmr_init:.)
 103
 104 &proto_start
 105 rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
 106 &proto_end
 107 This function sends the provided message allowing RMR to retry soft
 108 failures for approximately &ccw(max_to) milliseconds.  When a value of
 109 zero (0) is given for the maximum timeout, RMR will not attempt any
 110 retries and will return the state after the first attempt.  It is
 111 unlikely that a user application will use this function as it is
 112 possible (and recommended) to set the max timeout via the specific,
 113 one time, function call, and then to allow that value to be used as
 114 the default when &func(rmr_send_msg:) is invoked.
 115
 116 &proto_start
 117 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait );
 118 &proto_end
 119 This function waits for a message to arrive and returns a message
 120 buffer with the received message.  The function will timeout after
 121 &cw(max_wait) milliseconds (approximately) if no message is received.
 122
 123 &proto_start
 124 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
 125 &proto_end
 126 This function accepts a message, selects a destination endpoint using
 127 the message type and subscription ID, and then attempts to send the
 128 message to the destination.  The function returns a message buffer to
 129 the caller with the state set to indicate the state of the send
 130 operation.  On success, the message buffer is a new buffer that the
 131 application can "fill in," and send without the need to overtly
 132 allocate a new buffer.  On failure, the message buffer is the buffer
 133 that the application attempted to send.
 134
 135 &proto_start
 136 int rmr_init_trace( void* vctx, int size );
 137 &proto_end
 138 This function is used to set the default trace data size.  The size
 139 defaults to zero until this function is called; after the application
 140 sets a non-zero value, messages created with the &func(rmr_alloc_msg:)
 141 function will be allocated with trace data set to the size provided.
 142
 143 &proto_start
 144 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
 145 &proto_end
 146 The &func(rmr_rcv_msg:) function is used to block and wait for a
 147 message to arrive.  When a message is received, a pointer to an RMR
 148 message buffer structure is returned to the caller.  The &cw(old_msg)
 149 parameter allows the application to to pass a message buffer for
 150 reuse.  If the application does not have an old buffer, a nil pointer
 151 is given and the function will allocate a new buffer.
 152
 153 &proto_start
 154 rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect,
 155      int allow2queue );
 156 &proto_end
 157 This function blocks until a message with a specific transaction ID is
 158 received.  If the &cw(allowd2queue) parameter is set to 1, messages
 159 which do not match the ID are queued and returned to the application
 160 on subsequent calls to &func(rmr_rcv_msg:.)
 161
 162 &proto_start
 163 int rmr_ready( void* vctx );
 164 &proto_end
 165 This function is used to test whether RMR is capable of sending
 166 messages.  In other words once this function returns true (!0) RMR has
 167 received a route table (either from a static file or from a route
 168 manager process) and can map message types to endpoints.  If the
 169 application attempts to send a message before this function returns
 170 true, the sends will fail.  Applications which are only message
 171 receivers do not need to use this function.
 172
 173 &proto_start
 174 rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
 175 &proto_end
 176 The &func(rmr_rts_msg:) function allows the application to send a
 177 response message to the endpoint from which the message originated.
 178 This requires that the application use the same message buffer that
 179 was received for the response as it contains the sender information
 180 that is needed for this function to be successful.  If the message
 181 cannot be sent, a pointer to the message buffer is returned and the
 182 status in the message buffer is set to indicate the reason.  On
 183 success, a nil pointer is returned.
 184
 185 &proto_start
 186 int rmr_set_rtimeout( void* vctx, int time );
 187 &proto_end
 188 This function provides the ability to return from a receive operation
 189 after a timeout threshold is reached before a message is received, and
 190 is intended only to support the underlying Nanomsg transport mechanism
 191 (support for Nanomsg is deprecated).  The &func(rmr_torcv_msg)
 192 function should be used if timed receives are required.
 193 &space
 194 For transport mechanisms which support a receive timeout, this
 195 function allows the application to set a default timeout for receive
 196 operations.  If a call to &func(rmr_rcv_msg) does not complete before
 197 &ital(time) milliseconds has elapsed, the receive function will return
 198 a nil message buffer.  This may not be supported by the underlying
 199 transport mechanism, and if it is not the return from this function
 200 will be -1.
 201
 202 &proto_start
 203 int rmr_set_stimeout( void* vctx, int rounds );
 204 &proto_end
 205 This function allows the application to set a maximum number of retry
 206 &ital(rounds) that RMR will attempt when send operations report a
 207 transient (retry) failure.  Each &ital(round) of retries requires
 208 approximately 1 millisecond, and setting the number of rounds to zero
 209 (0) causes RMR to report the transient failure to the application
 210 without any retry attempts.  If the user application does not invoke
 211 this function, the default is one (1) round of retries.
 212
 213 &proto_start
 214 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
 215 &proto_end
 216 This function behaves identically to the &func(rmr_rcv_msg) function,
 217 but allows the application to set a specific timeout value for the
 218 receive operation.  If a message is not received before the timeout
 219 period expires (ms_to milliseconds), a message buffer is returned with
 220 the state set to &cw(RMR_ERR_TIMEOUT.)
 221
 222 &proto_start
 223 rmr_mbuf_t*  rmr_tralloc_msg( void* context, int msize, int trsize,
 224      unsigned const char* data );
 225 &proto_end
 226 Similar to the &func(rmr_alloc_msg) this function allocates a message
 227 buffer, and adds the referenced trace data to the buffer.  The new
 228 message buffer is returned.
 229
 230 &proto_start
 231 void rmr_wh_close( void* vctx, int whid );
 232 &proto_end
 233 This function closes an existing wormhole connection.
 234
 235 &proto_start
 236 rmr_whid_t rmr_wh_open( void* vctx, char const* target );
 237 &proto_end
 238 This function allows the application to create a &ital(wormhole,) a
 239 direct connection to another application.  The peer application must
 240 also be using RMR (messages sent on a wormhole connection are RMR
 241 messages).  The target may be a hostname:port or IP-address:port
 242 combination.  Upon successful completion, the &ital(wormhole ID) is
 243 returned; this ID must be passed on all subsequent calls to wormhole
 244 functions for this connection.
 245
 246 &proto_start
 247 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
 248 &proto_end
 249 Once a wormhole has been established to a peer application, this
 250 function allows the application to send a message to the peer.  All
 251 semantics of normal RMR sends (retries, etc.) are observed.  The
 252 application may opt not to supply the message type or subscription ID
 253 in the message as neither are used by RMR; they may be required by the
 254 peer application depending on the application level protocol(s) in
 255 use.
 256
 257 .** ------------------------------------
 258 &space
 259 &h2(Message Buffer Functions)
 260 The message buffer functions operate directly on a message buffer, and
 261 as such do not require that RMR context as a parameter.
 262 &space
 263
 264 &proto_start
 265 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 266 &proto_end
 267 Copy the bytes referenced by &ital(src) to the &ital(meid) field in
 268 the RMR message header.  Up to &ital(len) bytes are copied, though the
 269 maximum length of the field as governed by &cw(RMR_MAX_MEID) is
 270 enforced.
 271
 272 &proto_start
 273 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 274 &proto_end
 275 This function copies &ital(len) bytes from &ital(src) into the message
 276 buffer payload.  This function is primarily provided to support
 277 wrappers which don't directly support C pointers.
 278
 279 &proto_start
 280 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 281 &proto_end
 282 This function copies &ital(len) bytes of data from &ital(src) to the
 283 transaction ID field in the message buffer.  The number of bytes
 284 provided will be limited to a maximum of &cw(RMR_MAX_XID.)
 285
 286 &proto_start
 287 void rmr_free_msg( rmr_mbuf_t* mbuf );
 288 &proto_end
 289 This function should be used by the application to release the storage
 290 used by a message buffer.
 291
 292 &proto_start
 293 unsigned char*  rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
 294 &proto_end
 295 The bytes from the &cw(meid) field of the message buffer are copied to
 296 the &ital(dest) buffer provided by the application.  The full field of
 297 &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that
 298 &ital(dest) is large enough.  If the destination buffer pointer passed
 299 in is a nil pointer, the function will allocate a buffer and return a
 300 pointer to the buffer, which the caller is expected to free.
 301
 302 &proto_start
 303 unsigned char*  rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
 304 &proto_end
 305 The source of a message is copied to the &ital(dest) buffer provided
 306 by the caller.  This is generally the hostname and port, separated by
 307 a colon, of the application which sent the message, and is a zero
 308 terminated string.  Up to &cw(RMR_MAX_SRC) bytes will be copied, so
 309 the caller must ensure that &ital(dest) is at least this large.
 310
 311 &proto_start
 312 unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
 313 &proto_end
 314 This function copies the source IP address and port, separated by a
 315 colon, to the &ital(dest) buffer provided by the caller.  This is the
 316 address of the application which sent the message.  Up to
 317 &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that
 318 &ital(dest) is at least this large.
 319
 320 &proto_start
 321 int rmr_get_trlen( rmr_mbuf_t* msg );
 322 &proto_end
 323 This function can be used to determine the size of the trace
 324 information in the message buffer. If no trace data is present, then 0
 325 is returned.
 326
 327 &proto_start
 328 int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
 329 &proto_end
 330 The bytes from the trace data, up to &tial(size) bytes, is copied from
 331 the message buffer to the &ital(dest) buffer provided by the caller.
 332 The return value is the number of bytes actually copied.
 333
 334 &proto_start
 335 unsigned char*  rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest );
 336 &proto_end
 337 The bytes from the &ital(transaction) field in the message buffer are
 338 copied to the &ital(dest) buffer provided by the application.  The
 339 full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must
 340 ensure that &ital(dest) is large enough.  If the destination buffer
 341 pointer passed in is a nil pointer, the function will allocate a
 342 buffer and return a pointer to the buffer, which the caller is
 343 expected to free.
 344
 345 &proto_start
 346 int rmr_payload_size( rmr_mbuf_t* msg );
 347 &proto_end
 348 This function returns the number of bytes in the message buffer's
 349 payload that are available for the application to use.
 350
 351 &proto_start
 352 rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
 353 &proto_end
 354 This function allows the application to reallocate a message buffer
 355 with a different trace data size.  The contents of the message buffer
 356 supplied are copied to the new buffer, and a reference to the new
 357 buffer is returned.
 358
 359 &proto_start
 360 int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
 361 &proto_end
 362 The &ital(size) bytes, up to the size of the trace data in the message
 363 buffer, at &ital(data) are copied to the trace portion of the message
 364 buffer.  The return value is the actual number of bytes copied which
 365 could be less than the number requested.
 366
 367 &proto_start
 368 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
 369 &proto_end
 370 Accepts a pointer to a zero terminated string an copies it to the
 371 &cw(meid) field in the message header.  Up to &cw(RMR_MAX_MEID) bytes
 372 are copied (including the final 0), and the number copied is returned.
 373
 374 &proto_start
 375 void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
 376 &proto_end
 377 Accepts a pointer to a zero terminated string, and copies the string
 378 to the payload portion of the message buffer.  If the string is longer
 379 than the allocated payload, the string will be truncated and will
 380 &bold(not) be terminated with a zero byte.
 381
 382 &proto_start
 383 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
 384 &proto_end
 385 Accepts a pointer to a zero terminated string and copies the string to
 386 the transaction ID portion of the message buffer.  If the string is
 387 longer than &cw(RMR_MAX_XID,) the string will be truncated and will
 388 &bold(not) be zero terminated.
 389
 390 &proto_start
 391 void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
 392 &proto_end
 393 This function returns a pointer to the trace information in the
 394 message buffer.  The intent is that the application will treat this as
 395 a read/only field and will not write trace data into the message
 396 buffer.  The length of data available should be determined by calling
 397 &func(rmr_get_trlen:.)