File: asn.external.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 (119 lines) | stat: -rw-r--r-- 7,020 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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3.�EXTERNAL Data</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="asn.html" title="Chapter�5.�The Z39.50 ASN.1 Module"><link rel="prev" href="asn.preparing.html" title="2.�Preparing PDUs"><link rel="next" href="asn.pdu.html" title="4.�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">3.�EXTERNAL Data</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="asn.preparing.html">Prev</a>�</td><th width="60%" align="center">Chapter�5.�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>3.�EXTERNAL Data</h2></div></div></div><p>
    In order to achieve extensibility and adaptability to different
    application domains, the new version of the protocol defines many
    structures outside of the main ASN.1 specification, referencing them
    through ASN.1 EXTERNAL constructs. To simplify the construction and
    access to the externally referenced data, the Z39.50 ASN.1 module defines a
    specialized version of the EXTERNAL construct, called
    <code class="literal">Z_External</code>.It is defined thus:
   </p><pre class="screen">
typedef struct Z_External
{
    Odr_oid *direct_reference;
    int *indirect_reference;
    char *descriptor;
    enum
    {
        /* Generic types */
        Z_External_single = 0,
        Z_External_octet,
        Z_External_arbitrary,

        /* Specific types */
        Z_External_SUTRS,
        Z_External_explainRecord,
        Z_External_resourceReport1,
        Z_External_resourceReport2

    ...

    } which;
    union
    {
        /* Generic types */
        Odr_any *single_ASN1_type;
        Odr_oct *octet_aligned;
        Odr_bitmask *arbitrary;

        /* Specific types */
        Z_SUTRS *sutrs;
        Z_ExplainRecord *explainRecord;
        Z_ResourceReport1 *resourceReport1;
        Z_ResourceReport2 *resourceReport2;

        ...

    } u;
} Z_External;
   </pre><p>
    When decoding, the Z39.50 ASN.1 module will attempt to determine which
    syntax describes the data by looking at the reference fields
    (currently only the direct-reference). For ASN.1 structured data, you
    need only consult the <code class="literal">which</code> field to determine the
    type of data. You can the access  the data directly through the union.
    When constructing data for encoding, you set the union pointer to point
    to the data, and set the <code class="literal">which</code> field accordingly.
    Remember also to set the direct (or indirect) reference to the correct
    OID for the data type.
    For non-ASN.1 data such as MARC records, use the
    <code class="literal">octet_aligned</code> arm of the union.
   </p><p>
    Some servers return ASN.1 structured data values (eg. database
    records) as BER-encoded records placed in the
    <code class="literal">octet-aligned</code> branch of the EXTERNAL CHOICE.
    The ASN-module will <span class="emphasis"><em>not</em></span> automatically decode
    these records. To help you decode the records in the application, the
    function
   </p><pre class="screen">
   Z_ext_typeent *z_ext_gettypebyref(const oid *oid);
   </pre><p>
    Can be used to retrieve information about the known, external data
    types. The function return a pointer to a static area, or NULL, if no
    match for the given direct reference is found. The
    <code class="literal">Z_ext_typeent</code>
    is defined as:
   </p><pre class="screen">
typedef struct Z_ext_typeent
{
    int oid[OID_SIZE]; /* the direct-reference OID. */
    int what;          /* discriminator value for the external CHOICE */
    Odr_fun fun;       /* decoder function */
} Z_ext_typeent;
   </pre><p>
    The <code class="literal">what</code> member contains the
    <code class="literal">Z_External</code> union discriminator value for the
    given type: For the SUTRS record syntax, the value would be
    <code class="literal">Z_External_sutrs</code>.
    The <code class="literal">fun</code> member contains a pointer to the
    function which encodes/decodes the given type. Again, for the SUTRS
    record syntax, the value of <code class="literal">fun</code> would be
    <code class="literal">z_SUTRS</code> (a function pointer).
   </p><p>
    If you receive an EXTERNAL which contains an octet-string value that
    you suspect of being an ASN.1-structured data value, you can use
    <code class="literal">z_ext_gettypebyref</code> to look for the provided
    direct-reference.
    If the return value is different from NULL, you can use the provided
    function to decode the BER string (see <a class="xref" href="odr.use.html" title="2.�Using ODR">Section�2, &#8220;Using ODR&#8221;</a>
    ).
   </p><p>
    If you want to <span class="emphasis"><em>send</em></span> EXTERNALs containing
    ASN.1-structured values in the occtet-aligned branch of the CHOICE, this
    is possible too. However, on the encoding phase, it requires a somewhat
    involved juggling around of the various buffers involved.
   </p><p>
    If you need to add new, externally defined data types, you must update
    the struct above, in the source file <code class="filename">prt-ext.h</code>, as
    well as the encoder/decoder in the file <code class="filename">prt-ext.c</code>.
    When changing the latter, remember to update both the
    <code class="literal">arm</code> arrary and the list
    <code class="literal">type_table</code>, which drives the CHOICE biasing that
    is necessary to tell the different, structured types apart
    on decoding.
   </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
     Eventually, the EXTERNAL processing will most likely
     automatically insert the correct OIDs or indirect-refs. First,
     however, we need to determine how application-context management
     (specifically the presentation-context-list) should fit into the
     various modules.
    </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="asn.preparing.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">2.�Preparing PDUs�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�4.�PDU Contents Table</td></tr></table></div></body></html>