--- /dev/null
+.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 rmr_wh_send_msg_man.xfm
+ Abstract The manual page for the rmr_wh_send_msg function.
+ Author E. Scott Daniels
+ Date 28 January 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+ .im &{lib}/generic_ps.im
+.ei
+ .gv e OUTPUT_RST use_rst
+ .if .ev &use_rst 1 =
+ .im &{lib}/rst.im
+ .ei
+ .im &{lib}/roff.im
+ .fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+ rmr_wh_send_msg
+
+&h2(SYNOPSIS )
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+rmr_mbuf_t* rmr_wh_send_msg( void* vctx, rmr_whid_t id, rmr_mbuf_t* msg );
+&ex_end
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_wh_send_msg) function accepts a message buffer from the user application
+and attempts to send it using the wormhole ID provided (id).
+Unlike &ital(rmr_send_msg,) this function attempts to send the message directly
+to a process at the other end of a wormhole which was created with &ital(rmr_wh-open().)
+When sending message via wormholes, the normal RMr routing based on message type is
+ignored, and the caller may leave the message type unspecified in the message buffer
+(unless it is needed by the reeciving process).
+
+.sp
+The message buffer (msg) used to send is the same format as used for regular RMr
+send and reply to sender operations, thus any buffer allocated by these means, or
+calls to &ital(rmr_rcv_msg()) can be passed to this function.
+
+
+&h2(RETURN VALUE)
+On success, a new message buffer, with an empty payload, is returned for the application
+to use for the next send.
+The state in this buffer will reflect the overall send operation state and should be
+&cw(RMR_OK.)
+
+&space
+If the state in the returned buffer is anything other than &cw(RMR_OK,) the user application
+may need to attempt a retransmission of the message, or take other action depending on the
+setting of &cw(errno) as described below.
+
+&space
+In the event of extreme failure, a NULL pointer is returned. In this case the value of
+&cw(errno) might be of some use, for documentation, but there will be little that the
+user application can do other than to move on.
+
+&h2(ERRORS)
+The following values may be passed back in the &ital(state) field of the returned message
+buffer.
+
+&space
+&beg_dlist(.75i : ^&bold_font )
+&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.
+&di(RMR_ERR_NOWHOPEN) No wormholes exist, further attempt to validate the ID are skipped.
+&di(RMR_ERR_BADARG) The message buffer pointer did not refer to a valid message.
+&di(RMR_ERR_NOHDR) The header in the message buffer was not valid or corrupted.
+&end_dlist
+
+&space
+The following values may be assigned to &cw(errno) on failure.
+&beg_dlist(.75i : ^&bold_font )
+&di(INVAL) Parameter(s) passed to the function were not valid, or the underlying message processing environment was unable to interpret the message.
+
+&half_space
+&di(ENOKEY) The header information in the message buffer was invalid.
+
+&half_space
+&di(ENXIO) No known endpoint for the message could be found.
+
+&half_space
+&di(EMSGSIZE) The underlying transport refused to accept the message because of a size value issue (message was not attempted to be sent).
+
+&half_space
+&di(EFAULT) The message referenced by the message buffer is corrupt (NULL pointer or bad internal length).
+
+&half_space
+&di(EBADF) Internal RMR error; information provided to the message transport environment was not valid.
+
+&half_space
+&di(ENOTSUP) Sending was not supported by the underlying message transport.
+
+&half_space
+&di(EFSM) The device is not in a state that can accept the message.
+
+&half_space
+&di(EAGAIN) The device is not able to accept a message for sending. The user application should attempt to resend.
+
+&half_space
+&di(EINTR) The operation was interrupted by delivery of a signal before the message was sent.
+
+&half_space
+&di(ETIMEDOUT) The underlying message environment timed out during the send process.
+
+&half_space
+&di(ETERM) The underlying message environment is in a shutdown state.
+&end_dlist
+
+&h2(EXAMPLE)
+The following is a simple example of how the a wormhole is created (rmr_wh_open) and then
+how &cw(rmr_wh_send_msg) function is used to send messages.
+Some error checking is omitted for clarity.
+
+&space
+&ex_start
+
+#include <rmr/rmr.h> // system headers omitted for clarity
+
+int main() {
+ rmr_whid_t whid = -1; // wormhole id for sending
+ void* mrc; //msg router context
+ int i;
+ rmr_mbuf_t* sbuf; // send buffer
+ int count = 0;
+
+ mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
+ if( mrc == NULL ) {
+ fprintf( stderr, "[FAIL] unable to initialise RMr environment\n" );
+ exit( 1 );
+ }
+
+ while( ! rmr_ready( mrc ) ) { // wait for routing table info
+ sleep( 1 );
+ }
+
+ sbuf = rmr_alloc_msg( mrc, 2048 );
+
+ while( 1 ) {
+ if( whid < 0 ) {
+ whid = rmr_wh_open( mrc, "localhost:6123" ); // open fails if endpoint refuses conn
+ if( RMR_WH_CONNECTED( wh ) ) {
+ snprintf( sbuf->payload, 1024, "periodic update from sender: %d", count++ );
+ sbuf->len = strlen( sbuf->payload );
+ sbuf = rmr_wh_send_msg( mrc, whid, sbuf );
+ }
+ }
+
+ sleep( 5 );
+ }
+}
+&ex_end
+
+
+&h2(SEE ALSO )
+.ju off
+rmr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_init(3),
+rmr_payload_size(3),
+rmr_rcv_msg(3),
+rmr_rcv_specific(3),
+rmr_rts_msg(3),
+rmr_ready(3),
+rmr_fib(3),
+rmr_has_str(3),
+rmr_tokenise(3),
+rmr_mk_ring(3),
+rmr_ring_free(3),
+rmr_wh_open(3),
+rmr_wh_close(3)
+.ju on
+
+
+.qu
+
Code Review / ric-plt / lib / rmr.git / blobdiff