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