![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to libpsap2-lpp.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 / psap2-lpp|
Return to libpsap2-lpp.3n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / psap2-lpp |
1.1 root 1: .TH LIBPSAP2\-LPP 3N "31 May 1988"
2: .\" $Header: /f/osi/psap2-lpp/RCS/libpsap2-lpp.3n,v 7.1 90/07/09 14:44:56 mrose Exp $
3: .\"
4: .\" Contributed by The Wollongong Group, Inc.
5: .\"
6: .\"
7: .\" $Log: libpsap2-lpp.3n,v $
8: .\" Revision 7.1 90/07/09 14:44:56 mrose
9: .\" sync
10: .\"
11: .\" Revision 7.0 89/11/23 22:15:47 mrose
12: .\" Release 6.0
13: .\"
14: .SH NAME
15: libpsap2\-lpp \- (Lightweight) Presentation Services library
16: .SH SYNOPSIS
17: .B "#include <isode/psap2.h>"
18: .sp
19: \fIcc\fR\0...\0\fB\-lpsap2\-lpp\fR
20: .SH DESCRIPTION
21: The \fIlibpsap2\fR library contains a set of routines which implement the
22: presentation services.
23: However,
24: instead of using the ISO presentation protocol,
25: it uses the special lightweight presentation protocol specified in
26: RFC1085.
27: In essence,
28: the library implements a Presentation Service Access Point (PSAP) interface for
29: user applications which utilize only the most minimal set of
30: presentation services.
31: Note well:
32: before using presentation services,
33: an understanding of the underlying session services is necessary.
34: .PP
35: Although the ISO model is symmetric,
36: this implementation is based on a client/server paradigm and hence asymmetric.
37: The information herein is skeletal:
38: consult the \fIUser's Manual\fR for actual examples of how ISO servers and
39: clients are coded and interact with the \fIlibpsap2\-lpp\fR library.
40: .SH ADDRESSES
41: PSAP addresses are represented by the \fBPSAPaddr\fR structure.
42: This contains a session address,
43: and a presentation-selector as found in the \fIisoservices\fR\0(5)
44: database.
45: .SH "SERVER INITIALIZATION"
46: A program providing an ISO service is usually invoked under \fIlppd\fR\0(8c),
47: with the argument vector listed in the ISODE services database.
48: The server's very first action is to re\-capture the PSAP state as
49: recorded by \fIlppd\fR.
50: This is accomplished by calling \fBPInit\fR.
51: Information returned by this call is equivalent to the parameters passed by a
52: P\-CONNECTION.INDICATION event.
53: If the call is successful,
54: the program can then examine the argument vector that was passed via
55: \fIexecvp\fR
56: (it's important to call \fBPInit\fR prior to reading \fBargc\fR and
57: \fBargv\fR).
58: If the call to \fBPInit\fR is not successful,
59: information returned by the call indicates the reason for failure.
60: .PP
61: After examining the information provided by \fBPInit\fR
62: (and possibly the argument vector),
63: the server should either accept or reject the connection.
64: If accepting, the \fBPConnResponse\fR routine is called with the parameter
65: \fBresult\fR set to \fBPC_ACCEPT\fR.
66: (which corresponds to the accepting P\-CONNECT.RESPONSE action).
67: If the call is successful,
68: the interaction is henceforth symmetric.
69: If un\-successful,
70: information returned by the call indicates the reason for failure.
71: If rejecting, the \fBPConnResponse\fR routine is also called,
72: but with the parameter \fBresult\fR set to \fBPC_REJECTED\fR.
73: (which corresponds to the refusing P\-CONNECT.RESPONSE action),
74: and the program may exit.
75: .SH "CLIENT INITIALIZATION"
76: A program requesting an ISO service calls \fBPConnRequest\fR
77: (which corresponds to the P\-CONNECT.REQUEST action).
78: If successful (depending on the responder's choice of \fBresult\fR),
79: the interaction is henceforth symmetric.
80: If un\-successful,
81: information returned by the call indicates the reason for failure.
82: .SH PRESENTATION\-DESCRIPTORS
83: Once a connection has been established via a successful return from
84: \fBPConnResponse\fR (for servers) or \fBPConnRequest\fR (for clients),
85: a connection is referenced by a small integer
86: (returned in a structure passed to these calls) called a
87: \fIpresentation\-descriptor\fR.
88: The presentation\-descriptor appears as an argument to the peer routines
89: described below.
90: .PP
91: For synchronous multiplexing of several connections,
92: the routine \fBPSelectMask\fR
93: updates a file\-descriptor mask and counter for use with \fIselect\fR\0(2).
94: .SH PEER
95: A fatal failure (consult the \fIUser's Manual\fR)
96: on return from any of these routines is equivalent to a
97: P\-P\-ABORT.INDICATION.
98: .sp
99: .in +.5i
100: .nf
101: .ta \w'\fBPUAbortRequest\fR 'u
102: \fIroutine\fR \fIaction\fR
103: \fBPDataRequest\fR P\-DATA.REQUEST
104: \fBPReadRequest\fR P\-READ.REQUEST (synchronous read)
105: \fBPRelRequest\fR P\-RELEASE.REQUEST
106: \fBPRelResponse\fR P\-RELEASE.RESPONSE
107: \fBPUAabortRequest\fR P\-U\-ABORT.REQUEST
108: .re
109: .fi
110: .in -.5i
111: .sp
112: Note that the \fBPReadRequest\fR routine returns data from the peer by
113: allocating memory.
114: It should be freed before the structure is re\-used.
115: .PP
116: Also note that presentation utilizes a graceful closing mechanism.
117: Upon receipt of a P\-RELEASE\-INDICATION event,
118: the peer must immediately respond with an P\-RELEASE\-RESPONSE.
119: Depending on the setting of the session requirements (described next),
120: the peer may indicate refusal in the response.
121: .PP
122: Finally,
123: the routine \fBPErrString\fR takes a failure code from a \fBPSAPabort\fR
124: structure and returns a null\-terminated diagnostic string.
125: Also,
126: the routine \fBPLocalHostName\fR returns a null\-terminated string denoting
127: the name of the localhost;
128: .SH FILES
129: .nf
130: .ta \w'\*(EDisoservices 'u
131: \*(EDisobjects ISODE objects database
132: \*(EDisoservices ISODE services database
133: .re
134: .fi
135: .SH "SEE ALSO"
136: isobjects(5), isoservices(5), tsapd(8c),
137: .br
138: \fIThe ISO Development Environment: User's Manual\fR,
139: .br
140: ISO 8822:
141: \fIInformation Processing Systems \-\- Open Systems Interconnection \-\-
142: Connection Oriented Presentation Service Definition\fR,
143: .br
144: RFC1085:
145: \fIISO Presentation Services on top of TCP/IP\-based internets\fR
146: .SH DIAGNOSTICS
147: All routines return the manifest constant \fBNOTOK\fR (\-1) on error.
148: In addition,
149: those routines which take a pointer to a \fBPSAPindication\fR structure
150: fill\-in the structure as appropriate.
151: .SH AUTHOR
152: Marshall T. Rose
153: .SH BUGS
154: Do not confuse presentation\-descriptors with file\-descriptors.
155: Unlike file\-descriptors which are implemented by the kernel,
156: presentation\-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.