dependencies/yaz-2.1.28/doc/asn.external.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>4. EXTERNAL Data</title><meta name="generator" content="DocBook XSL Stylesheets V1.70.1"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="asn.html" title="Chapter 6. The Z39.50 ASN.1 Module"><link rel="prev" href="asn.oid.html" title="3. Object Identifiers"><link rel="next" href="asn.pdu.html" title="5. PDU Contents Table"></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">4. EXTERNAL Data</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="asn.oid.html">Prev</a> </td><th width="60%" align="center">Chapter 6. The Z39.50 ASN.1 Module</th><td width="20%" align="right"> <a accesskey="n" href="asn.pdu.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="asn.external"></a>4. EXTERNAL Data</h2></div></div></div><p>
   2     In order to achieve extensibility and adaptability to different
   3     application domains, the new version of the protocol defines many
   4     structures outside of the main ASN.1 specification, referencing them
   5     through ASN.1 EXTERNAL constructs. To simplify the construction and
   6     access to the externally referenced data, the Z39.50 ASN.1 module defines a
   7     specialized version of the EXTERNAL construct, called
   8     <code class="literal">Z_External</code>.It is defined thus:
   9    </p><pre class="screen">
  10 typedef struct Z_External
  11 {
  12     Odr_oid *direct_reference;
  13     int *indirect_reference;
  14     char *descriptor;
  15     enum
  16     {
  17         /* Generic types */
  18         Z_External_single = 0,
  19         Z_External_octet,
  20         Z_External_arbitrary,
  21
  22         /* Specific types */
  23         Z_External_SUTRS,
  24         Z_External_explainRecord,
  25         Z_External_resourceReport1,
  26         Z_External_resourceReport2
  27
  28     ...
  29
  30     } which;
  31     union
  32     {
  33         /* Generic types */
  34         Odr_any *single_ASN1_type;
  35         Odr_oct *octet_aligned;
  36         Odr_bitmask *arbitrary;
  37
  38         /* Specific types */
  39         Z_SUTRS *sutrs;
  40         Z_ExplainRecord *explainRecord;
  41         Z_ResourceReport1 *resourceReport1;
  42         Z_ResourceReport2 *resourceReport2;
  43
  44         ...
  45
  46     } u;
  47 } Z_External;
  48    </pre><p>
  49     When decoding, the Z39.50 ASN.1 module will attempt to determine which
  50     syntax describes the data by looking at the reference fields
  51     (currently only the direct-reference). For ASN.1 structured data, you
  52     need only consult the <code class="literal">which</code> field to determine the
  53     type of data. You can the access  the data directly through the union.
  54     When constructing data for encoding, you set the union pointer to point
  55     to the data, and set the <code class="literal">which</code> field accordingly.
  56     Remember also to set the direct (or indirect) reference to the correct
  57     OID for the data type.
  58     For non-ASN.1 data such as MARC records, use the
  59     <code class="literal">octet_aligned</code> arm of the union.
  60    </p><p>
  61     Some servers return ASN.1 structured data values (eg. database
  62     records) as BER-encoded records placed in the
  63     <code class="literal">octet-aligned</code> branch of the EXTERNAL CHOICE.
  64     The ASN-module will <span class="emphasis"><em>not</em></span> automatically decode
  65     these records. To help you decode the records in the application, the
  66     function
  67    </p><pre class="screen">
  68    Z_ext_typeent *z_ext_gettypebyref(oid_value ref);
  69    </pre><p>
  70     Can be used to retrieve information about the known, external data
  71     types. The function return a pointer to a static area, or NULL, if no
  72     match for the given direct reference is found. The
  73     <code class="literal">Z_ext_typeent</code>
  74     is defined as:
  75    </p><pre class="screen">
  76 typedef struct Z_ext_typeent
  77 {
  78     oid_value dref;    /* the direct-reference OID value. */
  79     int what;          /* discriminator value for the external CHOICE */
  80     Odr_fun fun;       /* decoder function */
  81 } Z_ext_typeent;
  82    </pre><p>
  83     The <code class="literal">what</code> member contains the
  84     <code class="literal">Z_External</code> union discriminator value for the
  85     given type: For the SUTRS record syntax, the value would be
  86     <code class="literal">Z_External_sutrs</code>.
  87     The <code class="literal">fun</code> member contains a pointer to the
  88     function which encodes/decodes the given type. Again, for the SUTRS
  89     record syntax, the value of <code class="literal">fun</code> would be
  90     <code class="literal">z_SUTRS</code> (a function pointer).
  91    </p><p>
  92     If you receive an EXTERNAL which contains an octet-string value that
  93     you suspect of being an ASN.1-structured data value, you can use
  94     <code class="literal">z_ext_gettypebyref</code> to look for the provided
  95     direct-reference.
  96     If the return value is different from NULL, you can use the provided
  97     function to decode the BER string (see <a href="odr.use.html" title="2. Using ODR">Section 2, &#8220;Using ODR&#8221;</a>
  98     ).
  99    </p><p>
 100     If you want to <span class="emphasis"><em>send</em></span> EXTERNALs containing
 101     ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
 102     is possible too. However, on the encoding phase, it requires a somewhat
 103     involved juggling around of the various buffers involved.
 104    </p><p>
 105     If you need to add new, externally defined data types, you must update
 106     the struct above, in the source file <code class="filename">prt-ext.h</code>, as
 107     well as the encoder/decoder in the file <code class="filename">prt-ext.c</code>.
 108     When changing the latter, remember to update both the
 109     <code class="literal">arm</code> arrary and the list
 110     <code class="literal">type_table</code>, which drives the CHOICE biasing that
 111     is necessary to tell the different, structured types apart
 112     on decoding.
 113    </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 114      Eventually, the EXTERNAL processing will most likely
 115      automatically insert the correct OIDs or indirect-refs. First,
 116      however, we need to determine how application-context management
 117      (specifically the presentation-context-list) should fit into the
 118      various modules.
 119     </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="asn.oid.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="asn.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="asn.pdu.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Object Identifiers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5. PDU Contents Table</td></tr></table></div></body></html>