doc/src/man/rmr_wh_open.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
  20 .if false
  21         Mnemonic        rmr_wh_open.xfm
  22         Abstract        The manual page for the rmr_wh_open function.
  23         Author          E. Scott Daniels
  24         Date            20 February 2019
  25 .fi
  26
  27 .gv e LIB lib
  28 .im &{lib}/man/setup.im
  29
  30 &line_len(6i)
  31
  32 &h1(RMR Library Functions)
  33 &h2(NAME)
  34         rmr_wh_open
  35
  36 &h2(SYNOPSIS)
  37 &indent
  38 &ex_start
  39 #include <rmr/rmr.h>
  40
  41 void* rmr_wh_open( void* vctx, char* target )
  42 &ex_end
  43
  44 &uindent
  45
  46 &h2(DESCRIPTION)
  47 The &cw(rmr_wh_open) function creates a direct link for sending, a wormhole, to another
  48 RMr based process.
  49 Sending messages through a wormhole requires that the connection be established overtly
  50 by the user application (via this function), and that the ID returned by &cw(rmr_wh_open)
  51 be passed to the &cw(rmr_wh_send_msg) function.
  52
  53 &space
  54 &ital(Target) is the &ital(name:port,) or &ital(IP-address:port,) combination of the
  55 processess that the wormhole should be connected to.
  56 &ital(Vctx) is the RMr void context pointer that was returned by the &cw(rmr_init) function.
  57
  58 &space
  59 When invoked, this function immediatly attempts to connect to the target process.
  60 If the connection cannot be established, an error is returned to the caller, and no
  61 direct messages can be sent to the target.
  62 Once a wormhole is connected, the underlying transport mechanism (e.g. NNG) will provide
  63 reconnects should the connection be lost, however the handling of messages sent when
  64 a connection is broken is undetermined as each underlying transport mechanism may handle
  65 buffering and retries differently.
  66
  67
  68 &h2(RETURN VALUE)
  69 The &cw(rmr_wh_open) function returns a type &cw(rmr_whid_t) which must be passed to
  70 the &cw(rmr_wh_send_msg) function when sending a message.
  71 The id may also be tested to determine success or failure of the connection by
  72 using the RMR_WH_CONNECTED macro and passing the ID as the parameter; a result of
  73 1 indicates that the connection was esablished and that the ID is valid.
  74
  75 &h2(ERRORS)
  76 The following error values are specifically set by this RMR function. In some cases the
  77 error message of a system call is propagated up, and thus this list might be incomplete.
  78
  79 &beg_dlist(.75i : ^&bold_font )
  80 &di(EINVAL) A parameter passed was not valid.
  81 &di(EACCESS) The user applicarion does not have the ability to establish a wormhole to the
  82                 indicated target (or maybe any target).
  83 &di(ECONNREFUSED) The connection was refused.
  84 &end_dlist
  85
  86 &h2(EXAMPLE)
  87 &ex_start
  88    void*  rmc;
  89    rmr_whid_t wh;
  90
  91    rmc = rmr_init( "43086", 4096, 0 ); // init context
  92    wh = rmr_wh_open( rmc, "localhost:6123" );
  93    if( !RMR_WH_CONNECTED( wh ) ) {
  94          fprintf( stderr, "unable to connect wormhole: %s\n",
  95              strerror( errno ) );
  96    }
  97 &ex_end
  98
  99 &h2(SEE ALSO )
 100 .ju off
 101 rmr_alloc_msg(3),
 102 rmr_call(3),
 103 rmr_free_msg(3),
 104 rmr_get_rcvfd(3),
 105 rmr_payload_size(3),
 106 rmr_send_msg(3),
 107 rmr_rcv_msg(3),
 108 rmr_rcv_specific(3),
 109 rmr_rts_msg(3),
 110 rmr_ready(3),
 111 rmr_fib(3),
 112 rmr_has_str(3),
 113 rmr_tokenise(3),
 114 rmr_mk_ring(3),
 115 rmr_ring_free(3),
 116 rmr_wh_send_msg(3),
 117 rmr_wh_close(3)
 118 .ju on