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
28 .im &{lib}/man/setup.im
32 &h1(RMR Library Functions)
41 void* rmr_wh_open( void* vctx, char* target )
47 The &cw(rmr_wh_open) function creates a direct link for sending, a wormhole, to another
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.
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.
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.
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.
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.
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.
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",