![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to libpsap2.3n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / psap2|
Return to libpsap2.3n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / psap2 |
1.1 root 1: .TH LIBPSAP2 3N "31 May 1988"
2: .\" $Header: /f/osi/psap2/RCS/libpsap2.3n,v 7.0 89/11/23 22:14:11 mrose Rel $
3: .\"
4: .\"
5: .\" $Log: libpsap2.3n,v $
6: .\" Revision 7.0 89/11/23 22:14:11 mrose
7: .\" Release 6.0
8: .\"
9: .SH NAME
10: libpsap2 \- Presentation Services library
11: .SH SYNOPSIS
12: .B "#include <isode/psap2.h>"
13: .sp
14: \fIcc\fR\0...\0\fB\-lpsap2\fR
15: .SH DESCRIPTION
16: The \fIlibpsap2\fR library contains a set of routines which implement the
17: presentation services.
18: In essence,
19: they implement a Presentation Service Access Point (PSAP) interface for
20: user applications.
21: This manual page describes only the interface to the Basic Combined Subset
22: (BCS) of session which is available for presentation;
23: consult the \fIUser's Manual\fR for the full details on the entire PSAP
24: interface, which supports the entire presentation service.
25: Note well:
26: before using presentation services,
27: an understanding of the underlying session services is necessary.
28: .PP
29: Although the ISO model is symmetric,
30: this implementation is based on a client/server paradigm and hence asymmetric.
31: The information herein is skeletal:
32: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
33: clients are coded and interact with the \fIlibpsap2\fR library.
34: .SH ADDRESSES
35: PSAP addresses are represented by the \fBPSAPaddr\fR structure.
36: This contains a session address,
37: and a presentation-selector as found in the \fIisoservices\fR\0(5)
38: database.
39: .SH "SERVER INITIALIZATION"
40: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
41: with the argument vector listed in the ISODE services database.
42: The server's very first action is to re\-capture the PSAP state as
43: recorded by \fItsapd\fR.
44: This is accomplished by calling \fBPInit\fR.
45: Information returned by this call is equivalent to the parameters passed by a
46: P\-CONNECTION.INDICATION event.
47: If the call is successful,
48: the program can then examine the argument vector that was passed via
49: \fIexecvp\fR
50: (it's important to call \fBPInit\fR prior to reading \fBargc\fR and
51: \fBargv\fR).
52: If the call to \fBPInit\fR is not successful,
53: information returned by the call indicates the reason for failure.
54: .PP
55: After examining the information provided by \fBPInit\fR
56: (and possibly the argument vector),
57: the server should either accept or reject the connection.
58: If accepting, the \fBPConnResponse\fR routine is called with the parameter
59: \fBresult\fR set to \fBPC_ACCEPT\fR.
60: (which corresponds to the accepting P\-CONNECT.RESPONSE action).
61: If the call is successful,
62: the interaction is henceforth symmetric.
63: If un\-successful,
64: information returned by the call indicates the reason for failure.
65: If rejecting, the \fBPConnResponse\fR routine is also called,
66: but with the parameter \fBresult\fR set to \fBPC_REJECTED\fR.
67: (which corresponds to the refusing P\-CONNECT.RESPONSE action),
68: and the program may exit.
69: .SH "CLIENT INITIALIZATION"
70: A program requesting an ISO service calls \fBPConnRequest\fR
71: (which corresponds to the P\-CONNECT.REQUEST action).
72: If successful (depending on the responder's choice of \fBresult\fR),
73: the interaction is henceforth symmetric.
74: If un\-successful,
75: information returned by the call indicates the reason for failure.
76: .SH PRESENTATION\-DESCRIPTORS
77: Once a connection has been established via a successful return from
78: \fBPConnResponse\fR (for servers) or \fBPConnRequest\fR (for clients),
79: a connection is referenced by a small integer
80: (returned in a structure passed to these calls) called a
81: \fIpresentation\-descriptor\fR.
82: The presentation\-descriptor appears as an argument to the peer routines
83: described below.
84: .PP
85: By default,
86: events associated with a presentation\-descriptor are synchronous in nature:
87: activity in the network won't generate an INDICATION event without program
88: first asking to be told of any activity.
89: To mark a presentation\-descriptor as asynchronous,
90: a call to \fBPSetIndications\fR is made with the addresses of an integer
91: function to handle these events:
92: .sp
93: .in +.5i
94: .nf
95: .ta \w'\fIroutine\fR 'u
96: \fIroutine\fR \fIevents\fR
97: \fBfunc1\fR data
98: \fBfunc2\fR tokens
99: \fBfunc3\fR synchronization
100: \fBfunc4\fR activities
101: \fBfunc5\fR reports
102: \fBfunc6\fR release
103: \fBfunc7\fR aborts
104: .re
105: .fi
106: .in -.5i
107: .sp
108: Upon a successful return from \fBPSetIndications\fR,
109: these functions will be called as appropriate in this fashion:
110: .sp
111: .in +.5i
112: .B "(*func1) (sd, px);"
113: .sp
114: .B "(*func2) (sd, pt);"
115: .sp
116: .B "(*func3) (sd, pn);"
117: .sp
118: .B "(*func4) (sd, pv);"
119: .sp
120: .B "(*func5) (sd, pp);"
121: .sp
122: .B "(*func6) (sd, pf);"
123: .sp
124: .B "(*func7) (sd, pa);"
125: .in -.5i
126: .sp
127: where \fBpd\fR is the presentation\-descriptor,
128: \fBpx\fR is a pointer to a \fBPSAPdata\fR structure,
129: \fBpt\fR is a pointer to a \fBPSAPtoken\fR structure,
130: \fBpn\fR is a pointer to a \fBPSAPsync\fR structure,
131: \fBpv\fR is a pointer to a \fBPSAPactivity\fR structure,
132: \fBpp\fR is a pointer to a \fBPSAPreport\fR structure,
133: \fBpf\fR is a pointer to a \fBPSAPfinish\fR structure,
134: and \fBpa\fR is a pointer to a \fBPSAPabort\fR structure.
135: Any value returned by these functions is ignored.
136: .PP
137: Note well: the \fB\-lpsap\fR library uses the \fB\-ltsap\fR library to
138: provide this interface.
139: The latter library uses the SIGEMT signal to provide this service.
140: Programs loaded with \fB\-ltsap\fR that use asynchronous
141: presentation\-descriptors should NOT use SIGEMT for other purposes.
142: .PP
143: For synchronous multiplexing of several connections,
144: the routine \fBPSelectMask\fR
145: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
146: .SH PEER
147: A fatal failure (consult the \fIUser's Manual\fR)
148: on return from any of these routines is equivalent to a
149: P\-P\-ABORT.INDICATION.
150: .sp
151: .in +.5i
152: .nf
153: .ta \w'\fBPUAbortRequest\fR 'u
154: \fIroutine\fR \fIaction\fR
155: \fBPDataRequest\fR P\-DATA.REQUEST
156: \fBPExpdRequest\fR P\-EXPEDITED\-DATA.REQUEST
157: \fBPReadRequest\fR P\-READ.REQUEST (synchronous read)
158: \fBPGTokenRequest\fR P\-TOKEN\-GIVE.REQUEST
159: \fBPPTokenRequest\fR P\-TOKEN\-PLEASE.REQUEST
160: \fBPRelRequest\fR P\-RELEASE.REQUEST
161: \fBPRelResponse\fR P\-RELEASE.RESPONSE
162: \fBPUAabortRequest\fR P\-U\-ABORT.REQUEST
163: .re
164: .fi
165: .in -.5i
166: .sp
167: Note that the \fBPReadRequest\fR routine returns data from the peer by
168: allocating memory.
169: It should be freed before the structure is re\-used.
170: .PP
171: Also note that presentation utilizes a graceful closing mechanism.
172: Upon receipt of a P\-RELEASE\-INDICATION event,
173: the peer must immediately respond with an P\-RELEASE\-RESPONSE.
174: Depending on the setting of the session requirements (described next),
175: the peer may indicate refusal in the response.
176: .PP
177: Finally,
178: the routine \fBPErrString\fR takes a failure code from a \fBPSAPabort\fR
179: structure and returns a null\-terminated diagnostic string.
180: Also,
181: the routine \fBPLocalHostName\fR returns a null\-terminated string denoting
182: the name of the localhost;
183: .SH "SESSION REQUIREMENTS"
184: During the connection\-establishment phase,
185: the presentation\-users, presentation\-providers, and session\-providers
186: negotiate the characteristics of the connection.
187: In particular,
188: they negotiate the \*(lqsession requirements\*(rq.
189: These requirements describe functional aspects of the connection,
190: and are always negotiated downwards.
191: .SH FILES
192: .nf
193: .ta \w'\*(EDisoservices 'u
194: \*(EDisobjects ISODE objects database
195: \*(EDisoservices ISODE services database
196: .re
197: .fi
198: .SH "SEE ALSO"
199: isobjects(5), isoservices(5), tsapd(8c),
200: .br
201: \fIThe ISO Development Environment: User's Manual\fR,
202: .br
203: ISO 8822:
204: \fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
205: Connection Oriented Presentation Service Definition\fR
206: .SH DIAGNOSTICS
207: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
208: In addition,
209: those routines which take a pointer to a \fBPSAPindication\fR structure
210: fill\-in the structure as appropriate.
211: .SH AUTHOR
212: Marshall T. Rose
213: .SH BUGS
214: Do not confuse presentation\-descriptors with file\-descriptors.
215: Unlike file\-descriptors which are implemented by the kernel,
216: presentation\-descriptors do not work across \fIfork\fRs and \fIexec\fRs.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.