'\" 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_CR_ACCEPT 3DAT "Jul 16, 2004"
.SH NAME
dat_cr_accept \- establishes a Connection between the active remote side
requesting Endpoint and the passive side local Endpoint
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_cr_accept (
    IN    DAT_CR_HANDLE    cr_handle,
    IN    DAT_EP_HANDLE    ep_handle,
    IN    DAT_COUNT        private_data_size,
    IN const DAT_PVOID     private_data
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIcr_handle\fR\fR
.ad
.RS 21n
Handle to an instance of a Connection Request that the Consumer is accepting.
.RE

.sp
.ne 2
.na
\fB\fIep_handle\fR\fR
.ad
.RS 21n
Handle for an instance of a local Endpoint that the Consumer is accepting the
Connection Request on. If the local Endpoint is specified by the Connection
Request, the \fIep_handle\fR shall be \fBDAT_HANDLE_NULL\fR.
.RE

.sp
.ne 2
.na
\fB\fIprivate_data_size\fR\fR
.ad
.RS 21n
Size of the \fIprivate_data\fR, which 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 when
the Connection is established. If \fIprivate_data_size\fR is zero, then
\fIprivate_data\fR can be \fINULL\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_cr_accept()\fR function establishes a Connection between the active
remote side requesting Endpoint and the passive side local Endpoint. The local
Endpoint is either specified explicitly by \fIep_handle\fR or implicitly by a
Connection Request. In the second case, \fIep_handle\fR is
\fBDAT_HANDLE_NULL\fR.
.sp
.LP
Consumers can specify private data that is provided to the remote side upon
Connection establishment.
.sp
.LP
If the provided local Endpoint does not satisfy the requested Connection
Request, the operation fails without any effect on the local Endpoint, Pending
Connection Request, private data, or remote Endpoint.
.sp
.LP
The operation is asynchronous. The successful completion of the operation is
reported through a Connection Event of type
\fBDAT_CONNECTION_EVENT_ESTABLISHED\fR on the \fIconnect_evd\fR of the local
Endpoint.
.sp
.LP
If the Provider cannot complete the Connection establishment, the connection is
not established and the Consumer is notified through a Connection Event of type
\fBDAT_CONNECTION_EVENT_ACCEPT_COMPLETION_ERROR\fR on the \fIconnect_evd\fR of
the local Endpoint. It can be caused by the active side timeout expiration,
transport error, or any other reason. If Connection is not established,
Endpoint transitions into Disconnected state and all posted Recv DTOs are
flushed to its \fIrecv_evd_handle\fR.
.sp
.LP
This operation, if successful, also destroys the Connection Request instance.
Use of the handle of the destroyed \fIcr_handle\fR in any consequent operation
fails.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 25n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 25n
The \fIcr_handle\fR or \fIep_handle\fR parameter is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 25n
The \fIprivate_data_size\fR or \fIprivate_data\fR parameter is invalid, out of
range, or a combination of parameters was invalid
.RE

.SH USAGE
.sp
.LP
Consumers should be aware that Connection establishment might fail in the
following cases: If the accepting Endpoint has an outstanding RDMA Read
outgoing attribute larger than the requesting remote Endpoint or outstanding
RDMA Read incoming attribute, or if the outstanding RDMA Read incoming
attribute is smaller than the requesting remote Endpoint or outstanding RDMA
Read outgoing attribute.
.sp
.LP
Consumers should set the accepting Endpoint RDMA Reads as the target (incoming)
to a number larger than or equal to the remote Endpoint RDMA Read outstanding
as the originator (outgoing), and the accepting Endpoint RDMA Reads as the
originator to a number smaller than or equal to the remote Endpoint RDMA Read
outstanding as the target. 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. 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
can 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)