Return to psap2.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/psap2.tex, revision 1.1

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.