1 // : vi ts=4 sw=4 noet :
3 ==================================================================================
4 Copyright (c) 2019 Nokia
5 Copyright (c) 2018-2019 AT&T Intellectual Property.
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
11 http://www.apache.org/licenses/LICENSE-2.0
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18 ==================================================================================
23 Abstract: General (public) header file for the uta message routing library
24 Author: E. Scott Daniels
25 Date: 27 November 2018
31 #include <sys/epoll.h> // broken on mac
38 #define RMR_MAX_XID 32 // space in header reserved for user xaction id
39 #define RMR_MAX_MEID 32 // spece in header reserved for managed element id
40 #define RMR_MAX_SRC 64 // max length of hostname (which could be IPv6 addr with [...]:port so more than the 39 bytes of a plain addr
41 #define RMR_MAX_SID 32 // misc sender info/data (reserved)
44 #define RMR_MAX_RCV_BYTES 1024 * 2 // DEPRECATED CONSTANT NAME as underlying transport no longer have a max receive size
45 #define RMR_DEF_MSG_SIZE 1024 // default message size that applications might want to use
47 // various flags for function calls
48 #define RMRFL_NONE 0x00 // no flags
49 #define RMRFL_NOTHREAD 0x01 // do not start an additional route collector thread
50 #define RMRFL_MTCALL 0x02 // set up multi-threaded call support (rmr_init)
51 #define RMRFL_AUTO_ALLOC 0x03 // send auto allocates a zerocopy buffer
52 #define RMRFL_NAME_ONLY 0x04 // only the hostname:ip is provided as source information for rts() calls
53 #define RMRFL_NOLOCK 0x08 // disable receive ring locking (user app ensures single thread or provides collision protection)
55 #define RMR_DEF_SIZE 0 // pass as size to have msg allocation use the default msg size
57 #define RMR_VOID_MSGTYPE (-1) // unset/invalid message type and sub id
58 #define RMR_VOID_SUBID (-1)
60 #define RMR_OK 0 // state is good
61 #define RMR_ERR_BADARG 1 // argument passd to function was unusable
62 #define RMR_ERR_NOENDPT 2 // send/call could not find an endpoint based on msg type
63 #define RMR_ERR_EMPTY 3 // msg received had no payload; attempt to send an empty message
64 #define RMR_ERR_NOHDR 4 // message didn't contain a valid header
65 #define RMR_ERR_SENDFAILED 5 // send failed; errno has nano reason
66 #define RMR_ERR_CALLFAILED 6 // unable to send call() message
67 #define RMR_ERR_NOWHOPEN 7 // no wormholes are open
68 #define RMR_ERR_WHID 8 // wormhole id was invalid
69 #define RMR_ERR_OVERFLOW 9 // operation would have busted through a buffer/field size
70 #define RMR_ERR_RETRY 10 // request (send/call/rts) failed, but caller should retry (EAGAIN for wrappers)
71 #define RMR_ERR_RCVFAILED 11 // receive failed (hard error)
72 #define RMR_ERR_TIMEOUT 12 // message processing call timed out
73 #define RMR_ERR_UNSET 13 // the message hasn't been populated with a transport buffer
74 #define RMR_ERR_TRUNC 14 // received message likely truncated
75 #define RMR_ERR_INITFAILED 15 // initialisation of something (probably message) failed
76 #define RMR_ERR_NOTSUPP 16 // the request is not supported, or RMr was not initialised for the request
78 #define RMR_NO_CLONE 0 // parm constants for better readability
83 #define RMR_WH_CONNECTED(a) (a>=0) // for now whid is integer; it could be pointer at some future date
86 General message buffer. Passed to send and returned by receive.
88 (All fields are exposed such that if a wrapper needs to dup the storage as it passes
89 into or out of their environment they dup it all, not just what we choose to expose.)
92 State is the RMR state of processing on the message. The transport state (tp_state)
93 will be set to mirror the value of errno for wrappers unable to access errno directly,
94 but will only be set if state is not RMR_OK. Even then, the value may be suspect as
95 the underlying transport mechanism may not set errno. It is strongly recommended that
96 user applications use tp_state only for dianostic purposes to convey additional information
100 int state; // state of processing
101 int mtype; // message type
102 int len; // length of data in the payload (send or received)
103 unsigned char* payload; // transported data
104 unsigned char* xaction; // pointer to fixed length transaction id bytes
105 int sub_id; // subscription id
106 int tp_state; // transport state (errno) valid only if state != RMR_OK, and even then may not be valid
108 // these things are off limits to the user application
109 void* tp_buf; // underlying transport allocated pointer (e.g. nng message)
110 void* header; // internal message header (whole buffer: header+payload)
111 unsigned char* id; // if we need an ID in the message separate from the xaction id
112 int flags; // various MFL_ (private) flags as needed
113 int alloc_len; // the length of the allocated space (hdr+payload)
115 void* ring; // ring this buffer should be queued back to
116 int rts_fd; // SI fd for return to sender
118 int cookie; // cookie to detect user misuse of free'd msg
122 typedef int rmr_whid_t; // wormhole identifier returned by rmr_wh_open(), passed to rmr_wh_send_msg()
125 // ---- library message specific prototypes ------------------------------------------------------------
126 extern rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size );
127 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
128 extern void rmr_close( void* vctx );
129 extern void rmr_set_fack( void* vctx );
130 extern void* rmr_init( char* proto_port, int max_msg_size, int flags );
131 extern int rmr_init_trace( void* vctx, int size );
132 extern int rmr_payload_size( rmr_mbuf_t* msg );
133 extern rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
134 extern rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
135 extern rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
136 extern rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect, int allow2queue );
137 extern rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
138 extern int rmr_ready( void* vctx );
139 extern int rmr_set_rtimeout( void* vctx, int time );
140 extern int rmr_set_stimeout( void* vctx, int time );
141 extern int rmr_get_rcvfd( void* vctx ); // only supported with nng
142 extern void rmr_set_low_latency( void* vctx );
143 extern rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
144 extern rmr_mbuf_t* rmr_tralloc_msg( void* context, int msize, int trsize, unsigned const char* data );
145 extern rmr_whid_t rmr_wh_open( void* vctx, char const* target );
146 extern rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait );
147 extern rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
148 extern int rmr_wh_state( void* vctx, rmr_whid_t whid );
149 extern void rmr_wh_close( void* vctx, int whid );
151 // ----- mt call support --------------------------------------------------------------------------------
152 extern rmr_mbuf_t* rmr_mt_call( void* vctx, rmr_mbuf_t* mbuf, int call_id, int max_wait );
153 extern rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* mbuf, int max_wait );
155 // ----- msg buffer operations (no context needed) ------------------------------------------------------
156 extern int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
157 extern void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
158 extern int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
159 extern void rmr_free_msg( rmr_mbuf_t* mbuf );
160 extern unsigned char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
161 extern unsigned char* rmr_get_src( rmr_mbuf_t* mbuf, unsigned char* dest );
162 extern unsigned char* rmr_get_srcip( rmr_mbuf_t* msg, unsigned char* dest );
163 extern unsigned char* rmr_get_xact( rmr_mbuf_t* mbuf, unsigned char* dest );
164 extern rmr_mbuf_t* rmr_realloc_msg( rmr_mbuf_t* mbuf, int new_tr_size );
165 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* old_msg, int new_len, int copy, int clone );
166 extern int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
167 extern void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
168 extern void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
169 extern int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
170 extern void* rmr_trace_ref( rmr_mbuf_t* msg, int* sizeptr );
172 extern int rmr_get_trlen( rmr_mbuf_t* msg );
173 extern int rmr_get_trace( rmr_mbuf_t* msg, unsigned char* dest, int size );
174 extern int rmr_set_trace( rmr_mbuf_t* msg, unsigned const char* data, int size );
176 extern int rmr_rcv_to( void* vctx, int time ); // DEPRECATED -- replaced with set_rtimeout
177 extern int rmr_send_to( void* vctx, int time ); // DEPRECATED -- replaced with set_stimeout
179 // ---- misc user interface stuff ----------------------------------------------------------------------
180 extern void rmr_set_vlevel( int new_level );
182 // --- uta compatability defs if needed user should define UTA_COMPAT ----------------------------------
184 #pragma message( "use of UTA_COMPAT is deprecated and soon to be removed" )
186 #define UTA_MAX_XID RMR_MAX_XID
187 #define UTA_MAX_SID RMR_MAX_SID
188 #define UTA_MAX_SRC RMR_MAX_SRC
189 #define UTA_MAX_RCV_BYTES RMR_MAX_RCV_BYTES
191 #define UTAFL_NONE RMRFL_NONE
192 #define UTAFL_AUTO_ALLOC RMRFL_AUTO_ALLOC
194 #define UTA_DEF_SIZE RMRFL_AUTO_ALLOC
196 #define UTA_OK RMR_OK
197 #define UTA_ERR_BADARG RMR_ERR_BADARG
198 #define UTA_ERR_NOENDPT RMR_ERR_NOENDPT
199 #define UTA_ERR_EMPTY RMR_ERR_EMPTY
200 #define UTA_ERR_NOHDR RMR_ERR_NOHDR
201 #define UTA_ERR_SENDFAILED RMR_ERR_SENDFAILED
202 #define UTA_ERR_CALLFAILED RMR_ERR_CALLFAILED
204 #define uta_mbuf_t rmr_mbuf_t
206 #define uta_alloc_msg rmr_alloc_msg
207 #define uta_call rmr_call
208 #define uta_free_msg rmr_free_msg
209 #define uta_init rmr_init
210 #define uta_payload_size rmr_payload_size
211 #define uta_send_msg rmr_send_msg
212 #define uta_rcv_msg rmr_rcv_msg
213 #define uta_rcv_specific rmr_rcv_specific
214 #define uta_rcv_to rmr_rcv_to
215 #define uta_rts_msg rmr_rts_msg
216 #define uta_ready rmr_ready
217 #define uta_send_to rmr_send_to
225 #endif // dup include prevention