doc/src/man/rmr_wh_send_msg.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   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
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  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 ==================================================================================
  18 .fi
  19 .if false
  20         Mnemonic        rmr_wh_send_msg_man.xfm
  21         Abstract        The manual page for the rmr_wh_send_msg function.
  22         Author          E. Scott Daniels
  23         Date            28 January 2019
  24 .fi
  25
  26 .** if formatting with tfm, the roff.im will cause roff output to be generated
  27 .** if formatting with pfm, then pretty postscript will be generated
  28 .gv e LIB lib
  29 .if pfm
  30         .im &{lib}/generic_ps.im
  31 .ei
  32         .gv e OUTPUT_RST use_rst
  33         .if .ev &use_rst 1 =
  34                 .im &{lib}/rst.im
  35         .ei
  36                 .im &{lib}/roff.im
  37         .fi
  38 .fi
  39
  40 &line_len(6i)
  41
  42 &h1(RMR Library Functions)
  43 &h2(NAME)
  44         rmr_wh_send_msg
  45
  46 &h2(SYNOPSIS )
  47 &indent
  48 &ex_start
  49 #include <rmr/rmr.h>
  50
  51 rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
  52 &ex_end
  53 &uindent
  54
  55 &h2(DESCRIPTION)
  56 The &cw(rmr_wh_send_msg) function accepts a message buffer from the user application
  57 and attempts to send it using the wormhole ID provided (id).
  58 Unlike &ital(rmr_send_msg,) this function attempts to send the message directly
  59 to a process at the other end of a wormhole which was created with &ital(rmr_wh-open().)
  60 When sending message via wormholes, the normal RMr routing based on message type is
  61 ignored, and the caller may leave the message type unspecified in the message buffer
  62 (unless it is needed by the reeciving process).
  63
  64 .sp
  65 The message buffer (msg) used to send is the same format as used for regular RMr
  66 send and reply to sender operations, thus any buffer allocated by these means, or
  67 calls to &ital(rmr_rcv_msg()) can be passed to this function.
  68
  69
  70 &h2(RETURN VALUE)
  71 On success, a new message buffer, with an empty payload, is returned for the application
  72 to use for the next send.
  73 The state in this buffer will reflect the overall send operation state and should be
  74 &cw(RMR_OK.)
  75
  76 &space
  77 If the state in the returned buffer is anything other than &cw(RMR_OK,) the user application
  78 may need to attempt a retransmission of the message, or take other action depending on the
  79 setting of &cw(errno) as described below.
  80
  81 &space
  82 In the event of extreme failure, a NULL pointer is returned. In this case the value of
  83 &cw(errno) might be of some use, for documentation, but there will be little that the
  84 user application can do other than to move on.
  85
  86 &h2(ERRORS)
  87 The following values may be passed back in the &ital(state) field of the returned message
  88 buffer.
  89
  90 &space
  91 &beg_dlist(.75i : ^&bold_font )
  92 &di(RMR_ERR_WHID) The wormhole ID passed in was not associated with an open wormhole, or was out of range for a valid ID.
  93 &di(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
  94 &di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
  95 &di(RMR_ERR_NOHDR)  The header in the message buffer was not valid or corrupted.
  96 &end_dlist
  97
  98 &space
  99 The following values may be assigned to &cw(errno) on failure.
 100 &beg_dlist(.75i : ^&bold_font )
 101 &di(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
 102
 103 &half_space
 104 &di(ENOKEY) The header information in the message buffer was invalid.
 105
 106 &half_space
 107 &di(ENXIO) No known endpoint for the message could be found.
 108
 109 &half_space
 110 &di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
 111
 112 &half_space
 113 &di(EFAULT) The message referenced by the message buffer is corrupt (NULL pointer or bad internal length).
 114
 115 &half_space
 116 &di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
 117
 118 &half_space
 119 &di(ENOTSUP) Sending was not supported by the underlying message transport.
 120
 121 &half_space
 122 &di(EFSM) The device is not in a state that can accept the message.
 123
 124 &half_space
 125 &di(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
 126
 127 &half_space
 128 &di(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
 129
 130 &half_space
 131 &di(ETIMEDOUT) The underlying message environment timed out during the send process.
 132
 133 &half_space
 134 &di(ETERM) The underlying message environment is in a shutdown state.
 135 &end_dlist
 136
 137 &h2(EXAMPLE)
 138 The following is a simple example of how the a wormhole is created (rmr_wh_open) and then
 139 how &cw(rmr_wh_send_msg) function is used to send messages.
 140 Some error checking is omitted for clarity.
 141
 142 &space
 143 &ex_start
 144
 145 #include <rmr/rmr.h>    // system headers omitted for clarity
 146
 147 int main() {
 148    rmr_whid_t whid = -1;   // wormhole id for sending
 149    void* mrc;      //msg router context
 150         int i;
 151    rmr_mbuf_t*  sbuf;      // send buffer
 152    int     count = 0;
 153
 154    mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
 155    if( mrc == NULL ) {
 156       fprintf( stderr, "[FAIL] unable to initialise RMr environment\n" );
 157       exit( 1 );
 158    }
 159
 160    while( ! rmr_ready( mrc ) ) {                // wait for routing table info
 161       sleep( 1 );
 162    }
 163
 164    sbuf = rmr_alloc_msg( mrc, 2048 );
 165
 166    while( 1 ) {
 167      if( whid < 0 ) {
 168        whid = rmr_wh_open( mrc, "localhost:6123" );  // open fails if endpoint refuses conn
 169            if( RMR_WH_CONNECTED( wh ) ) {
 170            snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
 171            sbuf->len =  strlen( sbuf->payload );
 172            sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
 173                 }
 174          }
 175
 176          sleep( 5 );
 177    }
 178 }
 179 &ex_end
 180
 181
 182 &h2(SEE ALSO )
 183 .ju off
 184 rmr_alloc_msg(3),
 185 rmr_call(3),
 186 rmr_free_msg(3),
 187 rmr_init(3),
 188 rmr_payload_size(3),
 189 rmr_rcv_msg(3),
 190 rmr_rcv_specific(3),
 191 rmr_rts_msg(3),
 192 rmr_ready(3),
 193 rmr_fib(3),
 194 rmr_has_str(3),
 195 rmr_tokenise(3),
 196 rmr_mk_ring(3),
 197 rmr_ring_free(3),
 198 rmr_wh_open(3),
 199 rmr_wh_close(3)
 200 .ju on
 201
 202
 203 .qu
 204