2 ==================================================================================
3 Copyright (c) 2019 Nokia
4 Copyright (c) 2018-2019 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)
28 The prototype for each of the externally available functions which comprise the RMR API is listed
29 in alphabetical order below.
30 For each prototype a brief description of the function is given.
31 The developer is encouraged to install the RMR development package which contains the manual pages.
32 The manual pages completely describe each function in a level of detail consistent with UNIX man pages.
34 &h2(Context Specific Functions)
35 These functions require that the RMR context (provided as the result of an &func(rmr_init:) call, be
36 passed as the first argument (vctx).
39 rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size );
41 This function allocates a &ital(zero copy) message buffer.
42 The payload portion is allocated from the underlying transport space such that on send the buffer
43 does not require a second copy.
44 The size parameter is the size of the payload portion of the buffer; if the recipient of the
45 message is expected to send a response, this should be large enough to accomodate the response
46 which will enable the remote application to reuse the message for the response and avoid a costly
50 rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
52 The call function accepts a message, selects an endpoint to receive the message and sends the message.
53 RMR will block the return to the application until a matching response is received, or a timeout period
55 The transaction ID in the outbound message is used to match a response, so it is imperative that
56 the application making the response reuse the received message, or copy the transaction ID to the new
57 message before sending.
58 Messages arriving which do not match the expected response are queued and will be delivered to the
59 application on subsequent calls to &func(rmr_rcv_msg:.)
62 void rmr_close( void* vctx );
64 This function terminates all sessions with the underlying transport mechanism.
65 Buffers pending may or may not be flushed (depending on the underlying mechanism), thus it is
66 recommended that before using this function the application pause for a second or two to
67 ensure that the pending transmissions have completed.
70 int rmr_get_rcvfd( void* vctx );
72 When the underlying transport mechanism supports this, a file descriptor suitable for use with
73 the &cw(select, poll) and &cw(epoll) system calls is returned.
74 The file descriptor may not be used for read or write operations; doing so will have unpredictable
78 void* rmr_init( char* proto_port, int max_msg_size, int flags );
80 This function must be used before all other RMR functions to initialise the environment.
81 The &cw(max_msg_size) parameter defines the maximum receive buffer size which will be
82 used if required by the underlying transport mechanism.
83 The value is also used as the default payload size if a zero length is given to &func(rmr_alloc_msg:.)
86 rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait );
88 Similar to the &func(rmr_call:) function, the message is sent to an endpoint and a response message
90 This call is thread safe, and while the thread that invokes this function blocks on the response,
91 it is possible for other application threads to continue to receive messages via the &func(rmr_rcv_msg:)
94 In order to use the multi-threaded call functions, the option to enable threaded receive support
95 must be set on the call to &func(rmr_init:.)
98 rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
100 This function sends the provided message allowing RMR to retry soft failures for approximately
101 &ccw(max_to) milliseconds.
102 When a value of zero (0) is given for the maximum timeout, RMR will not attempt any retires
103 and will return the state after the first attempt.
104 It is unlikely that a user application will use this function as it is possible (and recommended)
105 to set the max timeout via the specific, one time, function call, and then to allow that value
106 to be used as the default when &func(rmr_send_msg:) is invoked.
109 rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait );
111 This function waits for a message to arrive and returns a message buffer with the received
113 The function will timeout after &cw(max_wait) milliseconds (approximately) if no message is
117 rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
119 This function accepts a message, selects a destination endpoint using the message type and subscription ID,
120 and then attempts to send the message to the destination.
121 The function returns a message buffer to the caller with the state set to indicate the state of the
123 On success, the message buffer is a new buffer that the application can "fill in," and send without the
124 need to overtly allocate a new buffer.
125 On failure, the message buffer is the buffer that the application attempted to send.
128 int rmr_init_trace( void* vctx, int size );
130 This function is used to set the default trace data size.
131 The size defaults to zero until this function is called; after the application sets a non-zero value
132 messages created with the &func(rmr_alloc_msg:) function will be allocated with trace data set to
136 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
138 The &func(rmr_rcv_msg:) function is used to block and wait for a message to arrive.
139 When a message is received a pointer to an RMR message buffer structure is returned to the caller.
140 The &cw(old_msg) parameter allows the application to to pass a message buffer for reuse.
141 If the application does not have an old buffer, a nil pointer is given and the function will
142 allocate a new buffer.
145 rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect,
148 This function blocks until a message with a specific transaction ID is received.
149 If the &cw(allowd2queue) parameter is set to 1, messagess which do not match the ID are queued
150 and returned to the application on subsequent calls to &func(rmr_rcv_msg:.)
154 int rmr_ready( void* vctx );
156 This function is used to test whether RMR is capable of sending messages.
157 In other words once this function returns true (!0) RMR has received a route table (either from a static
158 file or from a route manager process, and can map message types to endpoints.
159 If the application attempts to send a message before this function returns true, the sends
161 Applications which are only message receivers do not need to use this function.
164 rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
166 The &func(rmr_rts_msg:) function allows the application to send a response message to the endpoint
167 from which the message originated.
168 This requires that the application use the same message buffer that was received for the
169 response as it contains the sender information that is needed for this function to be successful.
170 If the message cannot be sent, a pointer to the message buffer is returned and the status in the
171 message buffer is set to indicate the reason.
172 On success, a nil pointer will be returned.
176 int rmr_set_rtimeout( void* vctx, int time );
178 This function provides the ability to return from a receive operation after a timeout threshold
179 is reached before a message is received, and is intended only to support the underlying Nanomsg
180 transport mechanism (support for Nanomsg is deprecated).
181 The &func(rmr_torcv_msg) function should be used if timed receives are required.
184 For transport mechanisms which support a receive timeout, this function allows the application to
185 set a default timeout for receive operations.
186 If a call to &func(rmr_rcv_msg) does not complete before &ital(time) milliseconds has elapsed,
187 the receive function will return a nil message buffer.
188 This may not be supported by the underlying transport mechanism, and if it is not the return
189 from this function will be -1.
192 int rmr_set_stimeout( void* vctx, int rounds );
194 This function allows the application to set a maximum number of retry &ital(rounds) that RMR will
195 attempt when send operations report a transient (retry) failure.
196 Each &ital(round) of retries requires approximately 1 millisecond, and setting the number of
197 rounds to zero (0) causes RMR to report the transient failure to the application without
199 If the user application does not invoke this function, the default is one (1) round of retries.
202 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
204 This function because identically to the &func(rmr_rcv_msg) function, and allows the application to
205 set a specific timeout value for the receive operation.
206 If a message is not received before the timeout period expires (ms_to milliseconds), a message buffer
207 is returned with the state set to &cw(RMR_ERR_TIMEOUT.)
211 rmr_mbuf_t* rmr_tralloc_msg( void* context, int msize, int trsize,
212 unsigned const char* data );
214 Similar to the &func(rmr_alloc_msg) this function allocates a message buffer, and adds the
215 referenced trace data to the buffer.
216 The new message buffer is returned.
219 void rmr_wh_close( void* vctx, int whid );
221 This function closes an existing wormhole connection.
225 rmr_whid_t rmr_wh_open( void* vctx, char const* target );
227 This function allows the application to create a &ital(wormhole,) direct, connection to another application.
228 The peer application must also be using RMR (messages sent on a wormhole connection are RMR messages).
229 The target may be a hostname:port or IP-address:port combination.
230 Upon successful completion, the &ital(wormhole ID) is returned; this ID must be passed on all
231 subsequent calls to wormhole functions for this connection.
234 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
236 Once a wormhole has been established to a peer application, this function allows the application
237 to send a message to the peer.
238 All semantics of normal RMR sends (retries, etc.) are observed.
239 The application may opt not to supply the message type or subscription ID in the message as
240 neither are used by RMR; they may be required by the peer application depending on the application
241 level protocol(s) in use.
244 .** ------------------------------------
246 &h2(Message Buffer Functions)
247 The message buffer functions operate directly on a message buffer, and as such do not
248 require that RMR context as a parameter.
252 int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
254 Copy the bytes referenced by &ital(src) to the &ital(meid) field in the RMR message header.
255 Up to &ital(len) bytes are copied, though the maximum length of the field as
256 governed by &cw(RMR_MAX_MEID) is enforced.
259 void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
261 This function copies &ital(len) bytes from &ital(src) into the message buffer payload.
262 This function is primarily provided to support wrappers which don't directly support
267 int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
269 This function copies &ital(len) bytes of data from &ital(src) to the transaction ID
270 field in the message buffer.
271 The number of bytes provided will be limited to a maximum of &cw(RMR_MAX_XID.)
274 void rmr_free_msg( rmr_mbuf_t* mbuf );
276 This function should be used by the application to release the storage used by a message buffer.
279 unsigned char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
281 The bytes from the &cw(meid) field of the message buffer are copied to the &ital(dest) buffer
282 provided by the application.
283 The full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that &ital(dest)
285 If the destination buffer pointer passed in is a nil pointer, the function will allocate a buffer
286 and return a pointer, which the caller is expected to free, to the buffer.
289 unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
291 The source of a message is copied to the &ital(dest) buffer provided by the caller.
292 This is generally the hostname and port, separated by a colon, of the application
293 which sent the message, and is a zero terminated string.
294 Up to &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that &ital(dest)
295 is at least this large.
298 unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
300 This function copies the source IP address and port, separated by a colon, to the
301 &ital(dest) buffer provided by the caller.
302 This is the address of the application which sent the message.
303 Up to &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that &ital(dest)
304 is at least this large.
307 int rmr_get_trlen( rmr_mbuf_t* msg );
309 This function can be used to determine the size of the trace information in the message buffer.
310 If no trace data is present, then 0 is returned.
313 int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
315 The bytes from the trace data, up to &tial(size) bytes, is copied from the message buffer
316 to the &ital(dest) buffer provided by the caller.
317 The return value is the number of bytes actually copied.
320 unsigned char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest );
322 The bytes from the &ital(transaction) field in the message buffer are copied to the &ital(dest) buffer
323 provided by the application.
324 The full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that &ital(dest)
326 If the destination buffer pointer passed in is a nil pointer, the function will allocate a buffer
327 and return a pointer, which the caller is expected to free, to the buffer.
330 int rmr_payload_size( rmr_mbuf_t* msg );
332 This function returns the number of bytes in the message buffer's payload that are available
333 for the application to use.
337 rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
339 This function allows the application to reallocate a message buffer with a different trace
341 The contents of the message buffer supplied are copied to the new buffer, and a reference to
342 the new buffer is returned.
345 int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
347 The &ital(size) bytes, up to the size of the trace data in the message buffer,
348 at &ital(data) are copied to the trace portion of the message buffer.
349 The return value is the actual number of bytes copied which could be less than the number
354 int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
356 Accepts a pointer to a zero terminated string an copies it to the &cw(meid) field in the
358 Up to &cw(RMR_MAX_MEID) bytes are copied (including the final 0), and the number
362 void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
364 Accepts a pointer to a zero terminated string, and copies the string to the payload
365 portion of the message buffer.
366 If the string is longer than the allocated payload, the string will be truncated
367 and will &bold(not) be terminated with a zero byte.
371 int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
373 Accepts a pointer to a zero terminated string and copies the string to the transaction ID
374 portion of the message buffer.
375 If the string is longer than &cw(RMR_MAX_XID,) the string will be truncated and will &bold(not)
379 void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
381 This function returns a pointer to the trace information in the message buffer.
382 The intent is that the application will treat this as a read/only field and will not
383 write trace data into the message buffer.
384 The length of data available should be determined by calling &func(rmr_get_trlen:.)