| blob | 0243297d9e86d21777e6f53f95362dc2596dd7a4 |
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_PSP_CREATE 3DAT "Jul 16, 2004"
8 .SH NAME
9 dat_psp_create \- create a persistent Public Service Point
10 .SH SYNOPSIS
11 .LP
12 .nf
13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
14 #include <\fBdat/udat.h\fR>
16 DAT_RETURN
17 dat_psp_create(
18 IN DAT_IA_HANDLE \fIia_handle\fR,
19 IN DAT_CONN_QUAL \fIconn_qual\fR,
20 IN DAT_EVD_HANDLE \fIevd_handle\fR,
21 IN DAT_PSP_FLAGS \fIpsp_flags\fR,
22 OUT DAT_PSP_HANDLE *\fIpsp_handle\fR
23 )
24 .fi
26 .SH PARAMETERS
27 .sp
28 .ne 2
29 .na
30 \fB\fIia_handle\fR\fR
31 .ad
32 .RS 14n
33 Handle for an instance of DAT IA.
34 .RE
36 .sp
37 .ne 2
38 .na
39 \fB\fIconn_qual\fR\fR
40 .ad
41 .RS 14n
42 Connection Qualifier of the IA on which the Public Service Point is listening.
43 .RE
45 .sp
46 .ne 2
47 .na
48 \fB\fIevd_handle\fR\fR
49 .ad
50 .RS 14n
51 Event Dispatcher that provides the Connection Requested Events to the Consumer.
52 The size of the event queue for the Event Dispatcher controls the size of the
53 backlog for the created Public Service Point.
54 .RE
56 .sp
57 .ne 2
58 .na
59 \fB\fIpsp_flags\fR\fR
60 .ad
61 .RS 14n
62 Flag that indicates whether the Provider or Consumer creates an Endpoint per
63 arrived Connection Request. The value of \fBDAT_PSP_PROVIDER\fR indicates that
64 the Consumer wants to get an Endpoint from the Provider; a value of
65 \fBDAT_PSP_CONSUMER\fR means the Consumer does not want the Provider to provide
66 an Endpoint for each arrived Connection Request.
67 .RE
69 .sp
70 .ne 2
71 .na
72 \fB\fIpsp_handle\fR\fR
73 .ad
74 .RS 14n
75 Handle to an opaque Public Service Point.
76 .RE
78 .SH DESCRIPTION
79 .sp
80 .LP
81 The \fBdat_psp_create()\fR function creates a persistent Public Service Point
82 that can receive multiple requests for connection and generate multiple
83 Connection Request instances that are delivered through the specified Event
84 Dispatcher in Notification events.
85 .sp
86 .LP
87 The \fBdat_psp_create()\fR function is blocking. When the Public Service Point
88 is created, \fBDAT_SUCCESS\fR is returned and \fIpsp_handle\fR contains a
89 handle to an opaque Public Service Point Object.
90 .sp
91 .LP
92 There is no explicit backlog for a Public Service Point. Instead, Consumers can
93 control the size of backlog through the queue size of the associated Event
94 Dispatcher.
95 .sp
96 .LP
97 The \fIpsp_flags\fR parameter allows Consumers to request that the Provider
98 create an implicit Endpoint for each incoming Connection Request, or request
99 that the Provider should not create one per Connection Request. If the Provider
100 cannot satisfy the request, the operation shall fail and
101 \fBDAT_MODEL_NOT_SUPPORTED\fR is returned.
102 .sp
103 .LP
104 All Endpoints created by the Provider have \fBDAT_HANDLE_NULL\fR for the
105 Protection Zone and all Event Dispatchers. The Provider sets up Endpoint
106 attributes to match the Active side connection request. The Consumer can change
107 Endpoint parameters. Consumers should change Endpoint parameters, especially PZ
108 and EVD, and are advised to change parameters for local accesses prior to the
109 connection request acceptance with the Endpoint.
110 .SH RETURN VALUES
111 .sp
112 .ne 2
113 .na
114 \fB\fBDAT_SUCCESS\fR\fR
115 .ad
116 .RS 30n
117 The operation was successful.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
124 .ad
125 .RS 30n
126 The operation failed due to resource limitations.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fBDAT_INVALID_HANDLE\fR\fR
133 .ad
134 .RS 30n
135 The \fIia_handle\fR or \fIevd_handle\fR parameter is invalid.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBDAT_INVALID_PARAMETER\fR\fR
142 .ad
143 .RS 30n
144 The \fIconn_qual\fR or \fIpsp_flags\fR parameter is invalid.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fBDAT_CONN_QUAL_IN_USE\fR\fR
151 .ad
152 .RS 30n
153 The specified Connection Qualifier was in use.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
160 .ad
161 .RS 30n
162 The requested Model was not supported by the Provider.
163 .RE
165 .SH USAGE
166 .sp
167 .LP
168 Two uses of a Public Service Point are as follows:
169 .sp
170 .ne 2
171 .na
172 \fBModel 1\fR
173 .ad
174 .RS 11n
175 For this model, the Provider manipulates a pool of Endpoints for a Public
176 Service Point. The Provider can use the same pool for more than one Public
177 Service Point.
178 .RS +4
179 .TP
180 .ie t \(bu
181 .el o
182 The DAT Consumer creates a Public Service Point with a \fIflag\fR set to
183 \fBDAT_PSP_PROVIDER\fR.
184 .RE
185 .RS +4
186 .TP
187 .ie t \(bu
188 .el o
189 The Public Service Point does the following:
190 .RS +4
191 .TP
192 .ie t \(bu
193 .el o
194 Collects native transport information reflecting a received Connection Reques
195 .RE
196 .RS +4
197 .TP
198 .ie t \(bu
199 .el o
200 Creates an instance of Connection Reques
201 .RE
202 .RS +4
203 .TP
204 .ie t \(bu
205 .el o
206 Creates a Connection Request Notice (event) that includes the Connection
207 Request instance (thatwhich includes, among others, Public Service Point, its
208 Connection Qualifier, Provider-generated Local Endpoint, and information about
209 remote Endpoint)
210 .RE
211 .RS +4
212 .TP
213 .ie t \(bu
214 .el o
215 Delivers the Connection Request Notice to the Consumer-specified target (CNO)
216 \fIevd_handle\fR
217 .sp
218 The Public Service Point is persistent and continues to listen for incoming
219 requests for connection.
220 .RE
221 .RE
222 .RS +4
223 .TP
224 .ie t \(bu
225 .el o
226 Upon receiving a connection request, or at some time subsequent to that, the
227 DAT Consumer can modify the provided local Endpoint to match the Connection
228 Request and must either \fBaccept()\fR or \fBreject()\fR the pending Connection
229 Request.
230 .RE
231 .RS +4
232 .TP
233 .ie t \(bu
234 .el o
235 If accepted, the provided Local Endpoint is now in a "connected" state and is
236 fully usable for this connection, pending only any native transport mandated
237 RTU (ready-to-use) messages. This includes binding it to the IA port if that
238 was not done previously. The Consumer is notified that the Endpoint is in
239 Connected state by a Connection Established Event on the Endpoint
240 \fIconnect_evd_handle\fR.
241 .RE
242 .RS +4
243 .TP
244 .ie t \(bu
245 .el o
246 If rejected, control of the Local Endpoint point is returned back to the
247 Provider and its \fIep_handle\fR is no longer usable by the Consumer.
248 .RE
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fBModel 2\fR
255 .ad
256 .RS 11n
257 For this model, the Consumer manipulates a pool of Endpoints. Consumers can use
258 the same pool for more than one Service Point.
259 .RS +4
260 .TP
261 .ie t \(bu
262 .el o
263 DAT Consumer creates a Public Service Point with a \fIflag\fR set to
264 \fBDAT_PSP_CONSUMER\fR.
265 .RE
266 .RS +4
267 .TP
268 .ie t \(bu
269 .el o
270 Public Service Point:
271 .RS +4
272 .TP
273 .ie t \(bu
274 .el o
275 Collects native transport information reflecting a received Connection Request
276 .RE
277 .RS +4
278 .TP
279 .ie t \(bu
280 .el o
281 Creates an instance of Connection Request
282 .RE
283 .RS +4
284 .TP
285 .ie t \(bu
286 .el o
287 Creates a Connection Request Notice (event) that includes the Connection
288 Request instance (which includes, among others, Public Service Point, its
289 Connection Qualifier, Provider-generated Local Endpoint and information about
290 remote Endpoint)
291 .RE
292 .RS +4
293 .TP
294 .ie t \(bu
295 .el o
296 Delivers the Connection Request Notice to the Consumer-specified target (CNO)
297 \fIevd_handle\fR
298 .sp
299 The Public Service Point is persistent and continues to listen for incoming
300 requests for connection.
301 .RE
302 .RE
303 .RS +4
304 .TP
305 .ie t \(bu
306 .el o
307 The Consumer creates a pool of Endpoints that it uses for accepting Connection
308 Requests. Endpoints can be created and modified at any time prior to accepting
309 a Connection Request with that Endpoint.
310 .RE
311 .RS +4
312 .TP
313 .ie t \(bu
314 .el o
315 Upon receiving a connection request or at some time subsequent to that, the DAT
316 Consumer can modify its local Endpoint to match the Connection Request and must
317 either \fBaccept()\fR or \fBreject()\fR the pending Connection Request.
318 .RE
319 .RS +4
320 .TP
321 .ie t \(bu
322 .el o
323 If accepted, the provided Local Endpoint is now in a "connected" state and is
324 fully usable for this connection, pending only any native transport mandated
325 RTU messages. This includes binding it to the IA port if that was not done
326 previously. The Consumer is notified that the Endpoint is in Connected state by
327 a Connection Established Event on the Endpoint \fIconnect_evd_handle\fR.
328 .RE
329 .RS +4
330 .TP
331 .ie t \(bu
332 .el o
333 If rejected, the Consumer does not have to provide any Endpoint for
334 \fBdat_cr_reject\fR(3DAT).
335 .RE
336 .RE
338 .SH ATTRIBUTES
339 .sp
340 .LP
341 See \fBattributes\fR(5) for descriptions of the following attributes:
342 .sp
344 .sp
345 .TS
346 box;
347 c | c
348 l | l .
349 ATTRIBUTE TYPE ATTRIBUTE VALUE
350 _
351 Interface Stability Standard: uDAPL, 1.1, 1.2
352 _
353 MT-Level Safe
354 .TE
356 .SH SEE ALSO
357 .sp
358 .LP
359 \fBdat_cr_reject\fR(3DAT), \fBlibdat\fR(3LIB), \fBattributes\fR(5)