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_SID 32 // spece in header reserved for sender id
40 #define RMR_MAX_MEID 32 // spece in header reserved for managed element id
41 #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
42 #define RMR_MAX_RCV_BYTES 4096 // max bytes we support in a receive message
44 // various flags for function calls
45 #define RMRFL_NONE 0x00 // no flags
46 #define RMRFL_AUTO_ALLOC 0x01 // send auto allocates a zerocopy buffer
48 #define RMR_DEF_SIZE 0 // pass as size to have msg allocation use the default msg size
51 #define RMR_OK 0 // state is good
52 #define RMR_ERR_BADARG 1 // argument passd to function was unusable
53 #define RMR_ERR_NOENDPT 2 // send/call could not find an endpoint based on msg type
54 #define RMR_ERR_EMPTY 3 // msg received had no payload; attempt to send an empty message
55 #define RMR_ERR_NOHDR 4 // message didn't contain a valid header
56 #define RMR_ERR_SENDFAILED 5 // send failed; errno has nano reason
57 #define RMR_ERR_CALLFAILED 6 // unable to send call() message
58 #define RMR_ERR_NOWHOPEN 7 // no wormholes are open
59 #define RMR_ERR_WHID 8 // wormhole id was invalid
60 #define RMR_ERR_OVERFLOW 9 // operation would have busted through a buffer/field size
61 #define RMR_ERR_RETRY 10 // request (send/call/rts) failed, but caller should retry (EAGAIN for wrappers)
62 #define RMR_ERR_RCVFAILED 11 // receive failed (hard error)
63 #define RMR_ERR_TIMEOUT 12 // message processing call timed out
64 #define RMR_ERR_UNSET 13 // the message hasn't been populated with a transport buffer
65 #define RMR_ERR_TRUNC 14 // received message likely truncated
67 #define RMR_WH_CONNECTED(a) (a>=0) // for now whid is integer; it could be pointer at some future date
70 General message buffer. Passed to send and returned by receive.
72 (All fields are exposed such that if a wrapper needs to dup the storage as it passes
73 into or out of their environment they dup it all, not just what we choose to expose.)
76 int state; // state of processing
77 int mtype; // message type
78 int len; // length of data in the payload (send or received)
79 unsigned char* payload; // transported data
80 unsigned char* xaction; // pointer to fixed length transaction id bytes
82 // these things are off limits to the user application
83 void* tp_buf; // underlying transport allocated pointer (e.g. nng message)
84 void* header; // internal message header (whole buffer: header+payload)
85 unsigned char* id; // if we need an ID in the message separate from the xaction id
86 int flags; // various MFL_ (private) flags as needed
87 int alloc_len; // the length of the allocated space (hdr+payload)
91 typedef int rmr_whid_t; // wormhole identifier returned by rmr_wh_open(), passed to rmr_wh_send_msg()
94 // ---- library message specific prototypes ------------------------------------------------------------
95 extern rmr_mbuf_t* rmr_alloc_msg( void* vctx, int size );
96 extern rmr_mbuf_t* rmr_call( void* vctx, rmr_mbuf_t* msg );
97 extern void rmr_close( void* vctx );
98 extern void* rmr_init( char* proto_port, int max_msg_size, int flags );
99 extern int rmr_payload_size( rmr_mbuf_t* msg );
100 extern rmr_mbuf_t* rmr_send_msg( void* vctx, rmr_mbuf_t* msg );
101 extern rmr_mbuf_t* rmr_mtosend_msg( void* vctx, rmr_mbuf_t* msg, int max_to );
102 extern rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
103 extern rmr_mbuf_t* rmr_rcv_specific( void* uctx, rmr_mbuf_t* msg, char* expect, int allow2queue );
104 extern rmr_mbuf_t* rmr_rts_msg( void* vctx, rmr_mbuf_t* msg );
105 extern int rmr_ready( void* vctx );
106 extern int rmr_set_rtimeout( void* vctx, int time );
107 extern int rmr_set_stimeout( void* vctx, int time );
108 extern int rmr_get_rcvfd( void* vctx ); // only supported with nng
109 extern rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
110 extern rmr_whid_t rmr_wh_open( void* vctx, char const* target );
111 extern rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg );
112 extern void rmr_wh_close( void* vctx, int whid );
115 // ----- msg buffer operations (no context needed) ------------------------------------------------------
116 extern int rmr_bytes2meid( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
117 extern void rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
118 extern int rmr_bytes2xact( rmr_mbuf_t* mbuf, unsigned char const* src, int len );
119 extern void rmr_free_msg( rmr_mbuf_t* mbuf );
120 extern unsigned char* rmr_get_meid( rmr_mbuf_t* mbuf, unsigned char* dest );
121 extern int rmr_str2meid( rmr_mbuf_t* mbuf, unsigned char const* str );
122 extern void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
123 extern void rmr_str2payload( rmr_mbuf_t* mbuf, unsigned char const* str );
124 extern int rmr_str2xact( rmr_mbuf_t* mbuf, unsigned char const* str );
127 extern int rmr_rcv_to( void* vctx, int time ); // DEPRECATED -- replaced with set_rtimeout
128 extern int rmr_send_to( void* vctx, int time ); // DEPRECATED -- replaced with set_stimeout
131 // --- uta compatability defs if needed user should define UTA_COMPAT ----------------------------------
133 #pragma message( "use of UTA_COMPAT is deprecated and soon to be removed" )
135 #define UTA_MAX_XID RMR_MAX_XID
136 #define UTA_MAX_SID RMR_MAX_SID
137 #define UTA_MAX_SRC RMR_MAX_SRC
138 #define UTA_MAX_RCV_BYTES RMR_MAX_RCV_BYTES
140 #define UTAFL_NONE RMRFL_NONE
141 #define UTAFL_AUTO_ALLOC RMRFL_AUTO_ALLOC
143 #define UTA_DEF_SIZE RMRFL_AUTO_ALLOC
145 #define UTA_OK RMR_OK
146 #define UTA_ERR_BADARG RMR_ERR_BADARG
147 #define UTA_ERR_NOENDPT RMR_ERR_NOENDPT
148 #define UTA_ERR_EMPTY RMR_ERR_EMPTY
149 #define UTA_ERR_NOHDR RMR_ERR_NOHDR
150 #define UTA_ERR_SENDFAILED RMR_ERR_SENDFAILED
151 #define UTA_ERR_CALLFAILED RMR_ERR_CALLFAILED
153 #define uta_mbuf_t rmr_mbuf_t
155 #define uta_alloc_msg rmr_alloc_msg
156 #define uta_call rmr_call
157 #define uta_free_msg rmr_free_msg
158 #define uta_init rmr_init
159 #define uta_payload_size rmr_payload_size
160 #define uta_send_msg rmr_send_msg
161 #define uta_rcv_msg rmr_rcv_msg
162 #define uta_rcv_specific rmr_rcv_specific
163 #define uta_rcv_to rmr_rcv_to
164 #define uta_rts_msg rmr_rts_msg
165 #define uta_ready rmr_ready
166 #define uta_send_to rmr_send_to
174 #endif // dup include prevention