usr/src/man/man3dat/dat_ep_dup_connect.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DAT_EP_DUP_CONNECT 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ep_dup_connect \- establish a connection between the local Endpoint and a
  10 remote Endpoint
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <\fBdat/udat.h\fR>
  16
  17 DAT_RETURN
  18     dat_ep_dup_connect (
  19     IN    DAT_EP_HANDLE    ep_handle,
  20     IN    DAT_EP_HANDLE    dup_ep_handle,
  21     IN    DAT_TIMEOUT      timeout,
  22     IN    DAT_COUNT        private_data_size,
  23     IN const  DAT_PVOID    private_data,
  24     IN    DAT_QOS          qos
  25     )
  26 .fi
  27
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIep_handle\fR\fR
  33 .ad
  34 .RS 21n
  35 Handle for an instance of an Endpoint.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIdup_ep_handle\fR\fR
  42 .ad
  43 .RS 21n
  44 Connected local Endpoint that specifies a requested connection remote end.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fItimeout:\fR\fR
  51 .ad
  52 .RS 21n
  53 Duration of time, in microseconds, that Consumers wait for Connection
  54 establishment. The value of \fBDAT_TIMEOUT_INFINITE\fR represents no timeout,
  55 indefinite wait. Values must be positive.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIprivate_data_size\fR\fR
  62 .ad
  63 .RS 21n
  64 Size of \fIprivate_data\fR. Must be nonnegative.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIprivate_data\fR\fR
  71 .ad
  72 .RS 21n
  73 Pointer to the private data that should be provided to the remote Consumer as
  74 part of the Connection Request. If \fIprivate_data_size\fR is zero, then
  75 \fIprivate_data\fR can be \fINULL\fR.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIqos\fR\fR
  82 .ad
  83 .RS 21n
  84 Requested Quality of Service of the connection.
  85 .RE
  86
  87 .SH DESCRIPTION
  88 .sp
  89 .LP
  90 The \fBdat_ep_dup_connect()\fR function requests that a connection be
  91 established between the local Endpoint and a remote Endpoint. This operation is
  92 used by the active/client side Consumer of the connection model. The remote
  93 Endpoint is identified by the \fIdup_ep_handle\fR. The remote end of the
  94 requested connection shall be the same as the remote end of the
  95 \fIdup_ep_handle\fR. This is equivalent to requesting a connection to the same
  96 remote IA, Connection Qualifier, and \fIconnect_flags\fR as used for
  97 establishing the connection on duplicated Endpoints and following the same
  98 redirections.
  99 .sp
 100 .LP
 101 Upon establishing the requested connection as part of the successful completion
 102 of this operation, the local Endpoint is bound to a Port Qualifier of the local
 103 IA. The Port Qualifier is passed to the remote side of the requested connection
 104 and is available to the remote Consumer in the Connection Request of the
 105 \fBDAT_CONNECTION_REQUEST_EVENT\fR.
 106 .sp
 107 .LP
 108 The Consumer-provided \fIprivate_data\fR is passed to the remote side and is
 109 provided to the remote Consumer in the Connection Request. Consumers can
 110 encapsulate any local Endpoint attributes that remote Consumers need to know as
 111 part of an upper-level protocol. Providers can also provide a Provider on the
 112 remote side any local Endpoint attributes and Transport-specific information
 113 needed for Connection establishment by the Transport.
 114 .sp
 115 .LP
 116 Upon successful completion of this operation, the local Endpoint is transferred
 117 into \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR.
 118 .sp
 119 .LP
 120 Consumers can request a specific value of \fIqos\fR. The Provider specifies
 121 which Quality of Service it supports in documentation and in the Provider
 122 attributes. If the local Provider or Transport does not support the requested
 123 \fIqos\fR, the operation fails and \fBDAT_MODEL_NOT_SUPPORTED\fR is returned
 124 synchronously. If the remote Provider does not support the requested \fIqos\fR,
 125 the local Endpoint is automatically transitioned into a
 126 \fBDAT_EP_STATE_UNDISCONNECTED\fR state, the connection is not established, and
 127 the event returned on the \fIconnect_evd_handle\fR is
 128 \fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR. The same
 129 \fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR event is returned if connection
 130 cannot be established for all reasons for not establishing the connection,
 131 except timeout, remote host not reachable, and remote peer reject. For example,
 132 remote host is not reachable, remote Consumer is not listening on the requested
 133 Connection Qualifier, Backlog of the requested Service Point is full, and
 134 Transport errors. In this case, the local Endpoint is automatically
 135 transitioned into a \fBDAT_EP_STATE_UNDISCONNECTED\fR state.
 136 .sp
 137 .LP
 138 The acceptance of the requested connection by the remote Consumer is reported
 139 to the local Consumer through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on
 140 the \fIconnect_evd_handle\fR of the local Endpoint.
 141 .sp
 142 .LP
 143 The rejection of the connection by the remote Consumer is reported to the local
 144 Consumer through a \fBDAT_CONNECTION_EVENT_PEER_REJECTED\fR event on the
 145 \fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is
 146 automatically transitioned into a \fBDAT_EP_STATE_UNDISCONNECTED\fR state.
 147 .sp
 148 .LP
 149 When the Provider cannot reach the remote host or the remote host does not
 150 respond within the Consumer-requested \fItimeout\fR, a
 151 \fBDAT_CONNECTION_EVENT_UNREACHABLE\fR is generated on the
 152 \fIconnect_evd_handle\fR of the Endpoint. The Endpoint transitions into a
 153 \fBDAT_EP_STATE_DISCONNECTED\fR state.
 154 .sp
 155 .LP
 156 The local Endpoint is automatically transitioned into a
 157 \fBDAT_EP_STATE_CONNECTED\fR state when a Connection Request is accepted by the
 158 remote Consumer and the Provider completes the Transport-specific Connection
 159 establishment. The local Consumer is notified of the established connection
 160 through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on the
 161 \fIconnect_evd_handle\fR of the local Endpoint.
 162 .sp
 163 .LP
 164 When the \fItimeout\fR expired prior to completion of the Connection
 165 establishment, the local Endpoint is automatically transitioned into a
 166 \fBDAT_EP_STATE_UNDISCONNECTED\fR state and the local Consumer through a
 167 \fBDAT_CONNECTION_EVENT_TIMED_OUT\fR event on the \fIconnect_evd_handle\fR of
 168 the local Endpoint.
 169 .SH RETURN VALUES
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBDAT_SUCCESS\fR\fR
 174 .ad
 175 .RS 30n
 176 The operation was successful.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 183 .ad
 184 .RS 30n
 185 The operation failed due to resource limitations.
 186 .RE
 187
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 192 .ad
 193 .RS 30n
 194 Invalid parameter.
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBDAT_INVALID_HANDLE\fR\fR
 201 .ad
 202 .RS 30n
 203 The \fIep_handle\fR or \fIdup_ep_handle\fR parameter is invalid.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBDAT_INVALID_STATE\fR\fR
 210 .ad
 211 .RS 30n
 212 A parameter is in an invalid state.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
 219 .ad
 220 .RS 30n
 221 The requested Model is not supported by the Provider. For example, requested
 222 \fIqos\fR was not supported by the local Provider.
 223 .RE
 224
 225 .SH USAGE
 226 .sp
 227 .LP
 228 It is up to the Consumer to negotiate outstanding RDMA Read incoming and
 229 outgoing with a remote peer. The outstanding RDMA Read outgoing attribute
 230 should be smaller than the remote Endpoint outstanding RDMA Read incoming
 231 attribute. If this is not the case, connection establishment might fail.
 232 .sp
 233 .LP
 234 DAT API does not define a protocol on how remote peers exchange Endpoint
 235 attributes. The exchange of outstanding RDMA Read incoming and outgoing
 236 attributes of EPs is left to the Consumer ULP. The Consumer can use Private
 237 Data for it.
 238 .sp
 239 .LP
 240 If the Consumer does not care about posting RDMA Read operations or remote RDMA
 241 Read operations on the connection, it can set the two outstanding RDMA Read
 242 attribute values to 0.
 243 .sp
 244 .LP
 245 If the Consumer does not set the two outstanding RDMA Read attributes of the
 246 Endpoint, the Provider is free to pick up any values as a default. The Provider
 247 is allowed to change these default values during connection setup.
 248 .SH ATTRIBUTES
 249 .sp
 250 .LP
 251 See \fBattributes\fR(5) for descriptions of the following attributes:
 252 .sp
 253
 254 .sp
 255 .TS
 256 box;
 257 c | c
 258 l | l .
 259 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 260 _
 261 Interface Stability     Standard: uDAPL, 1.1, 1.2
 262 _
 263 MT-Level        Unsafe
 264 .TE
 265
 266 .SH SEE ALSO
 267 .sp
 268 .LP
 269 \fBlibdat\fR(3LIB), \fBattributes\fR(5)