Return to entities.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {The ISODE Entities Database}\label{isoentities}
        !             4: The database \file{isoentities} in the ISODE \verb"ETCDIR" directory
        !             5: (usually \file{/usr/etc/})
        !             6: contains a simple mapping between
        !             7: appli\-cat\-ion-entity information and presentation addresses.
        !             8: This database is used by the stub-directory service.
        !             9: 
        !            10: The database itself is an ordinary ASCII text file containing information
        !            11: regarding the known ap\-pli\-ca\-tion-entities on the network.
        !            12: Each entry contains:
        !            13: \begin{itemize}
        !            14: \item  the object descriptor of the application-entity information,
        !            15:        realized as a designator-qualifier (host/service) pair
        !            16:        (the distinguished designator \verb"default" is used for a template
        !            17:        entry);
        !            18: 
        !            19: \item  the object identifier of the application-entity information
        !            20:        expressed in dot-notation
        !            21:        (if no application-entity information is desired,
        !            22:        the string ``NULL'' should be used instead);
        !            23:        and,
        !            24: 
        !            25: \item  the presentation address expressed in the string format described
        !            26:        in Section~\ref{addr:encodings} on page~\pageref{addr:encodings} in
        !            27:        \volone/.
        !            28: 
        !            29:        Note that since double-quotes are often used in the new string format,
        !            30:        it is {\bf very\/} important to quote them correctly in the 
        !            31:        \man isoentities(5) file.
        !            32:        Usually preceeding the first character of the address with backslash
        !            33:        (``\verb"\"'') is adequate.
        !            34: \end{itemize}
        !            35: Blanks and/or tab characters are used to seperate items.
        !            36: However, double-quotes may be used to prevent separation for items containing
        !            37: embedded whitspace.
        !            38: This is useful for defining the presetnation address.
        !            39: The sharp character (`\verb"#"') at the beginning of a line indicates a
        !            40: commentary line.
        !            41: 
        !            42: It is suggested for readability purposes that a blank line should seperate
        !            43: entries. 
        !            44: 
        !            45: \subsection*   {RFC1085 Support}
        !            46: Since applications using RFC1085 (the lightweight presentation protocol)
        !            47: usually demultiplex on the basis of TCP or UDP port,
        !            48: a further definition for the qualifier is placed in
        !            49: \file{/etc/services},
        !            50: one of:
        !            51: \begin{quote}\small\begin{verbatim}
        !            52: qualifier    portno/lpp
        !            53: qualifier    portno/tcp
        !            54: qualifier    portno/udp
        !            55: \end{verbatim}\end{quote}
        !            56: The first alternative says that the service lives on both TCP and UDP;
        !            57: the second alternative says that the service lives on TCP only;
        !            58: and,
        !            59: the third alternative says that the service lives on UDP only.
        !            60: 
        !            61: \section      {Accessing the Database}\label{isoentity}
        !            62: The \man libacsap(3n) library contains the routines used to access the
        !            63: database.
        !            64: The high-level routines, \verb"_str2aei",
        !            65: which returns application-entity information,
        !            66: and \verb"aei2addr",
        !            67: which maps the ap\-pli\-ca\-tion-entity information into a presentation
        !            68: address have
        !            69: already been discussed in Section~\ref{acs:aei}.
        !            70: Similarly, the ``old-style'' routines,
        !            71: \verb"is2paddr", \verb"is2saddr", \verb"is2taddr",
        !            72: which maps a host and service directly into a prsentation, session,
        !            73: or transport address (respectively) are discussed in
        !            74: Sections~\ref{psap:addresses}, \ref{ssap:addresses}, and~\ref{tsap:addresses}
        !            75: of \voltwo/ (respectively).
        !            76: Hence, for the remainder of this chapter,
        !            77: we need only consider the internal form used by the library in querying the
        !            78: database.
        !            79: 
        !            80: The \verb"isoentity" structure is the internal form.
        !            81: \begin{quote}\index{isoentity}\small\begin{verbatim}
        !            82: struct isoentity {
        !            83:     OIDentifier ie_identifier;
        !            84:     char    *ie_descriptor;
        !            85: 
        !            86:     struct PSAPaddr ie_addr;
        !            87: };
        !            88: \end{verbatim}\end{quote}
        !            89: The elements of this structure are:
        !            90: \begin{describe}
        !            91: \item[\verb"ie\_identifier":] an object identifier used to form
        !            92: application-entity information;
        !            93: 
        !            94: \item[\verb"ie\_identifier":] the corresponding object descriptor;
        !            95: and,
        !            96: 
        !            97: \item[\verb"ie\_addr":] the presentation address.
        !            98: \end{describe}
        !            99: 
        !           100: The routine \verb"getisoentity" reads the next entry in the database,
        !           101: opening the database if necessary.
        !           102: \begin{quote}\index{getisoentity}\small\begin{verbatim}
        !           103: struct isoentity *getisoentity ()
        !           104: \end{verbatim}\end{quote}
        !           105: It returns the manifest constant \verb"NULL" on error or end-of-file.
        !           106: 
        !           107: The routine \verb"setisoentity" opens and rewinds the database.
        !           108: \begin{quote}\index{setisoentity}\small\begin{verbatim}
        !           109: int     setisoentity (f)
        !           110: int     f;
        !           111: \end{verbatim}\end{quote}
        !           112: The parameter to this procedure is:
        !           113: \begin{describe}
        !           114: \item[\verb"f":] the ``stayopen'' indicator,
        !           115: if non-zero, then the database will remain open over subsequent calls to the
        !           116: library.
        !           117: \end{describe}
        !           118: The routine \verb"endisoentity" closes the database.
        !           119: \begin{quote}\index{endisoentity}\small\begin{verbatim}
        !           120: int     endisoentity ()
        !           121: \end{verbatim}\end{quote}
        !           122: Both of these routines return non-zero on success and zero otherwise.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.