doc/introduction.xml

   1 <!-- $Id: introduction.xml,v 1.8 2002-08-17 07:55:51 adam Exp $ -->
   2  <chapter id="introduction"><title>Introduction</title>
   3
   4   <para>
   5    The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
   6    toolkit offers several different levels of access to the
   7    <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>
   8    and <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> protocols.
   9    The level that you need to use depends on your requirements, and
  10    the role (server or client) that you want to implement.
  11    If you're developing a client application you should consider the
  12    <link linkend="zoom">ZOOM</link> API.
  13    It is, by far, the easiest way to develop clients in C.
  14    Server implementers should consider the
  15    <link linkend="server">generic frontend server</link>.
  16    None of those high-level APIs support the whole protocol, but
  17    they do include most facilities used in existing Z39.50
  18    applications.
  19   </para>
  20   <para>
  21    If you're using 'exotic' functionality (meaning anything not included in
  22    the high-level APIs), developing non-standard extensions to Z39.50 or you're
  23    going to develop an ILL application you'll have to learn the lower
  24    level APIs of &yaz;.
  25   </para>
  26   <para>
  27    The basic low level modules, which are independent of the role
  28    (client or server), consist of three primary interfaces:
  29
  30    <itemizedlist>
  31     <listitem><para>&asn;, which provides a C representation of the Z39.50
  32       protocol packages (PDUs).
  33      </para></listitem>
  34     <listitem><para>&odr;, which encodes and decodes the packages according
  35       to the BER specification.
  36      </para></listitem>
  37     <listitem><para>&comstack;, which exchanges the encoded packages with
  38       a peer process over a network.
  39      </para></listitem>
  40    </itemizedlist>
  41
  42    The &asn; module represents the ASN.1 definition of
  43    the Z39.50 protocol. It establishes a set of type and
  44    structure definitions, with one structure for each of the top-level
  45    PDUs, and one structure or type for each of the contained ASN.1 types.
  46    For primitive types, or other types that are defined by the ASN.1
  47    standard itself (such as the EXTERNAL type), the C representation is
  48    provided by the &odr; (Open Data Representation) subsystem.
  49   </para>
  50   <para>
  51     &odr; is a basic mechanism for representing an
  52    ASN.1 type in the C programming language, and for implementing BER
  53    encoders and decoders for values of that type. The types defined in
  54    the &asn; module generally have the prefix <literal>Z_</literal>, and
  55    a suffix corresponding to the name of the type in the ASN.1
  56    specification of the protocol (generally Z39.50-1995). In the case of
  57    base types (those originating in the ASN.1 standard itself), the prefix
  58    <literal>Odr_</literal> is sometimes seen. Either way, look for
  59    the actual definition in either <filename>z-core.h</filename> (for the types
  60    from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
  61    types).
  62    The &asn; library also provides functions (which are, in turn,
  63    defined using &odr; primitives) for encoding and decoding data values.
  64    Their general form is
  65
  66    <funcsynopsis>
  67     <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
  68      <paramdef>ODR <parameter>o</parameter></paramdef>
  69      <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
  70      <paramdef>int <parameter>optional</parameter></paramdef>
  71      <paramdef>const char *<parameter>name</parameter></paramdef>
  72     </funcprototype>
  73    </funcsynopsis>
  74    (note the lower-case &quot;z&quot; in the function name)
  75   </para>
  76
  77   <note>
  78    <para>
  79     If you are using the premade definitions of the &asn; module, and you
  80     are not adding new protocol of your own, the only parts of &odr; that you
  81     need to worry about are documented in section
  82     <link linkend="odr-use">Using ODR</link>.
  83    </para>
  84   </note>
  85
  86   <para>
  87    When you have created a BER-encoded buffer, you can use the &comstack;
  88    subsystem to transmit (or receive) data over the network. The &comstack;
  89    module provides simple functions for establishing a connection
  90    (passively or actively, depending on the role of your application),
  91    and for exchanging BER-encoded PDUs over that connection. When you
  92    create a connection endpoint, you need to specify what transport to
  93    use (TCP/IP, SSL or UNIX sockets).
  94    For the remainder of the connection's lifetime, you don't have
  95    to worry about the underlying transport protocol at all - the &comstack;
  96    will ensure that the correct mechanism is used.
  97   </para>
  98   <para>
  99    We call the combined interfaces to &odr;, &asn;, and &comstack; the service
 100    level API. It's the API that most closely models the Z39.50
 101    service/protocol definition, and it provides unlimited access to all
 102    fields and facilities of the protocol definitions.
 103   </para>
 104   <para>
 105    The reason that the &yaz; service-level API is a conglomerate of the
 106    APIs from three different submodules is twofold. First, we wanted to allow
 107    the user a choice of different options for each major task. For instance,
 108    if you don't like the protocol API provided by &odr;/&asn;, you
 109    can use SNACC or BERUtils instead, and still have the benefits of the
 110    transparent transport approach of the &comstack; module. Secondly,
 111    we realize that you may have to fit the toolkit into an existing
 112    event-processing structure, in a way that is incompatible with
 113    the &comstack; interface or some other part of &yaz;.
 114   </para>
 115  </chapter>
 116
 117  <!-- Keep this comment at the end of the file
 118  Local variables:
 119  mode: sgml
 120  sgml-omittag:t
 121  sgml-shorttag:t
 122  sgml-minimize-attributes:nil
 123  sgml-always-quote-attributes:t
 124  sgml-indent-step:1
 125  sgml-indent-data:t
 126  sgml-parent-document:"yaz.xml"
 127  sgml-local-catalogs: nil
 128  sgml-namecase-general:t
 129  End:
 130  -->