.TH LIBPSAP2 3N "31 May 1988"
.\" $Header: /f/osi/psap2/RCS/libpsap2.3n,v 7.1 91/02/22 09:37:22 mrose Interim $
.\" $Log: libpsap2.3n,v $
.\" Revision 7.1 91/02/22 09:37:22 mrose
.\" Revision 7.0 89/11/23 22:14:11 mrose
libpsap2 \- Presentation Services library
.B "#include <isode/psap2.h>"
\fIcc\fR\0...\0\fB\-lpsap2\fR
The \fIlibpsap2\fR library contains a set of routines which implement the
they implement a Presentation Service Access Point (PSAP) interface for
This manual page describes only the interface to the Basic Combined Subset
(BCS) of session which is available for presentation;
consult the \fIUser's Manual\fR for the full details on the entire PSAP
interface, which supports the entire presentation service.
before using presentation services,
an understanding of the underlying session services is necessary.
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 \fIlibpsap2\fR library.
PSAP addresses are represented by the \fBPSAPaddr\fR structure.
This contains a session address,
and a presentation-selector as found in the \fIisoservices\fR\0(5)
.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 PSAP state as
This is accomplished by calling \fBPInit\fR.
Information returned by this call is equivalent to the parameters passed by a
P\-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 \fBPInit\fR prior to reading \fBargc\fR and
If the call to \fBPInit\fR is not successful,
information returned by the call indicates the reason for failure.
After examining the information provided by \fBPInit\fR
(and possibly the argument vector),
the server should either accept or reject the connection.
If accepting, the \fBPConnResponse\fR routine is called with the parameter
\fBresult\fR set to \fBPC_ACCEPT\fR.
(which corresponds to the accepting P\-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 \fBPConnResponse\fR routine is also called,
but with the parameter \fBresult\fR set to \fBPC_REJECTED\fR.
(which corresponds to the refusing P\-CONNECT.RESPONSE action),
and the program may exit.
.SH "CLIENT INITIALIZATION"
A program requesting an ISO service calls \fBPConnRequest\fR
(which corresponds to the P\-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.
.SH PRESENTATION\-DESCRIPTORS
Once a connection has been established via a successful return from
\fBPConnResponse\fR (for servers) or \fBPConnRequest\fR (for clients),
a connection is referenced by a small integer
(returned in a structure passed to these calls) called a
\fIpresentation\-descriptor\fR.
The presentation\-descriptor appears as an argument to the peer routines
events associated with a presentation\-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 presentation\-descriptor as asynchronous,
a call to \fBPSetIndications\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 \fBPSetIndications\fR,
these functions will be called as appropriate in this fashion:
where \fBpd\fR is the presentation\-descriptor,
\fBpx\fR is a pointer to a \fBPSAPdata\fR structure,
\fBpt\fR is a pointer to a \fBPSAPtoken\fR structure,
\fBpn\fR is a pointer to a \fBPSAPsync\fR structure,
\fBpv\fR is a pointer to a \fBPSAPactivity\fR structure,
\fBpp\fR is a pointer to a \fBPSAPreport\fR structure,
\fBpf\fR is a pointer to a \fBPSAPfinish\fR structure,
and \fBpa\fR is a pointer to a \fBPSAPabort\fR structure.
Any value returned by these functions is ignored.
Note well: the \fB\-lpsap\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
presentation\-descriptors should NOT use SIGEMT for other purposes.
For synchronous multiplexing of several connections,
the routine \fBPSelectMask\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'\fBPUAbortRequest\fR 'u
\fIroutine\fR \fIaction\fR
\fBPDataRequest\fR P\-DATA.REQUEST
\fBPExpdRequest\fR P\-EXPEDITED\-DATA.REQUEST
\fBPReadRequest\fR P\-READ.REQUEST (synchronous read)
\fBPGTokenRequest\fR P\-TOKEN\-GIVE.REQUEST
\fBPPTokenRequest\fR P\-TOKEN\-PLEASE.REQUEST
\fBPRelRequest\fR P\-RELEASE.REQUEST
\fBPRelResponse\fR P\-RELEASE.RESPONSE
\fBPUAabortRequest\fR P\-U\-ABORT.REQUEST
Note that the \fBPReadRequest\fR routine returns data from the peer by
It should be freed before the structure is re\-used.
Also note that presentation utilizes a graceful closing mechanism.
Upon receipt of a P\-RELEASE\-INDICATION event,
the peer must immediately respond with an P\-RELEASE\-RESPONSE.
Depending on the setting of the session requirements (described next),
the peer may indicate refusal in the response.
the routine \fBPErrString\fR takes a failure code from a \fBPSAPabort\fR
structure and returns a null\-terminated diagnostic string.
the routine \fBPLocalHostName\fR returns a null\-terminated string denoting
the name of the localhost;
.SH "SESSION REQUIREMENTS"
During the connection\-establishment phase,
the presentation\-users, presentation\-providers, and session\-providers
negotiate the characteristics of the connection.
they negotiate the \*(lqsession requirements\*(rq.
These requirements describe functional aspects of the connection,
and are always negotiated downwards.
.ta \w'\*(EDisoservices 'u
\*(EDisobjects ISODE objects database
\*(EDisoservices ISODE services database
isobjects(5), isoservices(5), tsapd(8c),
\fIThe ISO Development Environment: User's Manual\fR,
\fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
Connection Oriented Presentation Service Definition\fR
All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
those routines which take a pointer to a \fBPSAPindication\fR structure
fill\-in the structure as appropriate.
Do not confuse presentation\-descriptors with file\-descriptors.
Unlike file\-descriptors which are implemented by the kernel,
presentation\-descriptors do not work across \fIfork\fRs and \fIexec\fRs.
projects / unix-history / blob