doc/src/library/api_qref.im

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019-2020 Nokia
   4         Copyright (c) 2018-2020 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 extern void rmr_set_fack( void* vctx );
  76 &proto_end
  77 Invoking this function causes RMR to enable fast acknowledgement on TCP sessions
  78 if the underlying transport mechanism supports this.
  79 If this is not invoked, the option is not enabled.
  80
  81 &proto_start
  82 extern void rmr_set_vlevel( int new_level );
  83 &proto_end
  84 This function allows the user application to change the RMR verbosity level;
  85 the larger the &cw(vlevel) the more verbose RMR is with regard to writting
  86 messages to standard error.
  87 A value of minus 1 (-1) disables all RMR writing to the TTY.
  88
  89 &proto_start
  90 int rmr_get_rcvfd( void* vctx );
  91 &proto_end
  92 When the underlying transport mechanism supports this, a file
  93 descriptor suitable for use with the &cw(select, poll) and &cw(epoll)
  94 system calls is returned.  The file descriptor may not be used for
  95 read or write operations; doing so will have unpredictable results.
  96
  97 &proto_start
  98 void* rmr_init( char* proto_port, int def_msg_size, int flags );
  99 &proto_end
 100 This function must be used before all other RMR functions to
 101 initialize the environment.  The &cw(def_msg_size) parameter defines
 102 the &ital(normal,) or default, receive buffer size which will be used if required by the
 103 underlying transport mechanism.  The value is also used as the default
 104 payload size if a zero length is given to &func(rmr_alloc_msg:.)
 105
 106 &proto_start
 107 rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait );
 108 &proto_end
 109 Similar to the &func(rmr_call:) function, the message is sent to an
 110 endpoint and a response message is waited for.  This call is thread
 111 safe, and while the thread that invokes this function blocks on the
 112 response, it is possible for other application threads to continue to
 113 receive messages via the &func(rmr_rcv_msg:) function.
 114 &space
 115 In order to use the multi-threaded call functions, the option to
 116 enable threaded receive support must be set on the call to
 117 &func(rmr_init:.)
 118
 119 &proto_start
 120 rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
 121 &proto_end
 122 This function sends the provided message allowing RMR to retry soft
 123 failures for approximately &ccw(max_to) milliseconds.  When a value of
 124 zero (0) is given for the maximum timeout, RMR will not attempt any
 125 retries and will return the state after the first attempt.  It is
 126 unlikely that a user application will use this function as it is
 127 possible (and recommended) to set the max timeout via the specific,
 128 one time, function call, and then to allow that value to be used as
 129 the default when &func(rmr_send_msg:) is invoked.
 130
 131 &proto_start
 132 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait );
 133 &proto_end
 134 This function waits for a message to arrive and returns a message
 135 buffer with the received message.  The function will timeout after
 136 &cw(max_wait) milliseconds (approximately) if no message is received.
 137
 138 &proto_start
 139 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
 140 &proto_end
 141 This function accepts a message, selects a destination endpoint using
 142 the message type and subscription ID, and then attempts to send the
 143 message to the destination.  The function returns a message buffer to
 144 the caller with the state set to indicate the state of the send
 145 operation.  On success, the message buffer is a new buffer that the
 146 application can "fill in," and send without the need to overtly
 147 allocate a new buffer.  On failure, the message buffer is the buffer
 148 that the application attempted to send.
 149
 150 &proto_start
 151 int rmr_init_trace( void* vctx, int size );
 152 &proto_end
 153 This function is used to set the default trace data size.  The size
 154 defaults to zero until this function is called; after the application
 155 sets a non-zero value, messages created with the &func(rmr_alloc_msg:)
 156 function will be allocated with trace data set to the size provided.
 157
 158 &proto_start
 159 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
 160 &proto_end
 161 The &func(rmr_rcv_msg:) function is used to block and wait for a
 162 message to arrive.  When a message is received, a pointer to an RMR
 163 message buffer structure is returned to the caller.  The &cw(old_msg)
 164 parameter allows the application to to pass a message buffer for
 165 reuse.  If the application does not have an old buffer, a nil pointer
 166 is given and the function will allocate a new buffer.
 167
 168 &proto_start
 169 rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect,
 170      int allow2queue );
 171 &proto_end
 172 This function blocks until a message with a specific transaction ID is
 173 received.  If the &cw(allowd2queue) parameter is set to 1, messages
 174 which do not match the ID are queued and returned to the application
 175 on subsequent calls to &func(rmr_rcv_msg:.)
 176
 177 &proto_start
 178 int rmr_ready( void* vctx );
 179 &proto_end
 180 This function is used to test whether RMR is capable of sending
 181 messages.  In other words once this function returns true (!0) RMR has
 182 received a route table (either from a static file or from a route
 183 manager process) and can map message types to endpoints.  If the
 184 application attempts to send a message before this function returns
 185 true, the sends will fail.  Applications which are only message
 186 receivers do not need to use this function.
 187
 188 &proto_start
 189 rmr_mbuf_t*  rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
 190 &proto_end
 191 The &func(rmr_rts_msg:) function allows the application to send a
 192 response message to the endpoint from which the message originated.
 193 This requires that the application use the same message buffer that
 194 was received for the response as it contains the sender information
 195 that is needed for this function to be successful.  If the message
 196 cannot be sent, a pointer to the message buffer is returned and the
 197 status in the message buffer is set to indicate the reason.  On
 198 success, a nil pointer is returned.
 199
 200 &proto_start
 201 int rmr_set_rtimeout( void* vctx, int time );
 202 &proto_end
 203 This function became deprecated with the elimination of support for Nanomsg.
 204 See &cw(rmr_torcv_msg().)
 205 .if false
 206 This function provides the ability to return from a receive operation
 207 after a timeout threshold is reached before a message is received, and
 208 is intended only to support the underlying Nanomsg transport mechanism
 209 (support for Nanomsg is deprecated).  The &func(rmr_torcv_msg)
 210 function should be used if timed receives are required.
 211 &space
 212 For transport mechanisms which support a receive timeout, this
 213 function allows the application to set a default timeout for receive
 214 operations.  If a call to &func(rmr_rcv_msg) does not complete before
 215 &ital(time) milliseconds has elapsed, the receive function will return
 216 a nil message buffer.  This may not be supported by the underlying
 217 transport mechanism, and if it is not the return from this function
 218 will be -1.
 219 .fi
 220
 221 &proto_start
 222 int rmr_set_stimeout( void* vctx, int rounds );
 223 &proto_end
 224 This function became deprecated with the elimination of support for Nanomsg.
 225 .if false
 226 This function allows the application to set a maximum number of retry
 227 &ital(rounds) that RMR will attempt when send operations report a
 228 transient (retry) failure.  Each &ital(round) of retries requires
 229 approximately 1 millisecond, and setting the number of rounds to zero
 230 (0) causes RMR to report the transient failure to the application
 231 without any retry attempts.  If the user application does not invoke
 232 this function, the default is one (1) round of retries.
 233 .fi
 234
 235 &proto_start
 236 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
 237 &proto_end
 238 This function behaves identically to the &func(rmr_rcv_msg) function,
 239 but allows the application to set a specific timeout value for the
 240 receive operation.  If a message is not received before the timeout
 241 period expires (ms_to milliseconds), a message buffer is returned with
 242 the state set to &cw(RMR_ERR_TIMEOUT.)
 243
 244 &proto_start
 245 rmr_mbuf_t*  rmr_tralloc_msg( void* context, int msize, int trsize,
 246     unsigned const char* data );
 247 &proto_end
 248 Similar to the &func(rmr_alloc_msg) this function allocates a message
 249 buffer, and adds the referenced trace data to the buffer.  The new
 250 message buffer is returned.
 251
 252 &proto_start
 253 void rmr_wh_close( void* vctx, int whid );
 254 &proto_end
 255 This function closes an existing wormhole connection.
 256
 257 &proto_start
 258 extern rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg,
 259     int call_id, int max_wait );
 260 &proto_end
 261 This provides the same synchronous &ital(procedure call) as the &func(rmr_call()) function
 262 provides, excerpt that the message is sent to a specific endpoint as defined by an
 263 open wormhole.
 264
 265 &proto_start
 266 rmr_whid_t rmr_wh_open( void* vctx, char const* target );
 267 &proto_end
 268 This function allows the application to create a &ital(wormhole,) a
 269 direct connection to another application.  The peer application must
 270 also be using RMR (messages sent on a wormhole connection are RMR
 271 messages).  The target may be a hostname:port or IP-address:port
 272 combination.  Upon successful completion, the &ital(wormhole ID) is
 273 returned; this ID must be passed on all subsequent calls to wormhole
 274 functions for this connection.
 275
 276 &proto_start
 277 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
 278 &proto_end
 279 Once a wormhole has been established to a peer application, this
 280 function allows the application to send a message to the peer.  All
 281 semantics of normal RMR sends (retries, etc.) are observed.  The
 282 application may opt not to supply the message type or subscription ID
 283 in the message as neither are used by RMR; they may be required by the
 284 peer application depending on the application level protocol(s) in
 285 use.
 286
 287 &proto_start
 288 extern int rmr_wh_state( void* vctx, rmr_whid_t whid );
 289 &proto_end
 290 This function returns an indication of whether or not the connection referenced by
 291 the wormhole ID (whid) is open or closed.
 292
 293
 294 .** ------------------------------------
 295 &space
 296 &h2(Message Buffer Functions)
 297 The message buffer functions operate directly on a message buffer, and
 298 as such do not require that RMR context as a parameter.
 299 &space
 300
 301 &proto_start
 302 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 303 &proto_end
 304 Copy the bytes referenced by &ital(src) to the &ital(meid) field in
 305 the RMR message header.  Up to &ital(len) bytes are copied, though the
 306 maximum length of the field as governed by &cw(RMR_MAX_MEID) is
 307 enforced.
 308
 309 &proto_start
 310 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 311 &proto_end
 312 This function copies &ital(len) bytes from &ital(src) into the message
 313 buffer payload.  This function is primarily provided to support
 314 wrappers which don't directly support C pointers.
 315
 316 &proto_start
 317 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 318 &proto_end
 319 This function copies &ital(len) bytes of data from &ital(src) to the
 320 transaction ID field in the message buffer.  The number of bytes
 321 provided will be limited to a maximum of &cw(RMR_MAX_XID.)
 322
 323 &proto_start
 324 void rmr_free_msg( rmr_mbuf_t* mbuf );
 325 &proto_end
 326 This function should be used by the application to release the storage
 327 used by a message buffer.
 328
 329 &proto_start
 330 unsigned char*  rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
 331 &proto_end
 332 The bytes from the &cw(meid) field of the message buffer are copied to
 333 the &ital(dest) buffer provided by the application.  The full field of
 334 &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that
 335 &ital(dest) is large enough.  If the destination buffer pointer passed
 336 in is a nil pointer, the function will allocate a buffer and return a
 337 pointer to the buffer, which the caller is expected to free.
 338
 339 &proto_start
 340 unsigned char*  rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
 341 &proto_end
 342 The source of a message is copied to the &ital(dest) buffer provided
 343 by the caller.  This is generally the hostname and port, separated by
 344 a colon, of the application which sent the message, and is a zero
 345 terminated string.  Up to &cw(RMR_MAX_SRC) bytes will be copied, so
 346 the caller must ensure that &ital(dest) is at least this large.
 347
 348 &proto_start
 349 unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
 350 &proto_end
 351 This function copies the source IP address and port, separated by a
 352 colon, to the &ital(dest) buffer provided by the caller.  This is the
 353 address of the application which sent the message.  Up to
 354 &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that
 355 &ital(dest) is at least this large.
 356
 357 &proto_start
 358 int rmr_get_trlen( rmr_mbuf_t* msg );
 359 &proto_end
 360 This function can be used to determine the size of the trace
 361 information in the message buffer. If no trace data is present, then 0
 362 is returned.
 363
 364 &proto_start
 365 int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
 366 &proto_end
 367 The bytes from the trace data, up to &tial(size) bytes, is copied from
 368 the message buffer to the &ital(dest) buffer provided by the caller.
 369 The return value is the number of bytes actually copied.
 370
 371 &proto_start
 372 unsigned char*  rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest );
 373 &proto_end
 374 The bytes from the &ital(transaction) field in the message buffer are
 375 copied to the &ital(dest) buffer provided by the application.  The
 376 full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must
 377 ensure that &ital(dest) is large enough.  If the destination buffer
 378 pointer passed in is a nil pointer, the function will allocate a
 379 buffer and return a pointer to the buffer, which the caller is
 380 expected to free.
 381
 382 &proto_start
 383 int rmr_payload_size( rmr_mbuf_t* msg );
 384 &proto_end
 385 This function returns the number of bytes in the message buffer's
 386 payload that are available for the application to use.
 387
 388 &proto_start
 389 rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
 390 &proto_end
 391 This function allows the application to reallocate a message buffer
 392 with a different trace data size.  The contents of the message buffer
 393 supplied are copied to the new buffer, and a reference to the new
 394 buffer is returned.
 395
 396 &proto_start
 397 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* old_msg, int new_len,
 398     int copy, int clone );
 399 &proto_end
 400 This function allows the user programme to realloc the payload with a
 401 larger length.
 402 Optionally, the user programme may use this function to clone an existing
 403 message while extending the payload size.
 404 In both cases the message can be passed to a return to sender call as
 405 the source information from the original message is preserved.
 406
 407 &proto_start
 408 int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
 409 &proto_end
 410 The &ital(size) bytes, up to the size of the trace data in the message
 411 buffer, at &ital(data) are copied to the trace portion of the message
 412 buffer.  The return value is the actual number of bytes copied which
 413 could be less than the number requested.
 414
 415 &proto_start
 416 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
 417 &proto_end
 418 Accepts a pointer to a zero terminated string an copies it to the
 419 &cw(meid) field in the message header.  Up to &cw(RMR_MAX_MEID) bytes
 420 are copied (including the final 0), and the number copied is returned.
 421
 422 &proto_start
 423 void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
 424 &proto_end
 425 Accepts a pointer to a zero terminated string, and copies the string
 426 to the payload portion of the message buffer.  If the string is longer
 427 than the allocated payload, the string will be truncated and will
 428 &bold(not) be terminated with a zero byte.
 429
 430 &proto_start
 431 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
 432 &proto_end
 433 Accepts a pointer to a zero terminated string and copies the string to
 434 the transaction ID portion of the message buffer.  If the string is
 435 longer than &cw(RMR_MAX_XID,) the string will be truncated and will
 436 &bold(not) be zero terminated.
 437
 438 &proto_start
 439 void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
 440 &proto_end
 441 This function returns a pointer to the trace information in the
 442 message buffer.  The intent is that the application will treat this as
 443 a read/only field and will not write trace data into the message
 444 buffer.  The length of data available should be determined by calling
 445 &func(rmr_get_trlen:.)