Use ZOOM_API(int) for public function ZOOM_connection_is_idle

[yaz-moved-to-github.git] / doc / odr.xml

diff --git a/doc/odr.xml b/doc/odr.xml
index 9a7e8c6..38d300e 100644 (file)
--- a/doc/odr.xml
+++ b/doc/odr.xml
@@ -1,4 +1,4 @@
-<!-- $Id: odr.xml,v 1.10 2003-11-03 10:45:05 adam Exp $ -->
+<!-- $Id: odr.xml,v 1.19 2006-10-05 08:26:58 adam Exp $ -->

  <chapter id="odr"><title>The ODR Module</title>
   
   <sect1 id="odr.introduction"><title>Introduction</title>
  <chapter id="odr"><title>The ODR Module</title>
   
   <sect1 id="odr.introduction"><title>Introduction</title>

@@ -13,19 +13,19 @@
    <para>
     If you are only interested in writing a Z39.50 implementation based on
     the PDUs that are already provided with &yaz;, you only need to concern
    <para>
     If you are only interested in writing a Z39.50 implementation based on
     the PDUs that are already provided with &yaz;, you only need to concern

-    yourself with the section on managing ODR streams (section
-    <link linkend="odr-use">Using ODR</link>). Only if you need to
+    yourself with the section on managing ODR streams
+    (<xref linkend="odr.use"/>). Only if you need to

     implement ASN.1 beyond that which has been provided, should you
     worry about the second half of the documentation
     implement ASN.1 beyond that which has been provided, should you
     worry about the second half of the documentation

-    (section <link linkend="odr-prog">Programming with ODR</link>).
+    (<xref linkend="odr.programming"/>).

     If you use one of the higher-level interfaces, you can skip this
     section entirely.
    </para>
 
    <para>
     This is important, so we'll repeat it for emphasis: <emphasis>You do
     If you use one of the higher-level interfaces, you can skip this
     section entirely.
    </para>
 
    <para>
     This is important, so we'll repeat it for emphasis: <emphasis>You do

-    not need to read section <link linkend="odr-prog">Programming with
-    ODR</link> to implement Z39.50 with &yaz;.</emphasis>
+     not need to read <xref linkend="odr.programming"/>
+     to implement Z39.50 with &yaz;.</emphasis>

    </para>
 
    <para>
    </para>
 
    <para>

@@ -37,9 +37,9 @@
    </para>
 
   </sect1>
    </para>
 
   </sect1>

-  <sect1 id="odr.use"><title id="odr-use">Using ODR</title>
+  <sect1 id="odr.use"><title>Using ODR</title>

 
 

-   <sect2><title>ODR Streams</title>
+   <sect2 id="odr.streams"><title>ODR Streams</title>

 
     <para>
      Conceptually, the ODR stream is the source of encoded data in the
 
     <para>
      Conceptually, the ODR stream is the source of encoded data in the

@@ -74,7 +74,7 @@
     </para>
    </sect2>
 
     </para>
    </sect2>
 

-   <sect2><title id="memory">Memory Management</title>
+   <sect2 id="odr.memory.management"><title id="memory">Memory Management</title>

 
     <para>
      Two forms of memory management take place in the &odr; system. The first
 
     <para>
      Two forms of memory management take place in the &odr; system. The first

@@ -169,7 +169,7 @@
     </para>
 
    </sect2>
     </para>
 
    </sect2>

-   <sect2><title>Encoding and Decoding Data</title>
+   <sect2 id="odr.encoding.and.decoding"><title>Encoding and Decoding Data</title>

 
     <para>
      When encoding data, the ODR stream will write the encoded octet string
 
     <para>
      When encoding data, the ODR stream will write the encoded octet string

@@ -260,7 +260,8 @@
      <function>z_APDU()</function>).
     </para>
     
      <function>z_APDU()</function>).
     </para>
     

-    <example><title>Encoding and decoding functions</title>
+    <example id="example.odr.encoding.and.decoding.functions">
+     <title>Encoding and decoding functions</title>

      <synopsis>
       int odr_integer(ODR o, int **p, int optional, const char *name);
       
      <synopsis>
       int odr_integer(ODR o, int **p, int optional, const char *name);
       

@@ -298,7 +299,8 @@
      last call to <function>odr_reset()</function> will be released.
     </para>
 
      last call to <function>odr_reset()</function> will be released.
     </para>
 

-    <example><title>Encoding and decoding of an integer</title>
+    <example id="example.odr.encoding.of.integer">
+     <title>Encoding and decoding of an integer</title>

      <para>
       The use of the double indirection can be a little confusing at first
       (its purpose will become clear later on, hopefully),
      <para>
       The use of the double indirection can be a little confusing at first
       (its purpose will become clear later on, hopefully),

@@ -355,7 +357,58 @@ void do_nothing_useful(int value)
     
    </sect2>
 
     
    </sect2>
 

-   <sect2><title>Diagnostics</title>
+   <sect2 id="odr.printing"><title>Printing</title>
+    <para>
+     When an ODR stream is created of type <literal>ODR_PRINT</literal>
+     the ODR module will print the contents of a PDU in a readable format.
+     By default output is written to the <literal>stderr</literal> stream.
+     This behavior can be changed, however, by calling the function
+     <synopsis>
+      odr_setprint(ODR o, FILE *file);
+     </synopsis>
+     before encoders or decoders are being invoked.
+     It is also possible to direct the output to a buffer (of indeed
+     another file), by using the more generic mechanism:
+     <synopsis>
+      void odr_set_stream(ODR o, void *handle,
+                         void (*stream_write)(ODR o, void *handle, int type,
+                                              const char *buf, int len),
+                         void (*stream_close)(void *handle));
+     </synopsis>
+     Here the user provides an opaque handle and two handlers,
+     <replaceable>stream_write</replaceable> for writing,
+     and <replaceable>stream_close</replaceable> which is supposed
+     to close/free resources associated with handle. 
+     The <replaceable>stream_close</replaceable> handler is optional and
+     if NULL for the function is provided, it will not be invoked.
+     The <replaceable>stream_write</replaceable> takes the ODR handle
+     as parameter, the user defined handle, a type 
+     <literal>ODR_OCTETSTRING</literal>, <literal>ODR_VISIBLESTRING</literal>
+     which indicates the type of contents is being written.
+    </para>
+    <para>
+     Another utility useful for diagnostics (error handling) or as
+     part of the printing facilities is:
+     <synopsis>
+      const char **odr_get_element_path(ODR o);
+     </synopsis>
+     which returns a list of current elements that ODR deals with at the 
+     moment. For the returned array, say <literal>ar</literal>, 
+     <literal>ar[0]</literal> is the top level element,
+     <literal>ar[n]</literal> is the last. The last element has the
+     property that <literal>ar[n+1] == NULL</literal>.
+    </para>
+    <example id="example.odr.element.path.record">
+     <title>Element Path for record</title>
+     <para>
+      For a database record part of a PresentResponse the
+      array returned by <function>odr_get_element</function>
+      is <literal>presentResponse</literal>, <literal>databaseOrSurDiagnostics</literal>, <literal>?</literal>, <literal>record</literal>, <literal>?</literal>, <literal>databaseRecord</literal> . The question mark appears due to 
+      unnamed constructions.
+     </para>
+     </example>
+   </sect2>
+   <sect2 id="odr.diagnostics"><title>Diagnostics</title>

 
     <para>
      The encoding/decoding functions all return 0 when an error occurs.
 
     <para>
      The encoding/decoding functions all return 0 when an error occurs.

@@ -389,7 +442,8 @@ void do_nothing_useful(int value)
      one of these constants:
     </para>
 
      one of these constants:
     </para>
 

-    <table frame="top"><title>ODR Error codes</title>
+    <table frame="top" id="odr.error.codes">
+     <title>ODR Error codes</title>

      <tgroup cols="2">
       <thead>
        <row>
      <tgroup cols="2">
       <thead>
        <row>

@@ -447,7 +501,8 @@ void do_nothing_useful(int value)
     </para>
 
    </sect2>
     </para>
 
    </sect2>

-   <sect2><title>Summary and Synopsis</title>
+   <sect2 id="odr.summary.and.synopsis">
+    <title>Summary and Synopsis</title>

 
     <synopsis>
      #include &lt;odr.h>
 
     <synopsis>
      #include &lt;odr.h>

@@ -478,7 +533,7 @@ void do_nothing_useful(int value)
    </sect2>
   </sect1>
 
    </sect2>
   </sect1>
 

-  <sect1 id="odr.programming"><title id="odr-prog">Programming with ODR</title>
+  <sect1 id="odr.programming"><title>Programming with ODR</title>

 
    <para>
     The API of &odr; is designed to reflect the structure of ASN.1, rather
 
    <para>
     The API of &odr; is designed to reflect the structure of ASN.1, rather

@@ -489,9 +544,9 @@ void do_nothing_useful(int value)
    <tip>
     <para>
      There is an ASN.1 tutorial available at
    <tip>
     <para>
      There is an ASN.1 tutorial available at

-     <ulink url="http://asn1.elibel.tm.fr/en/introduction/">this site</ulink>.
+     <ulink url="&url.asn.1.tutorial;">this site</ulink>.

      This site also has standards for ASN.1 (X.680) and BER (X.690) 
      This site also has standards for ASN.1 (X.680) and BER (X.690) 

-     <ulink url="http://asn1.elibel.tm.fr/en/standards/">online</ulink>.
+     <ulink url="&url.asn.1.standards;">online</ulink>.

     </para>
    </tip>
    
     </para>
    </tip>
    

@@ -517,14 +572,15 @@ void do_nothing_useful(int value)
     SEQUENCE members which don't exist in XDR.
    </para>
 
     SEQUENCE members which don't exist in XDR.
    </para>
 

-   <sect2><title>The Primitive ASN.1 Types</title>
+   <sect2 id="odr.primitive.asn1.types">
+    <title>The Primitive ASN.1 Types</title>

 
     <para>
      ASN.1 defines a number of primitive types (many of which correspond
      roughly to primitive types in structured programming languages, such as C).
     </para>
 
 
     <para>
      ASN.1 defines a number of primitive types (many of which correspond
      roughly to primitive types in structured programming languages, such as C).
     </para>
 

-    <sect3><title>INTEGER</title>
+    <sect3 id="odr.integer"><title>INTEGER</title>

 
      <para>
       The &odr; function for encoding or decoding (or printing) the ASN.1
 
      <para>
       The &odr; function for encoding or decoding (or printing) the ASN.1

@@ -582,21 +638,21 @@ void do_nothing_useful(int value)
       similar manners:
      </para>
     </sect3>
       similar manners:
      </para>
     </sect3>

-    <sect3><title>BOOLEAN</title>
+    <sect3 id="odr.boolean"><title>BOOLEAN</title>

 
      <synopsis>
 int odr_bool(ODR o, bool_t **p, int optional, const char *name);
      </synopsis>
 
     </sect3>
 
      <synopsis>
 int odr_bool(ODR o, bool_t **p, int optional, const char *name);
      </synopsis>
 
     </sect3>

-    <sect3><title>REAL</title>
+    <sect3 id="odr.real"><title>REAL</title>

 
      <para>
       Not defined.
      </para>
 
     </sect3>
 
      <para>
       Not defined.
      </para>
 
     </sect3>

-    <sect3><title>NULL</title>
+    <sect3 id="odr.null"><title>NULL</title>

 
      <synopsis>
 int odr_null(ODR o, bool_t **p, int optional, const char *name);
 
      <synopsis>
 int odr_null(ODR o, bool_t **p, int optional, const char *name);

@@ -609,7 +665,7 @@ int odr_null(ODR o, bool_t **p, int optional, const char *name);
      </para>
 
     </sect3>
      </para>
 
     </sect3>

-    <sect3><title>OCTET STRING</title>
+    <sect3 id="odr.octet.string"><title>OCTET STRING</title>

 
      <synopsis>
 typedef struct odr_oct
 
      <synopsis>
 typedef struct odr_oct

@@ -656,7 +712,7 @@ int odr_visiblestring(ODR o, char **p, int optional,
      </synopsis>
 
     </sect3>
      </synopsis>
 
     </sect3>

-    <sect3><title>BIT STRING</title>
+    <sect3 id="odr.bit.string"><title>BIT STRING</title>

 
      <synopsis>
 int odr_bitstring(ODR o, Odr_bitmask **p, int optional,
 
      <synopsis>
 int odr_bitstring(ODR o, Odr_bitmask **p, int optional,

@@ -694,7 +750,7 @@ int ODR_MASK_GET(Odr_bitmask *b, int bitno);
      </para>
     </sect3>
 
      </para>
     </sect3>
 

-    <sect3><title>OBJECT IDENTIFIER</title>
+    <sect3 id="odr.object.identifier"><title>OBJECT IDENTIFIER</title>

 
      <synopsis>
 int odr_oid(ODR o, Odr_oid **p, int optional, const char *name);
 
      <synopsis>
 int odr_oid(ODR o, Odr_oid **p, int optional, const char *name);

@@ -704,14 +760,14 @@ int odr_oid(ODR o, Odr_oid **p, int optional, const char *name);
       The C OID representation is simply an array of integers, terminated by
       the value -1 (the <literal>Odr_oid</literal> type is synonymous with
       the <literal>int</literal> type).
       The C OID representation is simply an array of integers, terminated by
       the value -1 (the <literal>Odr_oid</literal> type is synonymous with
       the <literal>int</literal> type).

-      We suggest that you use the OID database module (see section
-      <link linkend="oid">Object Identifiers</link>) to handle object identifiers
+      We suggest that you use the OID database module (see
+      <xref linkend="asn.oid"/>) to handle object identifiers

       in your application.
      </para>
 
     </sect3>
    </sect2>
       in your application.
      </para>
 
     </sect3>
    </sect2>

-   <sect2><title id="tag-prim">Tagging Primitive Types</title>
+   <sect2 id="odr.tagging.primitive.types"><title>Tagging Primitive Types</title> <!-- tag.prim -->

 
     <para>
      The simplest way of tagging a type is to use the
 
     <para>
      The simplest way of tagging a type is to use the

@@ -762,7 +818,7 @@ int myInt(ODR o, int **p, int optional, const char *name)
     </para>
 
    </sect2>
     </para>
 
    </sect2>

-   <sect2><title>Constructed Types</title>
+   <sect2 id="odr.constructed.types"><title>Constructed Types</title>

 
     <para>
      Constructed types are created by combining primitive types. The
 
     <para>
      Constructed types are created by combining primitive types. The

@@ -849,17 +905,18 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name)
     </para>
 
    </sect2>
     </para>
 
    </sect2>

-   <sect2><title>Tagging Constructed Types</title>
+   <sect2 id="odr.tagging.constructed.types">
+    <title>Tagging Constructed Types</title>

 
     <note>
      <para>
 
     <note>
      <para>

-      See section <link linkend="tag-prim">Tagging Primitive types</link>
-      for information on how to tag the primitive types, as well as types
-      that are already defined.
+      See <xref linkend="odr.tagging.primitive.types"/> for information on how to tag
+      the primitive types, as well as types that are already defined.

      </para>
     </note>
 
      </para>
     </note>
 

-    <sect3><title>Implicit Tagging</title>
+    <sect3 id="odr.implicit.tagging">
+     <title>Implicit Tagging</title>

 
      <para>
       Assume the type above had been defined as
 
      <para>
       Assume the type above had been defined as

@@ -907,7 +964,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name)
      </para>
     </sect3>
 
      </para>
     </sect3>
 

-    <sect3><title>Explicit Tagging</title>
+    <sect3 id="odr.explicit.tagging"><title>Explicit Tagging</title>

 
      <para>
       Explicit tagging of constructed types is a little more complicated,
 
      <para>
       Explicit tagging of constructed types is a little more complicated,

@@ -982,7 +1039,7 @@ int mySequence(ODR o, MySequence **p, int optional, const char *name)
 
     </sect3>
    </sect2>
 
     </sect3>
    </sect2>

-   <sect2><title>SEQUENCE OF</title>
+   <sect2 id="odr.sequence.of"><title>SEQUENCE OF</title>

 
     <para>
      To handle sequences (arrays) of a specific type, the function
 
     <para>
      To handle sequences (arrays) of a specific type, the function

@@ -1038,7 +1095,7 @@ int myArray(ODR o, MyArray **p, int optional, const char *name)
     </screen>
 
    </sect2>
     </screen>
 
    </sect2>

-   <sect2><title>CHOICE Types</title>
+   <sect2 id="odr.choice.types"><title>CHOICE Types</title>

 
     <para>
      The choice type is used fairly often in some ASN.1 definitions, so
 
     <para>
      The choice type is used fairly often in some ASN.1 definitions, so