path: root/usr/src/man/man3dat/dat_psp_create.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_psp_create 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions"
.SH NAME
dat_psp_create \- create a persistent Public Service Point
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_psp_create(
    IN    DAT_IA_HANDLE    \fIia_handle\fR,
    IN    DAT_CONN_QUAL    \fIconn_qual\fR,
    IN    DAT_EVD_HANDLE   \fIevd_handle\fR,
    IN    DAT_PSP_FLAGS    \fIpsp_flags\fR,
    OUT   DAT_PSP_HANDLE   *\fIpsp_handle\fR
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIia_handle\fR\fR
.ad
.RS 14n
.rt  
Handle for an instance of DAT IA.
.RE

.sp
.ne 2
.mk
.na
\fB\fIconn_qual\fR\fR
.ad
.RS 14n
.rt  
Connection Qualifier of the IA on which the Public Service Point is listening.
.RE

.sp
.ne 2
.mk
.na
\fB\fIevd_handle\fR\fR
.ad
.RS 14n
.rt  
Event Dispatcher that provides the Connection Requested Events to the Consumer.
The size of the event queue for the Event Dispatcher controls the size of the
backlog for the created Public Service Point.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpsp_flags\fR\fR
.ad
.RS 14n
.rt  
Flag that indicates whether the Provider or Consumer creates an Endpoint per
arrived Connection Request. The value of \fBDAT_PSP_PROVIDER\fR indicates that
the Consumer wants to get an Endpoint from the Provider; a value of
\fBDAT_PSP_CONSUMER\fR means the Consumer does not want the Provider to provide
an Endpoint for each arrived Connection Request.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpsp_handle\fR\fR
.ad
.RS 14n
.rt  
Handle to an opaque Public Service Point.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_psp_create()\fR function creates a persistent Public Service Point
that can receive multiple requests for connection and generate multiple
Connection Request instances that are delivered through the specified Event
Dispatcher in Notification events.
.sp
.LP
The \fBdat_psp_create()\fR function is blocking. When the Public Service Point
is created, \fBDAT_SUCCESS\fR is returned and \fIpsp_handle\fR contains a
handle to an opaque Public Service Point Object.
.sp
.LP
There is no explicit backlog for a Public Service Point. Instead, Consumers can
control the size of backlog through the queue size of the associated Event
Dispatcher.
.sp
.LP
The \fIpsp_flags\fR parameter allows Consumers to request that the Provider
create an implicit Endpoint for each incoming Connection Request, or request
that the Provider should not create one per Connection Request. If the Provider
cannot satisfy the request, the operation shall fail and
\fBDAT_MODEL_NOT_SUPPORTED\fR is returned.
.sp
.LP
All Endpoints created by the Provider have \fBDAT_HANDLE_NULL\fR  for the
Protection Zone and all Event Dispatchers. The Provider sets up Endpoint
attributes to match the Active side connection request. The Consumer can change
Endpoint parameters. Consumers should change Endpoint parameters, especially PZ
and EVD, and are advised to change parameters for local accesses prior to the
connection request acceptance with the Endpoint.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
.rt  
The operation was successful.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
.rt  
The \fIia_handle\fR or \fIevd_handle\fR parameter is invalid.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
.rt  
The \fIconn_qual\fR or \fIpsp_flags\fR parameter is invalid.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDAT_CONN_QUAL_IN_USE\fR\fR
.ad
.RS 30n
.rt  
The specified Connection Qualifier was in use.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
.ad
.RS 30n
.rt  
The requested Model was not supported by the Provider.
.RE

.SH USAGE
.sp
.LP
Two uses of a Public Service Point are as follows:
.sp
.ne 2
.mk
.na
\fBModel 1\fR
.ad
.RS 11n
.rt  
For this model, the Provider manipulates a pool of Endpoints for a Public
Service Point. The Provider can use the same pool for more than one Public
Service Point.
.RS +4
.TP
.ie t \(bu
.el o
The DAT Consumer creates a Public Service Point with a \fIflag\fR set to
\fBDAT_PSP_PROVIDER\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The Public Service Point does the following:
.RS +4
.TP
.ie t \(bu
.el o
Collects native transport information reflecting a received Connection Reques
.RE
.RS +4
.TP
.ie t \(bu
.el o
Creates an instance of Connection Reques
.RE
.RS +4
.TP
.ie t \(bu
.el o
Creates a Connection Request Notice (event) that includes the Connection
Request instance (thatwhich includes, among others, Public Service Point, its
Connection Qualifier, Provider-generated Local Endpoint, and information about
remote Endpoint)
.RE
.RS +4
.TP
.ie t \(bu
.el o
Delivers the Connection Request Notice to the Consumer-specified target (CNO)
\fIevd_handle\fR
.sp
The Public Service Point is persistent and continues to listen for incoming
requests for connection.
.RE
.RE
.RS +4
.TP
.ie t \(bu
.el o
Upon receiving a connection request, or at some time subsequent to that, the
DAT Consumer can modify the provided local Endpoint to match the Connection
Request and must either \fBaccept()\fR or \fBreject()\fR the pending Connection
Request.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If accepted, the provided Local Endpoint is now in a "connected" state and is
fully usable for this connection, pending only any native transport mandated
RTU (ready-to-use) messages. This includes binding it to the IA port if that
was not done previously. The Consumer is notified that the Endpoint is in
Connected state by a Connection Established Event on the Endpoint
\fIconnect_evd_handle\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If rejected, control of the Local Endpoint point is returned back to the
Provider and its \fIep_handle\fR is no longer usable by the Consumer.
.RE
.RE

.sp
.ne 2
.mk
.na
\fBModel 2\fR
.ad
.RS 11n
.rt  
For this model, the Consumer manipulates a pool of Endpoints. Consumers can use
the same pool for more than one Service Point.
.RS +4
.TP
.ie t \(bu
.el o
DAT Consumer creates a Public Service Point with a \fIflag\fR set to
\fBDAT_PSP_CONSUMER\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Public Service Point:
.RS +4
.TP
.ie t \(bu
.el o
Collects native transport information reflecting a received Connection Request
.RE
.RS +4
.TP
.ie t \(bu
.el o
Creates an instance of Connection Request
.RE
.RS +4
.TP
.ie t \(bu
.el o
Creates a Connection Request Notice (event) that includes the Connection
Request instance (which includes, among others, Public Service Point, its
Connection Qualifier, Provider-generated Local Endpoint and information about
remote Endpoint)
.RE
.RS +4
.TP
.ie t \(bu
.el o
Delivers the Connection Request Notice to the Consumer-specified target (CNO)
\fIevd_handle\fR
.sp
The Public Service Point is persistent and continues to listen for incoming
requests for connection.
.RE
.RE
.RS +4
.TP
.ie t \(bu
.el o
The Consumer creates a pool of Endpoints that it uses for accepting Connection
Requests. Endpoints can be created and modified at any time prior to accepting
a Connection Request with that Endpoint.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Upon receiving a connection request or at some time subsequent to that, the DAT
Consumer can modify its local Endpoint to match the Connection Request and must
either \fBaccept()\fR or \fBreject()\fR the pending Connection Request.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If accepted, the provided Local Endpoint is now in a "connected" state and is
fully usable for this connection, pending only any native transport mandated
RTU messages. This includes binding it to the IA port if that was not done
previously. The Consumer is notified that the Endpoint is in Connected state by
a Connection Established Event on the Endpoint \fIconnect_evd_handle\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If rejected, the Consumer does not have to provide any Endpoint for
\fBdat_cr_reject\fR(3DAT).
.RE
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityStandard: uDAPL, 1.1, 1.2
_
MT-LevelSafe
.TE

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