2 ==================================================================================
3 Copyright (c) 2019-2020 Nokia
4 Copyright (c) 2018-2020 AT&T Intellectual Property.
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
10 http://www.apache.org/licenses/LICENSE-2.0
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 ==================================================================================
22 Abstract: A quick reference to all external function calls
24 Author: E. Scott Daniels
27 &h1(Appendix &qr_appendix -- Quick Reference)
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.
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).
41 rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size );
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
53 rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
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:.)
66 void rmr_close( void* vctx );
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.
75 extern void rmr_set_fack( void* vctx );
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.
82 extern void rmr_set_vlevel( int new_level );
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.
90 int rmr_get_rcvfd( void* vctx );
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.
98 void* rmr_init( char* proto_port, int def_msg_size, int flags );
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:.)
107 rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait );
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.
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
120 rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
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.
132 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait );
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.
139 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
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.
151 int rmr_init_trace( void* vctx, int size );
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.
159 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
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.
169 rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect,
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:.)
178 int rmr_ready( void* vctx );
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.
189 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
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.
201 int rmr_set_rtimeout( void* vctx, int time );
203 This function became deprecated with the elimination of support for Nanomsg.
204 See &cw(rmr_torcv_msg().)
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.
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
222 int rmr_set_stimeout( void* vctx, int rounds );
224 This function became deprecated with the elimination of support for Nanomsg.
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.
236 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
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.)
245 rmr_mbuf_t* rmr_tralloc_msg( void* context, int msize, int trsize,
246 unsigned const char* data );
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.
253 void rmr_wh_close( void* vctx, int whid );
255 This function closes an existing wormhole connection.
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 );
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
266 rmr_whid_t rmr_wh_open( void* vctx, char const* target );
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.
277 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
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
288 extern int rmr_wh_state( void* vctx, rmr_whid_t whid );
290 This function returns an indication of whether or not the connection referenced by
291 the wormhole ID (whid) is open or closed.
294 .** ------------------------------------
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.
302 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
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
310 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
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.
317 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
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.)
324 void rmr_free_msg( rmr_mbuf_t* mbuf );
326 This function should be used by the application to release the storage
327 used by a message buffer.
330 unsigned char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
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.
340 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
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.
349 unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
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.
358 int rmr_get_trlen( rmr_mbuf_t* msg );
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
365 int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
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.
372 unsigned char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest );
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
383 int rmr_payload_size( rmr_mbuf_t* msg );
385 This function returns the number of bytes in the message buffer's
386 payload that are available for the application to use.
389 rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
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
397 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* old_msg, int new_len,
398 int copy, int clone );
400 This function allows the user programme to realloc the payload with a
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.
408 int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
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.
416 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
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.
423 void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
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.
431 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
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.
439 void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
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:.)