![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to psap2.tex 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 / doc / manual|
Return to psap2.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
1.1 root 1: % run this through LaTeX with the appropriate wrapper
2:
3: \chapter {Presentation Services}\label{libpsap2}
4: The \man libpsap2(3n) library implements the presentation service.
5: The kernel subset of the ISO specification is currently implemented.
6: That is,
7: the library supports whatever session requirements the user wishes to
8: employ,
9: negotiates presentation contexts on connection establishments,
10: and utilizes abstract transfer notations to transmit data structures in a
11: machine-independent manner.
12:
13: As with most models of OSI services,
14: the underlying assumption is one of a symmetric, asynchronous environment.
15: That is,
16: although peers exist at a given layer,
17: one does not necessary view a peer as either a client or a server.
18: Further,
19: the service provider may generate events for the service user without the
20: latter entity triggering the actions which led to the event.
21: For example,
22: in a synchronous environment,
23: an indication that data has arrived usually occurs only when the service user
24: asks the service provider to read data;
25: in an asynchronous environment,
26: the service provider may interrupt the service user at any time to announce
27: the arrival of data.
28:
29: The \verb"psap2" module in this release initially uses a client/server
30: paradigm to start communications.
31: Once the connection is established,
32: a symmetric view is taken.
33: In addition,
34: initially the interface is synchronous;
35: however once the connection is established,
36: an asynchronous interface may be selected.
37:
38: All of the routines in the \man libpsap2(3n) library are integer-valued.
39: They return the manifest constant \verb"OK" on success,
40: or \verb"NOTOK" otherwise.
41:
42: \section {Warning}
43: Please read the following important message.
44: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
45: \bf NOTE:& Readers of this chapter should have an intimate understanding
46: of the OSI presentation and session services.
47: It is not the intent of this
48: chapter to present a tutorial on these services, so novice
49: users will suffer greatly if they choose to read further.
50: \end{tabular}}\]
51:
52: \section {Addresses}\label{psap:addresses}
53: Addresses at the presentation service access point are represented by the
54: \verb"PSAPaddr" structure.
55: \begin{quote}\index{PSAPaddr}\small\begin{verbatim}
56: struct PSAPaddr {
57: struct SSAPaddr pa_addr;
58:
59: #define PSSIZE 64
60: int pa_selectlen;
61: char pa_selector[PSSIZE];
62: };
63: #define NULLPA ((struct PSAPaddr *) 0)
64: \end{verbatim}\end{quote}
65: This structure contains two elements:
66: \begin{describe}
67: \item[\verb"pa\_addr":] the session address,
68: as described in Section~\ref{ssap:addresses} on page~\pageref{ssap:addresses};
69: and,
70:
71: \item[\verb"pa\_selector"/\verb"pa\_selectlen":] the presentation selector,
72: as described in the \man isoservices(5) database in Chapter~\ref{isoservices},
73: for the service provider \verb"psap".
74: \end{describe}
75:
76: In Figure~\ref{getAPprovider},
77: an example of how one constructs the PSAP address for the LOOP provider on
78: host \verb"RemoteHost" is presented.
79: The routine \verb"is2paddr" takes a host and service,
80: and then consults the \man isoentities(5) file described in
81: Chapter~\ref{isoentities} of \volone/ to construct a presentation
82: address.
83: \begin{quote}\index{is2paddr}\small\begin{verbatim}
84: struct PSAPaddr *is2paddr (host, service, is)
85: char *host,
86: *service;
87: struct isoservent *is;
88: \end{verbatim}\end{quote}
89: \tagrind[tp]{grind5a-1}{Constructing the PSAP address for the LOOP provider}%
90: {getAPprovider}
91:
92: \subsection {Calling Address}
93: Certain users of the presentation service
94: (e.g., the reliable transfer service)
95: need to know the name of the local host when they initiate a connection.
96: The routine \verb"PLocalHostName" has been provided for this reason.
97: \begin{quote}\index{PLocalHostName}\small\begin{verbatim}
98: char *PLocalHostName ()
99: \end{verbatim}\end{quote}
100:
101: \section {Connection Establishment}
102: Until the connection has been fully established,
103: the implementation distinguishes between clients and servers,
104: which are more properly referred to as {\em initiators\/} and
105: {\em responders}, to use OSI terminology.
106:
107: \subsection {Connection Negotiation}
108: From the user's perspective,
109: there are several parameters which are negotiated by the presentation providers
110: during connection establishment.
111: Suggestions as to the values of some of these parameters are made by the user.
112:
113: \subsubsection {Session Parameters}
114: Consult Section~\ref{ssap:negotiation} for a list of session parameters which
115: are negotiated during connection establishment.
116:
117: \subsubsection {Presentation Contexts}\label{psap:context}
118: A {\em presentation context\/} is a binding between an abstract syntax
119: notation and an abstract transfer notation on a
120: presentation connection,
121: and is denoted by an integer value termed the context identifier.
122: The abstract syntax notation describes,
123: to the users of the presentation service,
124: the data structures being exchanged;
125: the abstract transfer notation describes,
126: to the providers of the presentation services,
127: the method for encoding those data structures in a machine-independent fashion.
128: Hence the abstract syntax notation is negotiated by the users of the
129: presentation service,
130: while the abstract transfer notation is negotiated by the providers of that
131: service.
132:
133: When a connection is established,
134: the initiator suggests zero or more presentation contexts,
135: specifying a context identifier (an odd-valued integer),
136: and the abstract syntax
137: (a pointer to an object identifier, see Section~\ref{psap:oid} of \volone/).
138: The provider selects the abstract transfer notation
139: (in the current implementation, this is always ASN.1\cite{ISO.PP.Encoding}).
140: When the a {\sf P-CONNECT.INDICATION\/} event is given to the responder,
141: in addition
142: indicating the context identifier and abstract syntax information,
143: the provider also indicates if it is willing to support this presentation
144: context.
145: If so, the responder decides if it will accept or reject the context.
146: This information is then propagated back to the initiator with
147: the {\sf P-CONNECT.CONFIRMATION\/} indication.
148:
149: \subsection {Server Initialization}
150: The \man tsapd(8c) daemon,
151: upon accepting a connection from an initiating host,
152: consults the ISO services database to determine which program
153: on the local system implements the desired SSAP entity.
154: In the case of the presentation service,
155: the \pgm{tsapd} program contains the bootstrap for the presentation provider.
156: The daemon will again consult the ISO services database to determine which
157: program on the system implements the desired PSAP entity.
158:
159: Once the program has been ascertained,
160: the daemon runs the program with any arguments listed in the database.
161: In addition,
162: it appends some {\em magic arguments\/} to the argument vector.
163: Hence,
164: the very first action performed by the responder is to re-capture the PSAP
165: state contained in the magic arguments.
166: This is done by calling the routine \verb"PInit",
167: which on a successful return,
168: is equivalent to a {\sf P-CONNECT.INDICATION\/} from the presentation service
169: provider.
170: \begin{quote}\index{PInit}\small\begin{verbatim}
171: int PInit (vecp, vec, ps, pi)
172: int vecp;
173: char **vec;
174: struct PSAPstart *ps;
175: struct PSAPindication *pi;
176: \end{verbatim}\end{quote}
177: The parameters to this procedure are:
178: \begin{describe}
179: \item[\verb"vecp":] the length of the argument vector;
180:
181: \item[\verb"vec":] the argument vector;
182:
183: \item[\verb"ps":] a pointer to a \verb"PSAPstart" structure, which is updated
184: only if the call succeeds;
185: and,
186:
187: \item[\verb"pi":] a pointer to a \verb"PSAPindication" structure, which is
188: updated only if the call fails.
189: \end{describe}
190: If \verb"PInit" is successful,
191: it returns information in the \verb"ps" parameter,
192: which is a pointer to a \verb"PSAPstart" structure.
193: \begin{quote}\index{PSAPstart}\small\begin{verbatim}
194: struct PSAPstart {
195: int ps_sd;
196:
197: struct PSAPaddr ps_calling;
198: struct PSAPaddr ps_called;
199:
200: struct PSAPctxlist ps_ctxlist;
201:
202: OID ps_defctx;
203: int ps_defctxresult;
204:
205: int ps_prequirements;
206:
207: int ps_srequirements;
208: int ps_settings;
209: long ps_isn;
210:
211: struct SSAPref ps_connect;
212:
213: int ps_ssdusize;
214:
215: struct QOStype ps_qos;
216:
217: #define NPDATA 10
218: int ps_ninfo;
219: PE ps_info[NPDATA];
220: };
221: \end{verbatim}\end{quote}
222: The elements of this structure are:\label{PSAPstart}
223: \begin{describe}
224: \item[\verb"ps\_sd":] the presentation-descriptor to be used to reference this
225: connection;
226:
227: \item[\verb"ps\_calling":] the address of the peer initiating the connection;
228:
229: \item[\verb"ps\_called":] the address of the peer being asked to respond;
230:
231: \item[\verb"ps\_ctxlist":] the proposed list of presentation contexts;
232:
233: \item[\verb"ps\_defctx"/\verb"ps\_defctxresult":] the default context
234: for the presentation connection
235: (and the presentation provider's response);
236:
237: \item[\verb"ps\_prequirements":] the proposed presentation requirements;
238:
239: \item[\verb"ps\_srequirements":] the proposed session requirements;
240:
241: \item[\verb"ps\_settings":] the initial token settings;
242:
243: \item[\verb"ps\_isn":] the initial serial-number;
244:
245: \item[\verb"ps\_connect":] the connection identifier (a.k.a. SSAP reference)
246: used by the initiator;
247:
248: \item[\verb"ps\_ssdusize":] the largest atomic SSDU size that can be used on
249: the connection (see the note on page~\pageref{SSDU:atomic});
250:
251: \item[\verb"ps\_qos":] the quality of service on the connection
252: (see Section~\ref{tsap:qos});
253: and,
254:
255: \item[\verb"ps\_info"/\verb"ps\_ninfo":] an array of initial data
256: (and the number of elements in that array).
257: \end{describe}
258: Note that the \verb"ps_info" element is allocated via \man malloc(3) and
259: should be released using the \verb"PSFREE" macro when no longer referenced.
260: The \verb"PSFREE" macro behaves as if it was defined as:
261: \begin{quote}\index{PSFREE}\small\begin{verbatim}
262: void PSFREE (ps)
263: struct PSAPstart *ps;
264: \end{verbatim}\end{quote}
265: The macro frees only the data allocated by \verb"PInit",
266: and not the \verb"PSAPstart" structure itself.
267: Further,
268: \verb"PSFREE" should be called only if the call to the \verb"PInit"
269: routine returned \verb"OK".
270:
271: The \verb"ps_connect" element is a \verb"SSAPref" structure,
272: which is passed transparently by the presentation service.
273: Consult the description on page~\pageref{SSAPref}.
274: There are two routines of interest in the \man libpsap2(3n) that deal with
275: these structures:
276: The \verb"addr2ref" routine takes a string (presumably a hostname),
277: determines the current UT time,
278: and returns a pointer to a \verb"SSAPref" structure appropriately initialized
279: to denote this information.
280: \begin{quote}\index{addr2ref}\small\begin{verbatim}
281: struct SSAPref *addr2ref (addr)
282: char *addr;
283: \end{verbatim}\end{quote}
284: This routine might fail if it is unable to allocate a small amount of
285: memory.
286: In this event, it returns the manifest constant \verb"NULL".
287: The routine \verb"sprintref" can be used to return a null-terminated string
288: describing the SSAP reference.
289: \begin{quote}\index{sprintref}\small\begin{verbatim}
290: char *sprintref (sr)
291: struct SSAPref *sr;
292: \end{verbatim}\end{quote}
293:
294: The \verb"ps_ctxlist" element is a \verb"PSAPctxlist" structure,
295: which describes the presentation contexts the initiator wishes to use.
296: \begin{quote}\index{PSAPctxlist}\small\begin{verbatim}
297: struct PSAPctxlist {
298: int pc_nctx;
299:
300: #define NPCTX 5
301:
302: struct PSAPcontext {
303: int pc_id;
304: OID pc_asn;
305: OID pc_atn;
306: int pc_result;
307: } pc_ctx[NPCTX];
308: };
309: #define NULLPC ((struct PSAPctxlist *) 0)
310: \end{verbatim}\end{quote}
311: The elements of this structure are:\label{PSAPctxlist}
312: \begin{describe}
313: \item[\verb"pc\_ctx"/\verb"pc\_nctx":] the presentation contexts described
314: (and the number of contexts which may not exceed \verb"NPCTX" elements).
315: For each presentation context:
316: \begin{describe}
317: \item[\verb"pc\_id":] the identifier (or handle) for the context;
318:
319: \item[\verb"pc\_asn":] the abstract syntax notation to be used on the
320: context;
321:
322: \item[\verb"pc\_atn":] the transfer syntax notation to be used on the
323: context (this field is usually, \verb"NULLOID", only the initiator,
324: when it wishes to inform the presentation service of the transfer
325: syntax to use, is permitted to specify this); and,
326:
327: \item[\verb"pc\_result":] the presentation provider's response
328: (codes are listed in Table~\ref{PSAPreasons}).
329: \end{describe}
330: \end{describe}
331:
332: If the call to the \verb"PInit" routine is not successful,
333: then a {\sf P-P-ABORT.IN\-DI\-CA\-TION\/} event is simulated,
334: and the relevant information is returned in a \verb"PSAPindication"
335: structure.\label{PSAPindication}
336: \begin{quote}\index{PSAPindication}\small\begin{verbatim}
337: struct PSAPindication {
338: int pi_type;
339: #define PI_DATA 0x00
340: #define PI_TOKEN 0x01
341: #define PI_SYNC 0x02
342: #define PI_ACTIVITY 0x03
343: #define PI_REPORT 0x04
344: #define PI_FINISH 0x05
345: #define PI_ABORT 0x06
346:
347: union {
348: struct PSAPdata pi_un_data;
349: struct PSAPtoken pi_un_token;
350: struct PSAPsync pi_un_sync;
351: struct PSAPactivity pi_un_activity;
352: struct PSAPreport pi_un_report;
353: struct PSAPfinish pi_un_finish;
354: struct PSAPabort pi_un_abort;
355: } pi_un;
356: #define pi_data pi_un.pi_un_data
357: #define pi_token pi_un.pi_un_token
358: #define pi_sync pi_un.pi_un_sync
359: #define pi_activity pi_un.pi_un_activity
360: #define pi_report pi_un.pi_un_report
361: #define pi_finish pi_un.pi_un_finish
362: #define pi_abort pi_un.pi_un_abort
363: };
364: \end{verbatim}\end{quote}
365: As shown, this structure is really a discriminated union
366: (a structure with a tag element followed by a union).
367: Hence, on a failure return,
368: one first coerces a pointer to the \verb"PSAPabort" structure contained
369: therein,
370: and then consults the elements of that structure.
371: \begin{quote}\index{PSAPabort}\small\begin{verbatim}
372: struct PSAPabort {
373: int pa_peer;
374:
375: int pa_reason;
376: int pa_ppdu;
377:
378:
379: int pa_ninfo;
380: char pa_info;
381:
382: #define PA_SIZE 512
383: int pa_cc;
384: char pa_data[PA_SIZE];
385: };
386: \end{verbatim}\end{quote}
387: The elements of a \verb"PSAPabort" structure are:
388: \begin{describe}
389: \item[\verb"pa\_peer":] if set, indicates that a user-initiated abort occurred
390: (a {\sf P-U-ABORT.INDICATION\/} event);
391: if not set, indicates that a provider-initiated abort occurred
392: (a {\sf P-P-ABORT.INDICATION\/} event);
393:
394: \item[\verb"pa\_reason":] the reason for the provider-initiated
395: abort (codes are listed in Table~\ref{PSAPreasons});
396:
397: \item[\verb"pa\_ppdu":] the type of presentation protocol data unit which
398: triggered the provider-initiated abort
399: (codes are listed in Table~\ref{PSAPppdus});
400:
401: \item[\verb"pa\_data"/\verb"pa\_cc":] a provider-generated diagnostic string
402: (and the length of that string);
403: and,
404:
405: \item[\verb"pa\_info"/\verb"pa\_ninfo":] an array of user data,
406: and the number of elements in that array (if \verb"pa_peer" is set).
407: \end{describe}
408: \tagtable[tp]{5a-1}{PSAP Failure Codes}{PSAPreasons}
409: \tagtable[tp]{5a-2}{PSAP PPDU Codes}{PSAPppdus}
410: Note that the \verb"pa_info" element is allocated via \man malloc(3) and
411: should be released using the \verb"PAFREE" macro when no longer referenced.
412: The \verb"PAFREE" macro behaves as if it was defined as:
413: \begin{quote}\index{PAFREE}\small\begin{verbatim}
414: void PAFREE (pa)
415: struct PSAPabort *pa;
416: \end{verbatim}\end{quote}
417: The macro frees only the data allocated in the \verb"PSAPabort" structure
418: and not the structure itself.
419:
420: After examining the information returned by \verb"PInit" on a successful call
421: (and possibly after examining the argument vector),
422: the responder should either accept or reject the connection.
423: For either response,
424: the responder should use
425: the \verb"PConnResponse" routine
426: (which corresponds to the {\sf P-CONNECT.RESPONSE\/} action).
427: \begin{quote}\index{PConnResponse}\small\begin{verbatim}
428: int PConnResponse (sd, status, responding, ctxlist,
429: defctxresult, prequirements, srequirements,
430: isn, settings, ref, data, ndata, pi)
431: int sd;
432: struct PSAPaddr *responding;
433: int status,
434: prequirements,
435: srequirements,
436: settings,
437: ndata;
438: long isn;
439: struct PSAPctxlist *ctxlist;
440: int defctxresult;
441: struct SSAPref *ref;
442: PE *data;
443: struct PSAPindication *pi;
444: \end{verbatim}\end{quote}
445: The parameters to this procedure are:\label{PConnResponse}
446: \begin{describe}
447: \item[\verb"sd":] the presentation-descriptor;
448:
449: \item[\verb"result":] the acceptance indicator
450: (either \verb"PC_ACCEPT" if the connection is to be accepted,
451: or \verb"PC_REJECTED" otherwise);
452:
453: \item[\verb"responding":] the PSAP address of the responder (defaulting to the
454: called address, if not present);
455:
456: \item[\verb"ctxlist":] the responder's decision as to each of the presentation
457: contexts suggested
458: (for each proposed context,
459: if the \verb"pc_result" element supplied by the provider is \verb"PC_ACCEPT",
460: which indicates that the provider is willing to support it,
461: the user may supply either \verb"PC_ACCEPT" or the value \verb"PC_REJECTED");
462:
463: \item[\verb"defctxresult":] the response to the default context
464: (if the presentation provider responded with \verb"PC_ACCEPT",
465: the user may supply either \verb"PC_ACCEPT" or
466: \verb"PC_REJECTED");
467:
468: \item[\verb"prequirements":] the responder's presentation requirements;
469:
470: \item[\verb"srequirements":] the responder's session requirements;
471:
472: \item[\verb"isn":] the initial serial-number;
473:
474: \item[\verb"settings":] the initial token settings;
475:
476: \item[\verb"ref":] the connection identifier used by the responder
477: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
478: structure);
479:
480: \item[\verb"data"/\verb"ndata":] an array of initial data
481: (and the number of elements in that array,
482: consult the warning on page~\pageref{PSAPdata});
483: and,
484:
485: \item[\verb"pi":] a pointer to a \verb"PSAPindication" structure, which is
486: updated only if the call fails.
487: \end{describe}
488: If the call to \verb"PConnResponse" is successful,
489: and if the \verb"result" parameter is set to \verb"PC_ACCEPT",
490: then connection establishment has completed
491: and the users of the presentation service now operate as symmetric peers.
492: If the call is successful,
493: but the \verb"result" parameter is \verb"PC_REJECTED" instead,
494: then the connection has been rejected and the responder may exit.
495: Otherwise, if the call fails and the reason is not an interface error
496: (see Table~\ref{PSAPreasons} on page~\pageref{PSAPreasons}),
497: then the connection is closed.
498:
499: Note that when the responder rejects the connection,
500: it need only supply meaningful values for the \verb"sd", \verb"status",
501: \verb"defctxresult", and \verb"pi" parameters.
502:
503: \subsection {Client Initialization}
504: A program wishing to connect to another user of presentation services calls the
505: \verb"PConnRequest" routine,
506: which corresponds to the {\sf P-CONNECT.RE\-QUEST\/} action.
507: \begin{quote}\index{PConnRequest}\small\begin{verbatim}
508: int PConnRequest (calling, called, ctxlist, defctxname,
509: prequirements, srequirements, isn, settings,
510: ref, data, ndata, qos, pc, pi)
511: struct PSAPaddr *calling,
512: *called;
513: int prequirements,
514: srequirements,
515: settings,
516: ndata;
517: long isn;
518: struct PSAPctxlist *ctxlist;
519: OID defctxname;
520: struct SSAPref *ref;
521: PE *data;
522: struct QOStype *qos;
523: struct PSAPconnect *pc;
524: struct PSAPindication *pi;
525: \end{verbatim}\end{quote}
526: The parameters to this procedure are:\label{PConnRequest}
527: \begin{describe}
528: \item[\verb"calling":] the PSAP address of the initiator
529: (use the manifest constant verb"NULLPA" if this is not unimportant);
530:
531: \item[\verb"called":] the PSAP address of the responder;
532:
533: \item[\verb"ctxlist":] the list of proposed presentation contexts
534: (only the \verb"pc_id", \verb"pc_asn", and optionally the \verb"pc_atn"
535: elements should be filled in);
536:
537: \item[\verb"defctxname":] the proposed default contexts;
538:
539: \item[\verb"prequirements":] the presentation requirements;
540:
541: \item[\verb"srequirements":] the session requirements;
542:
543: \item[\verb"isn":] the initial serial-number;
544:
545: \item[\verb"settings":] the initial token settings;
546:
547: \item[\verb"ref":] the connection identifier used by the initiator
548: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
549: structure);
550:
551: \item[\verb"data"/\verb"ndata":] an array of initial data
552: (and the number of elements in that array,
553: consult the warning on page~\pageref{PSAPdata});
554:
555: \item[\verb"qos":] the quality of service on the connection
556: (see Section~\ref{tsap:qos});
557:
558: \item[\verb"pc":] a pointer to a \verb"PSAPconnect" structure, which is
559: updated only if the call succeeds;
560: and,
561:
562: \item[\verb"pi":] a pointer to a \verb"PSAPindication" structure, which is
563: updated only if the call fails.
564: \end{describe}
565: If the call to \verb"PConnRequest" is successful
566: (a successful return corresponds to a {\sf P-CONNECT.CONFIRMATION\/} event),
567: then information is returned in the \verb"pc" parameter,
568: which is a pointer to a \verb"PSAPconnect" structure.
569: \begin{quote}\index{PSAPconnect}\small\begin{verbatim}
570: struct PSAPconnect {
571: int pc_sd;
572:
573: struct PSAPaddr pc_responding;
574:
575: struct PSAPctxlsit pc_ctxlist;
576:
577: int pc_defctxresult;
578:
579: int pc_prequirements;
580:
581: int pc_srequirements;
582: int pc_settings;
583: int pc_please;
584: long pc_isn;
585:
586: struct SSAPref pc_connect;
587:
588: int pc_ssdusize;
589:
590: struct QOStype pc_qos;
591: int pc_result;
592:
593: struct SSAPref pc_connect;
594:
595: #define PC_SIZE 512
596: int pc_cc;
597: char pc_data[PC_SIZE];
598: };
599: \end{verbatim}\end{quote}
600: The elements of this structure are:\label{PSAPconnect}
601: \begin{describe}
602: \item[\verb"pc\_sd":] the presentation-descriptor to be used to reference this
603: connection;
604:
605: \item[\verb"pc\_responding":] the responding peer's address
606: (which is the same as the \verb"called" parameter given to
607: \verb"SConnRequest");
608:
609: \item[\verb"pc\_ctxlist":] the (negotiated) list of presentation contexts;
610:
611: \item[\verb"pc\_defctxresult":] the response to the proposed default context;
612:
613: \item[\verb"pc\_prequirements":] the (negotiated) presentation requirements;
614:
615: \item[\verb"pc\_srequirements":] the (negotiated) session requirements;
616:
617: \item[\verb"pc\_settings":] the (negotiated) initial token settings;
618:
619: \item[\verb"pc\_please":] the tokens which the responder wants to own
620: (if any);
621:
622: \item[\verb"pc\_isn":] the (negotiated) initial serial-number;
623:
624: \item[\verb"pc\_connect":] the connection identifier used by the responder
625: (consult page~\pageref{SSAPref} for a description of the \verb"SSAPref"
626: structure);
627:
628: \item[\verb"pc\_ssdusize":] the largest atomic SSDU size that can be used on
629: the connection (see the note on page~\pageref{SSDU:atomic});
630:
631: \item[\verb"pc\_qos":] the quality of service on the connection
632: (see Section~\ref{tsap:qos});
633: and,
634:
635: \item[\verb"pc\_result":] the connection response;
636:
637: \item[\verb"pc\_info"/\verb"pc\_ninfo":] an array of initial data,
638: and the number of elements in that array.
639: \end{describe}
640: If the call to \verb"PConnRequest" is successful,
641: and the \verb"pc_result" element is set to \verb"PC_ACCEPT",
642: then connection establishment has completed and the users of the presentation
643: service now operate as symmetric peers.
644: If the call is successful,
645: but the \verb"pc_result" element is not \verb"PC_ACCEPT",
646: then the connection has been rejected;
647: consult Table~\ref{PSAPreasons} to determine the reason
648: (further information can be found in the \verb"pi" parameter).
649: Otherwise, if the call fails then the connection is not established and the
650: \verb"PSAPabort" structure of the \verb"PSAPindication" discriminated union
651: has been updated.
652:
653: Note that the \verb"pc_info" element is allocated via \man malloc(3) and
654: should be released using the \verb"PCFREE" macro when no longer referenced.
655: The \verb"PCFREE" macro behaves as if it was defined as:
656: \begin{quote}\index{PCFREE}\small\begin{verbatim}
657: void PCFREE (pc)
658: struct PSAPconnect *pc;
659: \end{verbatim}\end{quote}
660: The macro frees only the data allocated by \verb"PConnRequest",
661: and not the \verb"PSAPconnect" structure itself.
662: Further,
663: \verb"PCFREE" should be called only if the call to the \verb"PConnRequest"
664: routine returned \verb"OK".
665:
666: Normally \verb"PConnRequest" returns only after a connection has succeeded or
667: failed.
668: This is termed a {\em synchronous\/} connection initiation.
669: If the user desires, an {\em asynchronous\/} connection may be initiated.
670: The routine \verb"PConnRequest" is really a macro which calls the routine
671: \verb"PAsynConnRequest" with an argument indicating that a connection should
672: be attempted synchronously.
673: \begin{quote}\index{PAsynConnRequest}\small\begin{verbatim}
674: int PAsynConnRequest (calling, called, ctxlist,
675: defctxname, prequirements, srequirements,
676: isn, settings, ref, data, ndata, qos, pc,
677: pi, async)
678: struct PSAPaddr *calling,
679: *called;
680: int prequirements,
681: srequirements,
682: settings,
683: ndata,
684: async;
685: long isn;
686: struct PSAPctxlist *ctxlist;
687: OID defctxname;
688: struct SSAPref *ref;
689: PE *data;
690: struct QOStype *qos;
691: struct PSAPconnect *pc;
692: struct PSAPindication *pi;
693: \end{verbatim}\end{quote}
694: The additional parameter to this procedure is:
695: \begin{describe}
696: \item[\verb"async":] whether the connection should be initiated asynchronously.
697: \end{describe}
698: If the \verb"async" parameter is non-zero,
699: then \verb"PAsynConnRequest" returns one of four values:
700: \verb"NOTOK", which indicates that the connection request failed;
701: \verb"DONE", which indicates that the connection request succeeded;
702: or, either of \verb"CONNECTING_1" or \verb"CONNECTING_2", which indicates that
703: the connection request is still in
704: progress.
705: In the first two cases,
706: the usual procedures for handling return values from \verb"PConnRequest" are
707: employed
708: (i.e., a \verb"NOTOK" return from \verb"PAsynConnRequest" is equivalent to a
709: \verb"NOTOK" return from \verb"PConnRequest", and,
710: a \verb"DONE" return from \verb"PAsynConnRequest" is equivalent to a
711: \verb"OK" return from \verb"PConnRequest").
712:
713: In the final case, when either \verb"CONNECTING_1" or
714: \verb"CONNECTING_2" is returned,
715: only the \verb"pc_sd" element of the \verb"pc" parameter has been updated;
716: it reflects the presentation-descriptor to be used to reference this
717: connection.
718:
719: To determine when the connection attempt has been completed,
720: the routine \verb"xselect" (consult Section~\ref{acs:select} of \volone/)
721: should be used after calling \verb"PSelectMask".
722: In order to determine if the connection attempt was successful,
723: the routine \verb"PAsynRetryRequest" is called:
724: \begin{quote}\index{PAsynRetryRequest}\small\begin{verbatim}
725: int PAsynRetryRequest (sd, pc, pi)
726: int sd;
727: struct PSAPconnect *pc;
728: struct PSAPindication *pi;
729: \end{verbatim}\end{quote}
730: The parameters to this procedure are:
731: \begin{describe}
732: \item[\verb"sd":] the presentation-descriptor;
733:
734: \item[\verb"pc":] a pointer to a \verb"PSAPconnect" structure, which is
735: updated only if the call succeeds;
736: and,
737:
738: \item[\verb"pi":] a pointer to a \verb"PSAPindication" structure, which is
739: updated only if the call fails.
740: \end{describe}
741: Again, one of three values are returned:
742: \verb"NOTOK", which indicates that the connection request failed;
743: \verb"DONE", which indicates that the connection request succeeded;
744: and, \verb"CONNECTING_1" or \verb"CONNECTING_2" which indicates that
745: the connection request is still in progress.
746:
747: Refer to Section~\ref{tsap:async} on page~\pageref{tsap:async}
748: for information on how to make efficient use of the asynchronous connection
749: facility.
750:
751: \section {Data Transfer}
752: Once the connection has been established,
753: a presentation-descriptor is used to reference the connection.
754: This is usually the first parameter given to any of the remaining routines in
755: the \man libpsap2(3n) library.
756: Further,
757: the last parameter is usually a pointer to a \verb"PSAPindication" structure
758: (as described on page~\pageref{PSAPindication}).
759: If a call to one of these routines fails,
760: then the structure is updated.
761: Consult the \verb"PSAPabort" element of the \verb"PSAPindication" structure.
762: If the \verb"pa_reason" element of the \verb"PSAPabort" structure is
763: associated with a fatal error,
764: then the connection is closed.
765: That is, a {\sf P-P-ABORT.INDICATION\/} event has occurred.
766: The \verb"PC_FATAL" macro can be used to determine this.
767: \begin{quote}\index{PC\_FATAL}\small\begin{verbatim}
768: int PC_FATAL (r)
769: int r;
770: \end{verbatim}\end{quote}
771: The most common interface error to occur is \verb"PC_OPERATION" which usually
772: indicates that either the user is lacking ownership of a session token
773: to perform an operation,
774: or that a session requirement required by the operation was not negotiated
775: during connection establishment.
776: For protocol purists,
777: the \verb"PC_OFFICIAL" macro can be used to determine if the error is an
778: ``official'' error as defined by the specification,
779: or an ``unofficial'' error used by the implementation.
780: \begin{quote}\index{PC\_OFFICIAL}\small\begin{verbatim}
781: int PC_OFFICIAL (r)
782: int r;
783: \end{verbatim}\end{quote}
784:
785: All of the remaining routines in the \man libpsap2(3n) library are identical
786: to their counterparts in the \man libssap(3n) library,
787: with these exceptions:
788: \begin{itemize}
789: \item The final parameter to each routine is a pointer to a
790: \verb"PSAPindication" structure,
791: rather than a \verb"SSAPindication" structure.
792:
793: \item Any user data components are specified as an array of presentation
794: elements (and the number of elements in that array),
795: rather than the base of a character array (and the number of octets
796: to be sent.
797: Note that any data to be sent should have the \verb"pe_context"
798: element set to the desired presentation context.
799: By default, presentation elements are initialized with the
800: default context (as represented by the manifest constant
801: \verb"PE_DFLT_CTX").
802:
803: \item Asynchronous event handlers are called with pointers to \verb"PSAP"
804: structures, rather tha \verb"SSAP" structures.
805:
806: \item With any indication which occurs,
807: it is important to free any data which might have been allocated.
808: The structures and corresponding macros are:
809: \[\begin{tabular}{|l|l|}
810: \hline
811: \multicolumn{1}{|c|}{\bf Macro}&
812: \multicolumn{1}{c|}{\bf Structure Pointer}\\
813: \hline
814: \tt PXFREE& struct PSAPdata *\\
815: \tt PTFREE& struct PSAPtoken *\\
816: \tt PNFREE& struct PSAPsync *\\
817: \tt PVFREE& struct PSAPactivity *\\
818: \tt PPFREE& struct PSAPreport *\\
819: \tt PFFREE& struct PSAPfinish *\\
820: \tt PRFREE& struct PSAPrelease *\\
821: \tt PAFREE& struct PSAPabort *\\
822: \hline
823: \end{tabular}\]
824: Note that these free the user data referenced by the indication
825: structures,
826: and not the structures themselves.\index{PXFREE}\index{PTFREE}
827: \index{PNFREE}\index{PVFREE}\index{PPFREE}\index{PFFREE}\index{PRFREE}
828: \index{PAFREE}
829: \end{itemize}
830:
831: \subsection {Restrictions on User Data}\label{PSAPdata}
832: To quote the \cite{ISO.PP.Service} specification:
833: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
834: \bf NOTE:& For all services which carry user data,
835: excluding {\sf P-DATA\/} and {\sf P-TYPED-DATA},
836: it may not be possible to exchange user data,
837: dependent on the user data length limitation supported by
838: the underlying session services.
839: \end{tabular}}\]
840:
841: \section {Error Conventions}
842: All of the routines in this library return the manifest constant \verb"NOTOK"
843: on error,
844: and also update the \verb"pi" parameter given to the routine.
845: The \verb"pi_abort" element of the \verb"PSAPindication" structure contains a
846: \verb"PSAPabort" structure detailing the reason for the failure.
847: The \verb"pa_reason" element of this latter structure can be given as a
848: parameter to the routine \verb"PErrString" which returns a null-terminated
849: diagnostic string.
850: \begin{quote}\index{PErrString}\small\begin{verbatim}
851: char *PErrString (c)
852: int c;
853: \end{verbatim}\end{quote}
854:
855: \section {Compiling and Loading}
856: Programs using the \man libpsap2(3n) library should include
857: \verb"<isode/psap2.h>".
858: The programs should also be loaded with \verb"-lpsap2".
859:
860: \section {An Example}
861: Let's consider how one might construct a source entity that resides on the
862: PSAP.
863: This entity will use a synchronous interface.
864:
865: There are two parts to the program:
866: initialization and data transfer;
867: release will occur when the standard input has been exhausted.
868: In our example,
869: we assume that the routine \verb"error" results in the process being
870: terminated after printing a diagnostic.
871:
872: In Figure~\ref{initPSsource},
873: the initialization steps for the source entity,
874: including the outer {\em C\/} wrapper,
875: is shown.
876: First, a lookup is done in the ISO services database,
877: and the \verb"PSAPaddr" is initialized.
878: The \verb"SSAPref" is initialized using the routine
879: \verb"addr2ref".
880: This routine takes a string and returns a pointer to a \verb"SSAPref"
881: structure which has been initialized to contain the string and the current
882: UTC time.
883: Next, for each token associated with the session requirements,
884: initial ownership of that token is claimed.
885: Finally,
886: the call to \verb"PConnRequest" is made.
887: If the call is successful,
888: a check is made to see if the remote user accepted the connection.
889: If so,
890: the presentation-descriptor is captured,
891: along with the negotiated requirements and initial token settings.
892:
893: In Figure~\ref{dataPSsource} on page~\pageref{dataPSsource},
894: the data transfer loop is realized.
895: The source entity reads a line from the standard input,
896: and then queues that line for sending to the remote side.
897: When an end-of-file occurs on the standard input,
898: the source entity requests release and then gracefully terminates.
899: Although no checking is done in this example,
900: for the calls to \verb"PDataRequest" and \verb"PRelRequest",
901: on failure
902: a check for the operational error \verb"PC_OPERATION" should be made.
903: For \verb"PDataRequest",
904: this would occur when the data token was not owned by the user;
905: for \verb"PRelRequest",
906: this would occur when the release token was not owned by the user.
907: \clearpage
908: \tagrind[tp]{grind5a-2a}{Initializing the PSAP source entity}{initPSsource}
909: \clearpage
910: \tagrind[tp]{grind5a-2b}{Initializing the PSAP source entity (continued)}\empty
911: \clearpage
912: \tagrind[tp]{grind5a-3}{Data Transfer for the PSAP source entity}%
913: {dataPSsource}
914:
915: \section {Lightweight Presentation Protocol}
916: To run OSI applications using the lighweight presentation protocol
917: defined in RFC1085,
918: load the program with \verb"-lpsap2-lpp" or \verb"-isode-lpp".
919:
920: This is a complete implementation of RFC1085.
921: The following functions are available:
922: \begin{quote}\small\begin{verbatim}
923: PInit
924: PConnResponse
925: PAsynConnRequest
926: PAsynRetryRequest
927: PDataRequest
928: PReadRequest
929: PUAbortRequest
930: PRelRequest
931: PRelResponse
932: PSetIndications
933: PSelectMask
934: PErrSTring
935: \end{verbatim}\end{quote}
936: Note that when RFC1085 is used as a presentation backing,
937: only a subset of the presentation services are available:
938: \begin{quote}\small\sf
939: P-CONNECT
940: P-DATA
941: P-U-ABORT
942: P-P-ABORT
943: \end{quote}
944: The \man lppd(8c) daemon is used to listen for incoming connections and
945: dispatch the appropriate daemon.
946: This daemon will listen only for connections using the TCP backing.
947: For connections using the UDP backing,
948: the responder program must listen itself.
949: This is trivally accomplished using the \verb"isodeserver" routine
950: described in Section~\ref{isodeserver} on page~\pageref{isodeserver}.
951:
952: \section {For Further Reading}
953: The ISO specification for session services is defined in
954: \cite{ISO.PP.Service},
955: while the corresponding protocol definition is \cite{ISO.PP.Protocol}.
956:
957: %%% \section {Changes Since the Last Release}\label{psapX:changes}
958: %%% A brief summary of the major changes between v~\psapXrevrsn/ and
959: %%% v~\psapXvrsn/ are now presented.
960: %%% These are the user-visible changes only;
961: %%% changes of a strictly internal nature are not discussed.
962:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.