docs/rmr_wh_open.3.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_wh_open
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_wh_open
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  void* rmr_wh_open( void* vctx, char* target )
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  37 The rmr_wh_open function creates a direct link for sending, a
  38 wormhole, to another RMR based process. Sending messages
  39 through a wormhole requires that the connection be
  40 established overtly by the user application (via this
  41 function), and that the ID returned by rmr_wh_open be passed
  42 to the rmr_wh_send_msg function.
  43
  44 *Target* is the *name* or *IP-address* combination of the
  45 processess that the wormhole should be connected to. *Vctx*
  46 is the RMR void context pointer that was returned by the
  47 rmr_init function.
  48
  49 When invoked, this function immediatly attempts to connect to
  50 the target process. If the connection cannot be established,
  51 an error is returned to the caller, and no direct messages
  52 can be sent to the target. Once a wormhole is connected, the
  53 underlying transport mechanism (e.g. NNG) will provide
  54 reconnects should the connection be lost, however the
  55 handling of messages sent when a connection is broken is
  56 undetermined as each underlying transport mechanism may
  57 handle buffering and retries differently.
  58
  59 RETURN VALUE
  60 --------------------------------------------------------------------------------------------
  61
  62 The rmr_wh_open function returns a type rmr_whid_t which must
  63 be passed to the rmr_wh_send_msg function when sending a
  64 message. The id may also be tested to determine success or
  65 failure of the connection by using the RMR_WH_CONNECTED macro
  66 and passing the ID as the parameter; a result of 1 indicates
  67 that the connection was esablished and that the ID is valid.
  68
  69 ERRORS
  70 --------------------------------------------------------------------------------------------
  71
  72 The following error values are specifically set by this RMR
  73 function. In some cases the error message of a system call is
  74 propagated up, and thus this list might be incomplete.
  75
  76
  77 EINVAL
  78
  79   A parameter passed was not valid.
  80
  81 EACCESS
  82
  83   The user application does not have the ability to
  84   establish a wormhole to the indicated target (or maybe any
  85   target).
  86
  87 ECONNREFUSED
  88
  89   The connection was refused.
  90
  91
  92 EXAMPLE
  93 --------------------------------------------------------------------------------------------
  94
  95
  96 ::
  97
  98     void*  rmc;
  99     rmr_whid_t wh;
 100     rmc = rmr_init( "43086", 4096, 0 ); // init context
 101     wh = rmr_wh_open( rmc, "localhost:6123" );
 102     if( !RMR_WH_CONNECTED( wh ) ) {
 103       fprintf( stderr, "unable to connect wormhole: %s\\n",
 104               strerror( errno ) );
 105     }
 106
 107
 108
 109 SEE ALSO
 110 --------------------------------------------------------------------------------------------
 111
 112 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 113 rmr_get_rcvfd(3), rmr_payload_size(3), rmr_send_msg(3),
 114 rmr_rcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
 115 rmr_ready(3), rmr_fib(3), rmr_has_str(3), rmr_tokenise(3),
 116 rmr_mk_ring(3), rmr_ring_free(3), rmr_wh_close(3),
 117 rmr_wh_send_msg(3), rmr_wh_state(3)