src/rmr/common/include/rmr.h

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