⟦51c4cb063⟧

TextFile

.TH LIBPSAP2 3N "31 May 1988"
.\" $Header: /f/osi/psap2-lpp/RCS/libpsap2-lpp.3n,v 7.0 89/11/23 22:15:47 mrose Rel $
.\"
.\" Contributed by The Wollongong Group, Inc.
.\"
.\"
.\" $Log:	libpsap2-lpp.3n,v $
.\" Revision 7.0  89/11/23  22:15:47  mrose
.\" Release 6.0
.\" 
.SH NAME
libpsap2\-lpp \- (Lightweight) Presentation Services library
.SH SYNOPSIS
.B "#include <isode/psap2.h>"
.sp
\fIcc\fR\0...\0\fB\-lpsap2\-lpp\fR
.SH DESCRIPTION
The \fIlibpsap2\fR library contains a set of routines which implement the
presentation services.
However,
instead of using the ISO presentation protocol,
it uses the special lightweight presentation protocol specified in
RFC1085.
In essence,
the library implements a Presentation Service Access Point (PSAP) interface for
user applications which utilize only the most minimal set of
presentation services.
Note well:
before using presentation services,
an understanding of the underlying session services is necessary.
.PP
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\-lpp\fR library.
.SH ADDRESSES
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)
database.
.SH "SERVER INITIALIZATION"
A program providing an ISO service is usually invoked under \fIlppd\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
recorded by \fIlppd\fR.
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
\fIexecvp\fR
(it's important to call \fBPInit\fR prior to reading \fBargc\fR and
\fBargv\fR).
If the call to \fBPInit\fR is not successful,
information returned by the call indicates the reason for failure.
.PP
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.
If un\-successful,
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.
If un\-successful,
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
described below.
.PP
For synchronous multiplexing of several connections,
the routine \fBPSelectMask\fR
updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
.SH PEER
A fatal failure (consult the \fIUser's Manual\fR)
on return from any of these routines is equivalent to a
P\-P\-ABORT.INDICATION.
.sp
.in +.5i
.nf
.ta \w'\fBPUAbortRequest\fR  'u
\fIroutine\fR	\fIaction\fR
\fBPDataRequest\fR	P\-DATA.REQUEST
\fBPReadRequest\fR	P\-READ.REQUEST (synchronous read)
\fBPRelRequest\fR	P\-RELEASE.REQUEST
\fBPRelResponse\fR	P\-RELEASE.RESPONSE
\fBPUAabortRequest\fR	P\-U\-ABORT.REQUEST
.re
.fi
.in -.5i
.sp
Note that the \fBPReadRequest\fR routine returns data from the peer by
allocating memory.
It should be freed before the structure is re\-used.
.PP
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.
.PP
Finally,
the routine \fBPErrString\fR takes a failure code from a \fBPSAPabort\fR
structure and returns a null\-terminated diagnostic string.
Also,
the routine \fBPLocalHostName\fR returns a null\-terminated string denoting
the name of the localhost;
.SH FILES
.nf
.ta \w'\*(EDisoservices  'u
\*(EDisobjects	ISODE objects database
\*(EDisoservices	ISODE services database
.re
.fi
.SH "SEE ALSO"
isobjects(5), isoservices(5), tsapd(8c),
.br
\fIThe ISO Development Environment: User's Manual\fR,
.br
ISO 8822:
\fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
Connection Oriented Presentation Service Definition\fR,
.br
RFC1085:
\fIISO Presentation Services on top of TCP/IP\-based internets\fR
.SH DIAGNOSTICS
All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
In addition,
those routines which take a pointer to a \fBPSAPindication\fR structure
fill\-in the structure as appropriate.
.SH AUTHOR
Marshall T. Rose
.SH BUGS
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.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦51c4cb063⟧ TextFile

Derivation

TextFile
