2 ==================================================================================
3 Copyright (c) 2019 Nokia
4 Copyright (c) 2018-2019 AT&T Intellectual Property.
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
10 http://www.apache.org/licenses/LICENSE-2.0
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 ==================================================================================
21 Mnemonic rmr_wh_open.xfm
22 Abstract The manual page for the rmr_wh_open function.
23 Author E. Scott Daniels
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
31 .im &{lib}/generic_ps.im
33 .gv e OUTPUT_RST use_rst
43 &h1(RMR Library Functions)
52 void* rmr_open( void* vctx, char* target )
58 The &cw(rmr_wh_open) function creates a direct link for sending, a wormhole, to another
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.
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.
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.
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.
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.
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.
102 rmc = rmr_init( "43086", 4096, 0 ); // init context
103 wh = rmr_open( rmc, "localhost:6123" );
104 if( !RMR_WH_CONNECTED( wh ) ) {
105 fprintf( stderr, "unable to connect wormhole: %s\n",