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 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, unsigned const char* data );
 246 &proto_end
 247 Similar to the &func(rmr_alloc_msg) this function allocates a message
 248 buffer, and adds the referenced trace data to the buffer.  The new
 249 message buffer is returned.
 250
 251 &proto_start
 252 void rmr_wh_close( void* vctx, int whid );
 253 &proto_end
 254 This function closes an existing wormhole connection.
 255
 256 &proto_start
 257 extern rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait );
 258 &proto_end
 259 This provides the same synchronous &ital(procedure call) as the &cw(rmr_call()) function
 260 provides, excerpt that the message is sent to a specific endpoint as defined by an
 261 open wormhole.
 262
 263 &proto_start
 264 rmr_whid_t rmr_wh_open( void* vctx, char const* target );
 265 &proto_end
 266 This function allows the application to create a &ital(wormhole,) a
 267 direct connection to another application.  The peer application must
 268 also be using RMR (messages sent on a wormhole connection are RMR
 269 messages).  The target may be a hostname:port or IP-address:port
 270 combination.  Upon successful completion, the &ital(wormhole ID) is
 271 returned; this ID must be passed on all subsequent calls to wormhole
 272 functions for this connection.
 273
 274 &proto_start
 275 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
 276 &proto_end
 277 Once a wormhole has been established to a peer application, this
 278 function allows the application to send a message to the peer.  All
 279 semantics of normal RMR sends (retries, etc.) are observed.  The
 280 application may opt not to supply the message type or subscription ID
 281 in the message as neither are used by RMR; they may be required by the
 282 peer application depending on the application level protocol(s) in
 283 use.
 284
 285 &proto_start
 286 extern int rmr_wh_state( void* vctx, rmr_whid_t whid );
 287 &proto_end
 288 This function returns an indication of whether or not the connection referenced by
 289 the wormhole ID (whid) is open or closed.
 290
 291
 292 .** ------------------------------------
 293 &space
 294 &h2(Message Buffer Functions)
 295 The message buffer functions operate directly on a message buffer, and
 296 as such do not require that RMR context as a parameter.
 297 &space
 298
 299 &proto_start
 300 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 301 &proto_end
 302 Copy the bytes referenced by &ital(src) to the &ital(meid) field in
 303 the RMR message header.  Up to &ital(len) bytes are copied, though the
 304 maximum length of the field as governed by &cw(RMR_MAX_MEID) is
 305 enforced.
 306
 307 &proto_start
 308 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 309 &proto_end
 310 This function copies &ital(len) bytes from &ital(src) into the message
 311 buffer payload.  This function is primarily provided to support
 312 wrappers which don't directly support C pointers.
 313
 314 &proto_start
 315 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
 316 &proto_end
 317 This function copies &ital(len) bytes of data from &ital(src) to the
 318 transaction ID field in the message buffer.  The number of bytes
 319 provided will be limited to a maximum of &cw(RMR_MAX_XID.)
 320
 321 &proto_start
 322 void rmr_free_msg( rmr_mbuf_t* mbuf );
 323 &proto_end
 324 This function should be used by the application to release the storage
 325 used by a message buffer.
 326
 327 &proto_start
 328 unsigned char*  rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
 329 &proto_end
 330 The bytes from the &cw(meid) field of the message buffer are copied to
 331 the &ital(dest) buffer provided by the application.  The full field of
 332 &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that
 333 &ital(dest) is large enough.  If the destination buffer pointer passed
 334 in is a nil pointer, the function will allocate a buffer and return a
 335 pointer to the buffer, which the caller is expected to free.
 336
 337 &proto_start
 338 unsigned char*  rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
 339 &proto_end
 340 The source of a message is copied to the &ital(dest) buffer provided
 341 by the caller.  This is generally the hostname and port, separated by
 342 a colon, of the application which sent the message, and is a zero
 343 terminated string.  Up to &cw(RMR_MAX_SRC) bytes will be copied, so
 344 the caller must ensure that &ital(dest) is at least this large.
 345
 346 &proto_start
 347 unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
 348 &proto_end
 349 This function copies the source IP address and port, separated by a
 350 colon, to the &ital(dest) buffer provided by the caller.  This is the
 351 address of the application which sent the message.  Up to
 352 &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that
 353 &ital(dest) is at least this large.
 354
 355 &proto_start
 356 int rmr_get_trlen( rmr_mbuf_t* msg );
 357 &proto_end
 358 This function can be used to determine the size of the trace
 359 information in the message buffer. If no trace data is present, then 0
 360 is returned.
 361
 362 &proto_start
 363 int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
 364 &proto_end
 365 The bytes from the trace data, up to &tial(size) bytes, is copied from
 366 the message buffer to the &ital(dest) buffer provided by the caller.
 367 The return value is the number of bytes actually copied.
 368
 369 &proto_start
 370 unsigned char*  rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest );
 371 &proto_end
 372 The bytes from the &ital(transaction) field in the message buffer are
 373 copied to the &ital(dest) buffer provided by the application.  The
 374 full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must
 375 ensure that &ital(dest) is large enough.  If the destination buffer
 376 pointer passed in is a nil pointer, the function will allocate a
 377 buffer and return a pointer to the buffer, which the caller is
 378 expected to free.
 379
 380 &proto_start
 381 int rmr_payload_size( rmr_mbuf_t* msg );
 382 &proto_end
 383 This function returns the number of bytes in the message buffer's
 384 payload that are available for the application to use.
 385
 386 &proto_start
 387 rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
 388 &proto_end
 389 This function allows the application to reallocate a message buffer
 390 with a different trace data size.  The contents of the message buffer
 391 supplied are copied to the new buffer, and a reference to the new
 392 buffer is returned.
 393
 394 &proto_start
 395 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* old_msg, int new_len, int copy, int clone );
 396 &proto_end
 397 This function allows the user programme to realloc the payload with a
 398 larger length.
 399 Optionally, the user programme may use this function to clone an existing
 400 message while extending the payload size.
 401 In both cases the message can be passed to a return to sender call as
 402 the source information from the original message is preserved.
 403
 404 &proto_start
 405 int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
 406 &proto_end
 407 The &ital(size) bytes, up to the size of the trace data in the message
 408 buffer, at &ital(data) are copied to the trace portion of the message
 409 buffer.  The return value is the actual number of bytes copied which
 410 could be less than the number requested.
 411
 412 &proto_start
 413 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
 414 &proto_end
 415 Accepts a pointer to a zero terminated string an copies it to the
 416 &cw(meid) field in the message header.  Up to &cw(RMR_MAX_MEID) bytes
 417 are copied (including the final 0), and the number copied is returned.
 418
 419 &proto_start
 420 void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
 421 &proto_end
 422 Accepts a pointer to a zero terminated string, and copies the string
 423 to the payload portion of the message buffer.  If the string is longer
 424 than the allocated payload, the string will be truncated and will
 425 &bold(not) be terminated with a zero byte.
 426
 427 &proto_start
 428 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
 429 &proto_end
 430 Accepts a pointer to a zero terminated string and copies the string to
 431 the transaction ID portion of the message buffer.  If the string is
 432 longer than &cw(RMR_MAX_XID,) the string will be truncated and will
 433 &bold(not) be zero terminated.
 434
 435 &proto_start
 436 void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
 437 &proto_end
 438 This function returns a pointer to the trace information in the
 439 message buffer.  The intent is that the application will treat this as
 440 a read/only field and will not write trace data into the message
 441 buffer.  The length of data available should be determined by calling
 442 &func(rmr_get_trlen:.)