.TH LIBSSAP 3N "31 May 1988"
.\" $Header: /f/osi/ssap/RCS/libssap.3n,v 7.1 91/02/22 09:45:35 mrose Interim $
.\" Revision 7.1 91/02/22 09:45:35 mrose
.\" Revision 7.0 89/11/23 22:25:17 mrose
libssap \- Session Services library
.B "#include <isode/ssap.h>"
\fIcc\fR\0...\0\fB\-lssap\fR
The \fIlibssap\fR library contains a set of routines which implement
they implement an Session Service Access Point (SSAP) interface for user
This manual page describes only the interface to the Basic Combined Subset
consult the \fIUser's Manual\fR for the full details on the entire SSAP
Although the ISO model is symmetric,
this implementation is based on a client/server paradigm and hence asymmetric.
The information herein is skeletal:
consult the \fIUser's Manual\fR for actual examples of how ISO servers and
clients are coded and interact with the \fIlibssap\fR library.
SSAP addresses are represented by the \fBSSAPaddr\fR structure.
This contains a transport address,
and a session-selector as found in the \fIisoservices\fR\0(5)
represented by the \fBSSAPref\fR structure,
consist of three attributes:
the user reference, the common reference, and the additional reference.
These are preserved by the SSAP but otherwise ignored.
.SH "SERVER INITIALIZATION"
A program providing an ISO service is usually invoked under \fItsapd\fR\0(8c),
with the argument vector listed in the ISODE services database.
The server's very first action is to re\-capture the SSAP state as
This is accomplished by calling \fBSInit\fR.
Information returned by this call is equivalent to the parameters passed by a
S\-CONNECTION.INDICATION event.
If the call is successful,
the program can then examine the argument vector that was passed via
(it's important to call \fBSInit\fR prior to reading \fBargc\fR and
If the call to \fBSInit\fR is not successful,
information returned by the call indicates the reason for failure.
After examining the information provided by \fBSInit\fR
(and possibly the argument vector),
the server should either accept or reject the connection.
If accepting, the \fBSConnResponse\fR routine is called with the parameter
.ta \w'SC_NOTSPECIFIED 'u
SC_ACCEPT connection accepted
(which corresponds to the accepting S\-CONNECT.RESPONSE action).
If the call is successful,
the interaction is henceforth symmetric.
information returned by the call indicates the reason for failure.
If rejecting, the \fBSConnResponse\fR routine is also called,
but with the parameter \fBresult\fR set to one of:
.ta \w'SC_NOTSPECIFIED 'u
SC_NOTSPECIFIED reason not specified
SC_CONGESTION temporary congestion
(which corresponds to the refusing S\-CONNECT.RESPONSE action),
and the program may exit.
.SH "CLIENT INITIALIZATION"
A program requesting an ISO service calls \fBSConnRequest\fR
(which corresponds to the S\-CONNECT.REQUEST action).
If successful (depending on the responder's choice of \fBresult\fR),
the interaction is henceforth symmetric.
information returned by the call indicates the reason for failure.
Once a connection has been established via a successful return from
\fBSConnResponse\fR (for servers) or \fBSConnRequest\fR (for clients),
a connection is referenced by a small integer
(returned in a structure passed to these calls) called a
\fIsession\-descriptor\fR.
The session\-descriptor appears as an argument to the peer routines described
events associated with a session\-descriptor are synchronous in nature:
activity in the network won't generate an INDICATION event without program
first asking to be told of any activity.
To mark a session\-descriptor as asynchronous,
a call to \fBSSetIndications\fR is made with the addresses of an integer
function to handle these events:
\fIroutine\fR \fIevents\fR
\fBfunc3\fR synchronization
Upon a successful return from \fBSSetIndications\fR,
these functions will be called as appropriate in this fashion:
where \fBsd\fR is the session\-descriptor,
\fBsx\fR is a pointer to a \fBSSAPdata\fR structure,
\fBst\fR is a pointer to a \fBSSAPtoken\fR structure,
\fBsn\fR is a pointer to a \fBSSAPsync\fR structure,
\fBsv\fR is a pointer to a \fBSSAPactivity\fR structure,
\fBsp\fR is a pointer to a \fBSSAPreport\fR structure,
\fBsf\fR is a pointer to a \fBSSAPfinish\fR structure,
and \fBsa\fR is a pointer to a \fBSSAPabort\fR structure.
Any value returned by these functions is ignored.
Note well: the \fB\-lssap\fR library uses the \fB\-ltsap\fR library to
The latter library uses the SIGEMT signal to provide this service.
Programs loaded with \fB\-ltsap\fR that use asynchronous session\-descriptors
should NOT use SIGEMT for other purposes.
For synchronous multiplexing of several connections,
the routine \fBSSelectMask\fR
updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
A fatal failure (consult the \fIUser's Manual\fR)
on return from any of these routines is equivalent to a
.ta \w'\fBSUAbortRequest\fR 'u
\fIroutine\fR \fIaction\fR
\fBSDataRequest\fR S\-DATA.REQUEST
\fBSExpdRequest\fR S\-EXPEDITED\-DATA.REQUEST
\fBSReadRequest\fR S\-READ.REQUEST (synchronous read)
\fBSGTokenRequest\fR S\-TOKEN\-GIVE.REQUEST
\fBSPTokenRequest\fR S\-TOKEN\-PLEASE.REQUEST
\fBSRelRequest\fR S\-RELEASE.REQUEST
\fBSRelResponse\fR S\-RELEASE.RESPONSE
\fBSUAabortRequest\fR S\-U\-ABORT.REQUEST
Note that the \fBSReadRequest\fR routine returns data from the peer by
It should be freed before the structure is re\-used.
Also note that session utilizes a graceful closing mechanism.
Upon receipt of a S\-RELEASE\-INDICATION event,
the peer must immediately respond with an S\-RELEASE\-RESPONSE.
Depending on the setting of the session requirements (described next),
the peer may indicate refusal in the response.
the routine \fBSErrString\fR takes a failure code from a \fBSSAPabort\fR
structure and returns a null\-terminated diagnostic string.
the routine \fBSLocalHostName\fR returns a null\-terminated string denoting
the name of the localhost;
.SH "SESSION REQUIREMENTS"
During the connection\-establishment phase,
the session\-users and session\-providers negotiate the characteristics of
they negotiate the \*(lqsession requirements\*(rq.
These requirements describe functional aspects of the connection,
and are always negotiated downwards.
.ta \w'\*(EDisoservices 'u
\*(EDisoservices ISODE services database
isoservices(5), tsapd(8c),
\fIThe ISO Development Environment: User's Manual\fR,
\fIInformation Processing Systems \-\- Open Systems Interconnection~---~
Connection Oriented Session Service Definition\fR,
CCITT Recommendation X.215:
\fISession Service Definition for Open Systems Interconnection (OSI) for
All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
those routines which take a pointer to a \fBSSAPindication\fR structure
fill\-in the structure as appropriate.
Northrop Research and Technology Center
Do not confuse session\-descriptors with file\-descriptors.
Unlike file\-descriptors which are implemented by the kernel,
session\-descriptors do not work across \fIfork\fRs and \fIexec\fRs.
projects / unix-history / blob