path: root/usr/src/man/man3dat/dat_ep_connect.3dat

'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH DAT_EP_CONNECT 3DAT "Jul 16, 2004"
.SH NAME
dat_ep_connect \- establish a connection between the local Endpoint and a
remote Endpoint
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ep_connect (
    IN    DAT_EP_HANDLE         ep_handle,
    IN    DAT_IA_ADDRESS_PTR    remote_ia_address,
    IN    DAT_CONN_QUAL         remote_conn_qual,
    IN    DAT_TIMEOUT           timeout,
    IN    DAT_COUNT             private_data_size,
    IN const  DAT_PVOID         private_data,
    IN    DAT_QOS               qos,
    IN    DAT_CONNECT_FLAGS     connect_flags
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIep_handle\fR\fR
.ad
.RS 21n
Handle for an instance of an Endpoint.
.RE

.sp
.ne 2
.na
\fB\fIremote_ia_address\fR\fR
.ad
.RS 21n
The Address of the remote IA to which an Endpoint is requesting a connection.
.RE

.sp
.ne 2
.na
\fB\fIremote_conn_qual\fR\fR
.ad
.RS 21n
Connection Qualifier of the remote IA from which an Endpoint requests a
connection.
.RE

.sp
.ne 2
.na
\fB\fItimeout\fR\fR
.ad
.RS 21n
Duration of time, in microseconds, that a Consumer waits for Connection
establishment. The value of \fBDAT_TIMEOUT_INFINITE\fR represents no timeout,
indefinite wait. Values must be positive.
.RE

.sp
.ne 2
.na
\fB\fIprivate_data_size\fR\fR
.ad
.RS 21n
Size of the \fIprivate_data\fR. Must be nonnegative.
.RE

.sp
.ne 2
.na
\fB\fIprivate_data\fR\fR
.ad
.RS 21n
Pointer to the private data that should be provided to the remote Consumer as
part of the Connection Request. If \fIprivate_data_size\fR is zero, then
\fIprivate_data\fR can be \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fIqos\fR\fR
.ad
.RS 21n
Requested quality of service of the connection.
.RE

.sp
.ne 2
.na
\fB\fIconnect_flags\fR\fR
.ad
.RS 21n
Flags for the requested connection. If the least significant bit of
\fBDAT_MULTIPATH_FLAG\fR is 0, the Consumer does not request multipathing. If
the least significant bit of \fBDAT__MULTIPATH_FLAG\fR is 1, the Consumer
requests multipathing. The default value is \fBDAT_CONNECT_DEFAULT_FLAG\fR,
which is 0.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ep_connect()\fR function requests that a connection be established
between the local Endpoint and a remote Endpoint. This operation is used by the
active/client side Consumer of the Connection establishment model. The remote
Endpoint is identified by Remote IA and Remote Connection Qualifier.
.sp
.LP
As part of the successful completion of this operation, the local Endpoint is
bound to a Port Qualifier of the local IA. The Port Qualifier is passed to the
remote side of the requested connection and is available to the remote Consumer
in the Connection Request of the \fBDAT_CONNECTION_REQUEST_EVENT\fR.
.sp
.LP
The Consumer-provided \fIprivate_data\fR is passed to the remote side and is
provided to the remote Consumer in the Connection Request. Consumers can
encapsulate any local Endpoint attributes that remote Consumers need to know as
part of an upper-level protocol. Providers can also provide a Provider on the
remote side any local Endpoint attributes and Transport-specific information
needed for Connection establishment by the Transport.
.sp
.LP
Upon successful completion of this operation, the local Endpoint is transferred
into \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR.
.sp
.LP
Consumers can request a specific value of \fIqos\fR. The Provider specifies
which quality of service it supports in documentation and in the Provider
attributes. If the local Provider or Transport does not support the requested
\fIqos\fR, the operation fails and \fBDAT_MODEL_NOT_SUPPORTED\fR is returned
synchronously. If the remote Provider does not support the requested \fIqos\fR,
the local Endpoint is automatically transitioned into the
\fBDAT_EP_STATE_DISCONNECTED\fR state, the connection is not established, and
the event returned on the \fIconnect_evd_handle\fR is
\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR. The same
\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR event is returned if the
connection cannot be established for all reasons of not establishing the
connection, except timeout, remote host not reachable, and remote peer reject.
For example, remote Consumer is not listening on the requested Connection
Qualifier, Backlog of the requested Service Point is full, and Transport
errors. In this case, the local Endpoint is automatically transitioned into
\fBDAT_EP_STATE_DISCONNECTED\fR state.
.sp
.LP
The acceptance of the requested connection by the remote Consumer is reported
to the local Consumer through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on
the \fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is
automatically transitioned into a \fBDAT_EP_STATE_CONNECTED\fR state.
.sp
.LP
The rejection of the connection by the remote Consumer is reported to the local
Consumer through a \fBDAT_CONNECTION_EVENT_PEER_REJECTED\fR event on the
\fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is
automatically transitioned into a \fBDAT_EP_STATE_DISCONNECTED\fR state.
.sp
.LP
When the Provider cannot reach the remote host or the remote host does not
respond within the Consumer requested Timeout, a
\fBDAT_CONNECTION_EVENT_UNREACHABLE\fR event is generated on the
\fIconnect_evd_handle\fR of the Endpoint. The Endpoint transitions into a
\fBDAT_EP_STATE_DISCONNECTED\fR state.
.sp
.LP
If the Provider can locally determine that the \fIremote_ia_address\fR is
invalid, or that the remote_ia_address cannot be converted to a
Transport-specific address, the operation can fail synchronously with a
\fBDAT_INVALID_ADDRESS\fR return.
.sp
.LP
The local Endpoint is automatically transitioned into a
\fBDAT_EP_STATE_CONNECTED\fR state when a Connection Request accepted by the
remote Consumer and the Provider completes the Transport-specific Connection
establishment. The local Consumer is notified of the established connection
through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on the
\fIconnect_evd_handle\fR of the local Endpoint.
.sp
.LP
When the \fItimeout\fR expired prior to completion of the Connection
establishment, the local Endpoint is automatically transitioned into a
\fBDAT_EP_STATE_DISCONNECTED\fR state and the local Consumer through a
\fBDAT_CONNECTION_EVENT_TIMED_OUT\fR event on the \fIconnect_evd_handle\fR of
the local Endpoint.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
.ad
.RS 30n
The operation failed due to resource limitations.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
Invalid parameter.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_ADDRESS\fR\fR
.ad
.RS 30n
Invalid address.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
Invalid DAT handle; Invalid Endpoint handle.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_STATE\fR\fR
.ad
.RS 30n
Parameter in an invalid state. Endpoint was not in
\fBDAT_EP_STATE_UNCONNECTED\fR state.
.RE

.sp
.ne 2
.na
\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
.ad
.RS 30n
The requested Model was not supported by the Provider. For example, the
requested qos was not supported by the local Provider.
.RE

.SH USAGE
.sp
.LP
It is up to the Consumer to negotiate outstanding RDMA Read incoming and
outgoing with a remote peer. The outstanding RDMA Read outgoing attribute
should be smaller than the remote Endpoint outstanding RDMA Read incoming
attribute. If this is not the case, Connection establishment might fail.
.sp
.LP
DAT API does not define a protocol on how remote peers exchange Endpoint
attributes. The exchange of outstanding RDMA Read incoming and outgoing
attributes of EPs is left to the Consumer ULP. The Consumer can use Private
Data for it.
.sp
.LP
If the Consumer does not care about posting RDMA Read operations or remote RDMA
Read operations on the connection, it can set the two outstanding RDMA Read
attribute values to 0.
.sp
.LP
If the Consumer does not set the two outstanding RDMA Read attributes of the
Endpoint, the Provider is free to pick up any value for default. The Provider
is allowed to change these default values during connection setup.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.1, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibdat\fR(3LIB), \fBattributes\fR(5)