![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to libssap.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 / ssap|
Return to libssap.3n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / ssap |
1.1 root 1: .TH LIBSSAP 3N "31 May 1988"
2: .\" $Header: /f/osi/ssap/RCS/libssap.3n,v 7.0 89/11/23 22:25:17 mrose Rel $
3: .\"
4: .\"
5: .\" $Log: libssap.3n,v $
6: .\" Revision 7.0 89/11/23 22:25:17 mrose
7: .\" Release 6.0
8: .\"
9: .SH NAME
10: libssap \- Session Services library
11: .SH SYNOPSIS
12: .B "#include <isode/ssap.h>"
13: .sp
14: \fIcc\fR\0...\0\fB\-lssap\fR
15: .SH DESCRIPTION
16: The \fIlibssap\fR library contains a set of routines which implement
17: session services.
18: In essence,
19: they implement an Session Service Access Point (SSAP) interface for user
20: applications.
21: This manual page describes only the interface to the Basic Combined Subset
22: (BCS) of session;
23: consult the \fIUser's Manual\fR for the full details on the entire SSAP
24: interface.
25: .PP
26: Although the ISO model is symmetric,
27: this implementation is based on a client/server paradigm and hence asymmetric.
28: The information herein is skeletal:
29: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
30: clients are coded and interact with the \fIlibssap\fR library.
31: .SH ADDRESSES
32: SSAP addresses are represented by the \fBSSAPaddr\fR structure.
33: This contains a transport address,
34: and a session-selector as found in the \fIisoservices\fR\0(5)
35: database.
36: .PP
37: SSAP references,
38: represented by the \fBSSAPref\fR structure,
39: consist of three attributes:
40: the user reference, the common reference, and the additional reference.
41: These are preserved by the SSAP but otherwise ignored.
42: .SH "SERVER INITIALIZATION"
43: A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
44: with the argument vector listed in the ISODE services database.
45: The server's very first action is to re\-capture the SSAP state as
46: recorded by \fItsapd\fR.
47: This is accomplished by calling \fBSInit\fR.
48: Information returned by this call is equivalent to the parameters passed by a
49: S\-CONNECTION.INDICATION event.
50: If the call is successful,
51: the program can then examine the argument vector that was passed via
52: \fIexecvp\fR
53: (it's important to call \fBSInit\fR prior to reading \fBargc\fR and
54: \fBargv\fR).
55: If the call to \fBSInit\fR is not successful,
56: information returned by the call indicates the reason for failure.
57: .PP
58: After examining the information provided by \fBSInit\fR
59: (and possibly the argument vector),
60: the server should either accept or reject the connection.
61: If accepting, the \fBSConnResponse\fR routine is called with the parameter
62: \fBresult\fR set to
63: .sp
64: .in +.5i
65: .nf
66: .ta \w'SC_NOTSPECIFIED 'u
67: SC_ACCEPT connection accepted
68: .re
69: .fi
70: .in -.5i
71: .sp
72: (which corresponds to the accepting S\-CONNECT.RESPONSE action).
73: If the call is successful,
74: the interaction is henceforth symmetric.
75: If un\-successful,
76: information returned by the call indicates the reason for failure.
77: If rejecting, the \fBSConnResponse\fR routine is also called,
78: but with the parameter \fBresult\fR set to one of:
79: .sp
80: .in +.5i
81: .nf
82: .ta \w'SC_NOTSPECIFIED 'u
83: SC_NOTSPECIFIED reason not specified
84: SC_CONGESTION temporary congestion
85: SC_REJECTED rejected
86: .re
87: .fi
88: .in -.5i
89: .sp
90: (which corresponds to the refusing S\-CONNECT.RESPONSE action),
91: and the program may exit.
92: .SH "CLIENT INITIALIZATION"
93: A program requesting an ISO service calls \fBSConnRequest\fR
94: (which corresponds to the S\-CONNECT.REQUEST action).
95: If successful (depending on the responder's choice of \fBresult\fR),
96: the interaction is henceforth symmetric.
97: If un\-successful,
98: information returned by the call indicates the reason for failure.
99: .SH SESSION\-DESCRIPTORS
100: Once a connection has been established via a successful return from
101: \fBSConnResponse\fR (for servers) or \fBSConnRequest\fR (for clients),
102: a connection is referenced by a small integer
103: (returned in a structure passed to these calls) called a
104: \fIsession\-descriptor\fR.
105: The session\-descriptor appears as an argument to the peer routines described
106: below.
107: .PP
108: By default,
109: events associated with a session\-descriptor are synchronous in nature:
110: activity in the network won't generate an INDICATION event without program
111: first asking to be told of any activity.
112: To mark a session\-descriptor as asynchronous,
113: a call to \fBSSetIndications\fR is made with the addresses of an integer
114: function to handle these events:
115: .sp
116: .in +.5i
117: .nf
118: .ta \w'\fIroutine\fR 'u
119: \fIroutine\fR \fIevents\fR
120: \fBfunc1\fR data
121: \fBfunc2\fR tokens
122: \fBfunc3\fR synchronization
123: \fBfunc4\fR activities
124: \fBfunc5\fR reports
125: \fBfunc6\fR release
126: \fBfunc7\fR aborts
127: .re
128: .fi
129: .in -.5i
130: .sp
131: Upon a successful return from \fBSSetIndications\fR,
132: these functions will be called as appropriate in this fashion:
133: .sp
134: .in +.5i
135: .B "(*func1) (sd, sx);"
136: .sp
137: .B "(*func2) (sd, st);"
138: .sp
139: .B "(*func3) (sd, sn);"
140: .sp
141: .B "(*func4) (sd, sv);"
142: .sp
143: .B "(*func5) (sd, sp);"
144: .sp
145: .B "(*func6) (sd, sf);"
146: .sp
147: .B "(*func7) (sd, sa);"
148: .in -.5i
149: .sp
150: where \fBsd\fR is the session\-descriptor,
151: \fBsx\fR is a pointer to a \fBSSAPdata\fR structure,
152: \fBst\fR is a pointer to a \fBSSAPtoken\fR structure,
153: \fBsn\fR is a pointer to a \fBSSAPsync\fR structure,
154: \fBsv\fR is a pointer to a \fBSSAPactivity\fR structure,
155: \fBsp\fR is a pointer to a \fBSSAPreport\fR structure,
156: \fBsf\fR is a pointer to a \fBSSAPfinish\fR structure,
157: and \fBsa\fR is a pointer to a \fBSSAPabort\fR structure.
158: Any value returned by these functions is ignored.
159: .PP
160: Note well: the \fB\-lssap\fR library uses the \fB\-ltsap\fR library to
161: provide this interface.
162: The latter library uses the SIGEMT signal to provide this service.
163: Programs loaded with \fB\-ltsap\fR that use asynchronous session\-descriptors
164: should NOT use SIGEMT for other purposes.
165: .PP
166: For synchronous multiplexing of several connections,
167: the routine \fBSSelectMask\fR
168: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
169: .SH PEER
170: A fatal failure (consult the \fIUser's Manual\fR)
171: on return from any of these routines is equivalent to a
172: S\-P\-ABORT.INDICATION.
173: .sp
174: .in +.5i
175: .nf
176: .ta \w'\fBSUAbortRequest\fR 'u
177: \fIroutine\fR \fIaction\fR
178: \fBSDataRequest\fR S\-DATA.REQUEST
179: \fBSExpdRequest\fR S\-EXPEDITED\-DATA.REQUEST
180: \fBSReadRequest\fR S\-READ.REQUEST (synchronous read)
181: \fBSGTokenRequest\fR S\-TOKEN\-GIVE.REQUEST
182: \fBSPTokenRequest\fR S\-TOKEN\-PLEASE.REQUEST
183: \fBSRelRequest\fR S\-RELEASE.REQUEST
184: \fBSRelResponse\fR S\-RELEASE.RESPONSE
185: \fBSUAabortRequest\fR S\-U\-ABORT.REQUEST
186: .re
187: .fi
188: .in -.5i
189: .sp
190: Note that the \fBSReadRequest\fR routine returns data from the peer by
191: allocating memory.
192: It should be freed before the structure is re\-used.
193: .PP
194: Also note that session utilizes a graceful closing mechanism.
195: Upon receipt of a S\-RELEASE\-INDICATION event,
196: the peer must immediately respond with an S\-RELEASE\-RESPONSE.
197: Depending on the setting of the session requirements (described next),
198: the peer may indicate refusal in the response.
199: .PP
200: Finally,
201: the routine \fBSErrString\fR takes a failure code from a \fBSSAPabort\fR
202: structure and returns a null\-terminated diagnostic string.
203: Also,
204: the routine \fBSLocalHostName\fR returns a null\-terminated string denoting
205: the name of the localhost;
206: .SH "SESSION REQUIREMENTS"
207: During the connection\-establishment phase,
208: the session\-users and session\-providers negotiate the characteristics of
209: the connection.
210: In particular,
211: they negotiate the \*(lqsession requirements\*(rq.
212: These requirements describe functional aspects of the connection,
213: and are always negotiated downwards.
214: primitives.
215: .SH FILES
216: .nf
217: .ta \w'\*(EDisoservices 'u
218: \*(EDisoservices ISODE services database
219: .re
220: .fi
221: .SH "SEE ALSO"
222: isoservices(5), tsapd(8c),
223: .br
224: \fIThe ISO Development Environment: User's Manual\fR,
225: .br
226: ISO 8326:
227: \fIInformation Processing Systems \-\- Open Systems Interconnection~---~
228: Connection Oriented Session Service Definition\fR,
229: .br
230: CCITT Recommendation X.215:
231: \fISession Service Definition for Open Systems Interconnection (OSI) for
232: CCITT Applications\fR
233: .SH DIAGNOSTICS
234: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
235: In addition,
236: those routines which take a pointer to a \fBSSAPindication\fR structure
237: fill\-in the structure as appropriate.
238: .SH AUTHORS
239: Marshall T. Rose
240: .br
241: Dwight E. Cass,
242: Northrop Research and Technology Center
243: .SH BUGS
244: Do not confuse session\-descriptors with file\-descriptors.
245: Unlike file\-descriptors which are implemented by the kernel,
246: session\-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.