.if false ================================================================================== Copyright (c) 2019 Nokia Copyright (c) 2018-2019 AT&T Intellectual Property. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================================================== .fi .if false Mnemonic: api_qr.im Abstract: A quick reference to all external function calls Date: 2 August, 2019 Author: E. Scott Daniels .fi &h1(Appendix &qr_appendix -- Quick Reference) The prototype for each of the externally available functions which comprise the RMR API is listed in alphabetical order below. For each prototype a brief description of the function is given. The developer is encouraged to install the RMR development package which contains the manual pages. The manual pages completely describe each function in a level of detail consistent with UNIX man pages. &h2(Context Specific Functions) These functions require that the RMR context (provided as the result of an &func(rmr_init:) call, be passed as the first argument (vctx). &proto_start rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size ); &proto_end This function allocates a &ital(zero copy) message buffer. The payload portion is allocated from the underlying transport space such that on send the buffer does not require a second copy. The size parameter is the size of the payload portion of the buffer; if the recipient of the message is expected to send a response, this should be large enough to accomodate the response which will enable the remote application to reuse the message for the response and avoid a costly reallocation. &proto_start rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg ); &proto_end The call function accepts a message, selects an endpoint to receive the message and sends the message. RMR will block the return to the application until a matching response is received, or a timeout period is reached. The transaction ID in the outbound message is used to match a response, so it is imperative that the application making the response reuse the received message, or copy the transaction ID to the new message before sending. Messages arriving which do not match the expected response are queued and will be delivered to the application on subsequent calls to &func(rmr_rcv_msg:.) &proto_start void rmr_close( void* vctx ); &proto_end This function terminates all sessions with the underlying transport mechanism. Buffers pending may or may not be flushed (depending on the underlying mechanism), thus it is recommended that before using this function the application pause for a second or two to ensure that the pending transmissions have completed. &proto_start int rmr_get_rcvfd( void* vctx ); &proto_end When the underlying transport mechanism supports this, a file descriptor suitable for use with the &cw(select, poll) and &cw(epoll) system calls is returned. The file descriptor may not be used for read or write operations; doing so will have unpredictable results. &proto_start void* rmr_init( char* proto_port, int max_msg_size, int flags ); &proto_end This function must be used before all other RMR functions to initialise the environment. The &cw(max_msg_size) parameter defines the maximum receive buffer size which will be used if required by the underlying transport mechanism. The value is also used as the default payload size if a zero length is given to &func(rmr_alloc_msg:.) &proto_start rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait ); &proto_end Similar to the &func(rmr_call:) function, the message is sent to an endpoint and a response message is waited for. This call is thread safe, and while the thread that invokes this function blocks on the response, it is possible for other application threads to continue to receive messages via the &func(rmr_rcv_msg:) function. &space In order to use the multi-threaded call functions, the option to enable threaded receive support must be set on the call to &func(rmr_init:.) &proto_start rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to ); &proto_end This function sends the provided message allowing RMR to retry soft failures for approximately &ccw(max_to) milliseconds. When a value of zero (0) is given for the maximum timeout, RMR will not attempt any retires and will return the state after the first attempt. It is unlikely that a user application will use this function as it is possible (and recommended) to set the max timeout via the specific, one time, function call, and then to allow that value to be used as the default when &func(rmr_send_msg:) is invoked. &proto_start rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait ); &proto_end This function waits for a message to arrive and returns a message buffer with the received message. The function will timeout after &cw(max_wait) milliseconds (approximately) if no message is received. &proto_start rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg ); &proto_end This function accepts a message, selects a destination endpoint using the message type and subscription ID, and then attempts to send the message to the destination. The function returns a message buffer to the caller with the state set to indicate the state of the send operation. On success, the message buffer is a new buffer that the application can "fill in," and send without the need to overtly allocate a new buffer. On failure, the message buffer is the buffer that the application attempted to send. &proto_start int rmr_init_trace( void* vctx, int size ); &proto_end This function is used to set the default trace data size. The size defaults to zero until this function is called; after the application sets a non-zero value messages created with the &func(rmr_alloc_msg:) function will be allocated with trace data set to the size provided. &proto_start rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg ); &proto_end The &func(rmr_rcv_msg:) function is used to block and wait for a message to arrive. When a message is received a pointer to an RMR message buffer structure is returned to the caller. The &cw(old_msg) parameter allows the application to to pass a message buffer for reuse. If the application does not have an old buffer, a nil pointer is given and the function will allocate a new buffer. &proto_start rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect, int allow2queue ); &proto_end This function blocks until a message with a specific transaction ID is received. If the &cw(allowd2queue) parameter is set to 1, messagess which do not match the ID are queued and returned to the application on subsequent calls to &func(rmr_rcv_msg:.) &proto_start int rmr_ready( void* vctx ); &proto_end This function is used to test whether RMR is capable of sending messages. In other words once this function returns true (!0) RMR has received a route table (either from a static file or from a route manager process, and can map message types to endpoints. If the application attempts to send a message before this function returns true, the sends will fail. Applications which are only message receivers do not need to use this function. &proto_start rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg ); &proto_end The &func(rmr_rts_msg:) function allows the application to send a response message to the endpoint from which the message originated. This requires that the application use the same message buffer that was received for the response as it contains the sender information that is needed for this function to be successful. If the message cannot be sent, a pointer to the message buffer is returned and the status in the message buffer is set to indicate the reason. On success, a nil pointer will be returned. &proto_start int rmr_set_rtimeout( void* vctx, int time ); &proto_end This function provides the ability to return from a receive operation after a timeout threshold is reached before a message is received, and is intended only to support the underlying Nanomsg transport mechanism (support for Nanomsg is deprecated). The &func(rmr_torcv_msg) function should be used if timed receives are required. &space For transport mechanisms which support a receive timeout, this function allows the application to set a default timeout for receive operations. If a call to &func(rmr_rcv_msg) does not complete before &ital(time) milliseconds has elapsed, the receive function will return a nil message buffer. This may not be supported by the underlying transport mechanism, and if it is not the return from this function will be -1. &proto_start int rmr_set_stimeout( void* vctx, int rounds ); &proto_end This function allows the application to set a maximum number of retry &ital(rounds) that RMR will attempt when send operations report a transient (retry) failure. Each &ital(round) of retries requires approximately 1 millisecond, and setting the number of rounds to zero (0) causes RMR to report the transient failure to the application without any retry attempts. If the user application does not invoke this function, the default is one (1) round of retries. &proto_start rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to ); &proto_end This function because identically to the &func(rmr_rcv_msg) function, and allows the application to set a specific timeout value for the receive operation. If a message is not received before the timeout period expires (ms_to milliseconds), a message buffer is returned with the state set to &cw(RMR_ERR_TIMEOUT.) &proto_start rmr_mbuf_t* rmr_tralloc_msg( void* context, int msize, int trsize, unsigned const char* data ); &proto_end Similar to the &func(rmr_alloc_msg) this function allocates a message buffer, and adds the referenced trace data to the buffer. The new message buffer is returned. &proto_start void rmr_wh_close( void* vctx, int whid ); &proto_end This function closes an existing wormhole connection. &proto_start rmr_whid_t rmr_wh_open( void* vctx, char const* target ); &proto_end This function allows the application to create a &ital(wormhole,) direct, connection to another application. The peer application must also be using RMR (messages sent on a wormhole connection are RMR messages). The target may be a hostname:port or IP-address:port combination. Upon successful completion, the &ital(wormhole ID) is returned; this ID must be passed on all subsequent calls to wormhole functions for this connection. &proto_start rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg ); &proto_end Once a wormhole has been established to a peer application, this function allows the application to send a message to the peer. All semantics of normal RMR sends (retries, etc.) are observed. The application may opt not to supply the message type or subscription ID in the message as neither are used by RMR; they may be required by the peer application depending on the application level protocol(s) in use. .** ------------------------------------ &space &h2(Message Buffer Functions) The message buffer functions operate directly on a message buffer, and as such do not require that RMR context as a parameter. &space &proto_start int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len ); &proto_end Copy the bytes referenced by &ital(src) to the &ital(meid) field in the RMR message header. Up to &ital(len) bytes are copied, though the maximum length of the field as governed by &cw(RMR_MAX_MEID) is enforced. &proto_start void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len ); &proto_end This function copies &ital(len) bytes from &ital(src) into the message buffer payload. This function is primarily provided to support wrappers which don't directly support C pointers. &proto_start int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len ); &proto_end This function copies &ital(len) bytes of data from &ital(src) to the transaction ID field in the message buffer. The number of bytes provided will be limited to a maximum of &cw(RMR_MAX_XID.) &proto_start void rmr_free_msg( rmr_mbuf_t* mbuf ); &proto_end This function should be used by the application to release the storage used by a message buffer. &proto_start unsigned char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest ); &proto_end The bytes from the &cw(meid) field of the message buffer are copied to the &ital(dest) buffer provided by the application. The full field of &cw(RMR_MAX_MEID) bytes are copied; the caller must ensure that &ital(dest) is large enough. &proto_start unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest ); &proto_end The source of a message is copied to the &ital(dest) buffer provided by the caller. This is generally the hostname and port, separated by a colon, of the application which sent the message, and is a zero terminated string. Up to &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that &ital(dest) is at least this large. &proto_start unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest ); &proto_end This function copies the source IP address and port, separated by a colon, to the &ital(dest) buffer provided by the caller. This is the address of the application which sent the message. Up to &cw(RMR_MAX_SRC) bytes will be copied, so the caller must ensure that &ital(dest) is at least this large. &proto_start int rmr_get_trlen( rmr_mbuf_t* msg ); &proto_end This function can be used to determine the size of the trace information in the message buffer. If no trace data is present, then 0 is returned. &proto_start int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size ); &proto_end The bytes from the trace data, up to &tial(size) bytes, is copied from the message buffer to the &ital(dest) buffer provided by the caller. The return value is the number of bytes actually copied. &proto_start int rmr_payload_size( rmr_mbuf_t* msg ); &proto_end This function returns the number of bytes in the message buffer's payload that are available for the application to use. &proto_start rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size ); &proto_end This function allows the application to reallocate a message buffer with a different trace data size. The contents of the message buffer supplied are copied to the new buffer, and a reference to the new buffer is returned. &proto_start int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size ); &proto_end The &ital(size) bytes, up to the size of the trace data in the message buffer, at &ital(data) are copied to the trace portion of the message buffer. The return value is the actual number of bytes copied which could be less than the number requested. &proto_start int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str ); &proto_end Accepts a pointer to a zero terminated string an copies it to the &cw(meid) field in the message header. Up to &cw(RMR_MAX_MEID) bytes are copied (including the final 0), and the number copied is returned. &proto_start void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str ); &proto_end Accepts a pointer to a zero terminated string, and copies the string to the payload portion of the message buffer. If the string is longer than the allocated payload, the string will be truncated and will &bold(not) be terminated with a zero byte. &proto_start int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str ); &proto_end Accepts a pointer to a zero terminated string and copies the string to the transaction ID portion of the message buffer. If the string is longer than &cw(RMR_MAX_XID,) the string will be truncated and will &bold(not) be zero terminated. &proto_start void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr ); &proto_end This function returns a pointer to the trace information in the message buffer. The intent is that the application will treat this as a read/only field and will not write trace data into the message buffer. The length of data available should be determined by calling &func(rmr_get_trlen:.)