LIBPSAP2-LPP(3N)

NAME
libpsap2-lpp - (Lightweight) Presentation Services library

SYNOPSIS
#include <isode/psap2.h>

cc ... -lpsap2-lpp

DESCRIPTION
The libpsap2 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.

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 User's Manual for actual examples of how ISO servers and clients are coded and interact with the libpsap2-lpp library.

ADDRESSES
PSAP addresses are represented by the PSAPaddr structure. This contains a session address, and a presentation-selector as found in the isoservices (5) database.

SERVER INITIALIZATION
A program providing an ISO service is usually invoked under lppd (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 lppd. This is accomplished by calling PInit. 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 execvp (it's important to call PInit prior to reading argc and argv). If the call to PInit is not successful, information returned by the call indicates the reason for failure.

After examining the information provided by PInit (and possibly the argument vector), the server should either accept or reject the connection. If accepting, the PConnResponse routine is called with the parameter result set to PC_ACCEPT. (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 PConnResponse routine is also called, but with the parameter result set to PC_REJECTED. (which corresponds to the refusing P-CONNECT.RESPONSE action), and the program may exit.

CLIENT INITIALIZATION
A program requesting an ISO service calls PConnRequest (which corresponds to the P-CONNECT.REQUEST action). If successful (depending on the responder's choice of result), the interaction is henceforth symmetric. If un-successful, information returned by the call indicates the reason for failure.

PRESENTATION-DESCRIPTORS
Once a connection has been established via a successful return from PConnResponse (for servers) or PConnRequest (for clients), a connection is referenced by a small integer (returned in a structure passed to these calls) called a presentation-descriptor. The presentation-descriptor appears as an argument to the peer routines described below.

For synchronous multiplexing of several connections, the routine PSelectMask updates a file-descriptor mask and counter for use with select (2).

PEER
A fatal failure (consult the User's Manual) on return from any of these routines is equivalent to a P-P-ABORT.INDICATION.

routine	action
PDataRequest	P-DATA.REQUEST
PReadRequest	P-READ.REQUEST (synchronous read)
PRelRequest	P-RELEASE.REQUEST
PRelResponse	P-RELEASE.RESPONSE
PUAabortRequest	P-U-ABORT.REQUEST

Note that the PReadRequest routine returns data from the peer by allocating memory. 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.

Finally, the routine PErrString takes a failure code from a PSAPabort structure and returns a null-terminated diagnostic string. Also, the routine PLocalHostName returns a null-terminated string denoting the name of the localhost;

FILES
isobjects	ISODE objects database
isoservices	ISODE services database

SEE ALSO
isobjects(5), isoservices(5), tsapd(8c),
The ISO Development Environment: User's Manual,
ISO 8822: Information Processing Systems -- Open Systems Interconnection -- Connection Oriented Presentation Service Definition,
RFC1085: ISO Presentation Services on top of TCP/IP-based internets

DIAGNOSTICS
All routines return the manifest constant NOTOK (-1) on error. In addition, those routines which take a pointer to a PSAPindication structure fill-in the structure as appropriate.

AUTHOR
Marshall T. Rose

BUGS
Do not confuse presentation-descriptors with file-descriptors. Unlike file-descriptors which are implemented by the kernel, presentation-descriptors do not work across forks and execs.