.if false
==================================================================================
   Copyright (c) 2020 Nokia
   Copyright (c) 2020 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_call_3.xfm
    Abstract    The manual page for the rmr_wh_call function.
    Author      E. Scott Daniels
    Date        28 January 2019
.fi

.gv e LIB lib
.im &{lib}/man/setup.im

&line_len(6i)

&h1(RMR Library Functions)
&h2(NAME)
    rmr_wh_call

&h2(SYNOPSIS )
&indent
&ex_start
#include <rmr/rmr.h>

rmr_mbuf_t* rmr_wh_call( void* vctx, rmr_whid_t whid, rmr_mbuf_t* msg, int call_id, int max_wait )

&ex_end
&uindent

&h2(DESCRIPTION)
The &cw(rmr_wh_call) function accepts a message buffer (msg) from the user application
and attempts to send it using the wormhole ID provided (whid).
If the send is successful, the call will block until either a response message is
received, or the &cw(max_wait) number of milliseconds has passed.
In order for the response to be recognised as a response, the remote process &bold(must)
use &cw(rmr_rts_msg()) to send their response.

&space
Like &ital(rmr_wh_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 receiving process).

The &cw(call_id) parameter is a number in the range of 2 through 255 and is used to
identify the calling thread in order to properly match a response message when it
arrives.
Providing this value, and ensuring the proper uniqueness,  is the responsibility of the
user application and as such the ability to use the &cw(rmr_wh_call()) function from
potentially non-threaded concurrent applications (such as Go's goroutines) is possible.

.** pull in common retry text
.im &{lib}/man/retry.im

&h2(RETURN VALUE)
On success, new message buffer, with the payload containing the response from the remote
endpoint is returned.
The state in this buffer will reflect the overall send operation state and should be
&cw(RMR_OK.)

&space
If a message is returned with a state which is anything other than &cw(RMR_OK,) the indication
is that the send was not successful.
The user application must check the state and determine the course of action.
If the return value is NULL, no message, the indication is that there was no response
received within the timeout (max_wait) period of time.

&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

&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;
   int     norm_msg_size = 1500;    // most messages fit in this size

   mrc = rmr_init( "43086", norm_msg_size, 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_call( mrc, whid, sbuf, 1000 );        // expect a response in 1s or less
           if( sbuf != NULL && sbuf->state = RMR_OK ) {
             sprintf( stderr, "response: %s\n", sbuf->payload );    // assume they sent a string
           } else {
             sprintf( stderr, "response not received, or send error\n" );
           }
        }
      }

      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_set_stimeout(3),
rmr_wh_open(3),
rmr_wh_close(3),
rmr_wh_state(3)
.ju on