File: introduction.api.html

package info (click to toggle)
yaz 3.0.34-2
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,404 kB
  • ctags: 12,108
  • sloc: xml: 116,075; ansic: 52,205; sh: 9,746; tcl: 2,043; makefile: 1,141; yacc: 347
file content (98 lines) | stat: -rw-r--r-- 9,234 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.�The API</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="introduction.html" title="Chapter�1.�Introduction"><link rel="prev" href="introduction.html" title="Chapter�1.�Introduction"><link rel="next" href="installation.html" title="Chapter�2.�Compilation and Installation"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.�The API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a>�</td><th width="60%" align="center">Chapter�1.�Introduction</th><td width="20%" align="right">�<a accesskey="n" href="installation.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction.api"></a>2.�The API</h2></div></div></div><p>
    The <a class="ulink" href="http://www.indexdata.com/yaz/" target="_top">YAZ</a>
    toolkit offers several different levels of access to the
    <a class="ulink" href="http://www.loc.gov/z3950/agency/" target="_top">ISO23950/Z39.50</a>,
    <a class="ulink" href="http://www.nlc-bnc.ca/iso/ill/" target="_top">ILL</a> and
    <a class="ulink" href="http://www.loc.gov/standards/sru/" target="_top">SRU</a>
    protocols.
    The level that you need to use depends on your requirements, and
    the role (server or client) that you want to implement.
    If you're developing a client application you should consider the
    <a class="link" href="zoom.html" title="Chapter�3.�ZOOM">ZOOM</a> API.
    It is, by far, the easiest way to develop clients in C.
    Server implementers should consider the 
    <a class="link" href="server.html" title="Chapter�4.�Generic server">generic frontend server</a>.
    None of those high-level APIs support the whole protocol, but
    they do include most facilities used in existing Z39.50 applications.
   </p><p>
    If you're using 'exotic' functionality (meaning anything not included in
    the high-level APIs), developing non-standard extensions to Z39.50 or
    you're going to develop an ILL application you'll have to learn the lower
    level APIs of YAZ.
   </p><p>
    The YAZ toolkit modules is shown in figure <a class="xref" href="introduction.api.html#yaz.layer" title="Figure�1.1.�YAZ layers">Figure�1.1, &#8220;YAZ layers&#8221;</a>.
   </p><div class="figure"><a name="yaz.layer"></a><p class="title"><b>Figure�1.1.�YAZ layers</b></p><div class="figure-contents"><div class="mediaobject"><img src="apilayer.png" alt="YAZ layers"></div></div></div><br class="figure-break"><p>
    There are four layers.
    </p><div class="itemizedlist"><ul type="disc"><li><p>A client or server application (or both).
       This layer includes ZOOM and the generic frontend server.
      </p></li><li><p>
       The second layer provides a C represenation of the 
       protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
       SRU.
      </p></li><li><p>
       The third layer encodes and decodes protocol data units to
       simple packages (buffer with certain length). The <acronym class="acronym">ODR</acronym> module
       encodes and decodes BER whereas the HTTP modules encodes and
       decodes HTTP ruquests/responses.
      </p></li><li><p>
       The lowest layer is <acronym class="acronym">COMSTACK</acronym> which exchanges the encoded packages
       with a peer process over a network.
      </p></li></ul></div><p>
   </p><p>
    The Z39.50 ASN.1 module represents the ASN.1 definition of
    the Z39.50 protocol. It establishes a set of type and
    structure definitions, with one structure for each of the top-level
    PDUs, and one structure or type for each of the contained ASN.1 types.
    For primitive types, or other types that are defined by the ASN.1
    standard itself (such as the EXTERNAL type), the C representation is
    provided by the <acronym class="acronym">ODR</acronym> (Open Data Representation) subsystem.
  </p><p>
     <acronym class="acronym">ODR</acronym> is a basic mechanism for representing an
    ASN.1 type in the C programming language, and for implementing BER
    encoders and decoders for values of that type. The types defined in
    the Z39.50 ASN.1 module generally have the prefix <code class="literal">Z_</code>, and
    a suffix corresponding to the name of the type in the ASN.1
    specification of the protocol (generally Z39.50-1995). In the case of
    base types (those originating in the ASN.1 standard itself), the prefix
    <code class="literal">Odr_</code> is sometimes seen. Either way, look for
    the actual definition in either <code class="filename">z-core.h</code> (for the types
    from the protocol), <code class="filename">odr.h</code> (for the primitive ASN.1
    types).
    The Z39.50 ASN.1 library also provides functions (which are, in turn,
    defined using <acronym class="acronym">ODR</acronym> primitives) for encoding and decoding data values.
    Their general form is
    
    </p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr><td><code class="funcdef">int <b class="fsfunc">z_xxx</b>(</code></td><td><var class="pdparam">o</var>, </td><td>�</td></tr><tr><td>�</td><td><var class="pdparam">p</var>, </td><td>�</td></tr><tr><td>�</td><td><var class="pdparam">optional</var>, </td><td>�</td></tr><tr><td>�</td><td><var class="pdparam">name</var><code>)</code>;</td><td>�</td></tr></table><table border="0" summary="Function argument synopsis" cellspacing="0" cellpadding="0"><tr><td><code>ODR </code>�</td><td><code><var class="pdparam">o</var>;</code></td></tr><tr><td><code>Z_xxx **</code>�</td><td><code><var class="pdparam">p</var>;</code></td></tr><tr><td><code>int </code>�</td><td><code><var class="pdparam">optional</var>;</code></td></tr><tr><td><code>const char *</code>�</td><td><code><var class="pdparam">name</var>;</code></td></tr></table></div><p>
    (note the lower-case "z" in the function name)
   </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
     If you are using the premade definitions of the Z39.50 ASN.1 module, and you
     are not adding new protocol of your own, the only parts of <acronym class="acronym">ODR</acronym> that you
     need to worry about are documented in
     <a class="xref" href="odr.use.html" title="2.�Using ODR">Section�2, &#8220;Using ODR&#8221;</a>.
    </p></div><p>
    When you have created a BER-encoded buffer, you can use the <acronym class="acronym">COMSTACK</acronym>
    subsystem to transmit (or receive) data over the network. The <acronym class="acronym">COMSTACK</acronym>
    module provides simple functions for establishing a connection
    (passively or actively, depending on the role of your application),
    and for exchanging BER-encoded PDUs over that connection. When you
    create a connection endpoint, you need to specify what transport to
    use (TCP/IP, SSL or UNIX sockets).
    For the remainder of the connection's lifetime, you don't have
    to worry about the underlying transport protocol at all - the <acronym class="acronym">COMSTACK</acronym>
    will ensure that the correct mechanism is used.
   </p><p>
    We call the combined interfaces to <acronym class="acronym">ODR</acronym>, Z39.50 ASN.1, and <acronym class="acronym">COMSTACK</acronym> the service
    level API. It's the API that most closely models the Z39.50
   service/protocol definition, and it provides unlimited access to all
    fields and facilities of the protocol definitions.
   </p><p>
    The reason that the YAZ service-level API is a conglomerate of the
    APIs from three different submodules is twofold. First, we wanted to allow
    the user a choice of different options for each major task. For instance,
    if you don't like the protocol API provided by <acronym class="acronym">ODR</acronym>/Z39.50 ASN.1, you
    can use SNACC or BERUtils instead, and still have the benefits of the
    transparent transport approach of the <acronym class="acronym">COMSTACK</acronym> module. Secondly,
    we realize that you may have to fit the toolkit into an existing
    event-processing structure, in a way that is incompatible with
    the <acronym class="acronym">COMSTACK</acronym> interface or some other part of YAZ.
   </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="introduction.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="installation.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�1.�Introduction�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�2.�Compilation and Installation</td></tr></table></div></body></html>