dependencies/yaz_3.0.14/doc/asn.preparing.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2. Preparing PDUs</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 7. The Z39.50 ASN.1 Module"><link rel="prev" href="asn.html" title="Chapter 7. The Z39.50 ASN.1 Module"><link rel="next" href="asn.oid.html" title="3. Object Identifiers (YAZ 2)"></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. Preparing PDUs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="asn.html">Prev</a> </td><th width="60%" align="center">Chapter 7. The Z39.50 ASN.1 Module</th><td width="20%" align="right"> <a accesskey="n" href="asn.oid.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.preparing"></a>2. Preparing PDUs</h2></div></div></div><p>
   2     A structure representing a complex ASN.1 type doesn't in itself contain the
   3     members of that type. Instead, the structure contains
   4     <span class="emphasis"><em>pointers</em></span> to the members of the type.
   5     This is necessary, in part, to allow a mechanism for specifying which
   6     of the optional structure (SEQUENCE) members are present, and which
   7     are not. It follows that you will need to somehow provide space for
   8     the individual members of the structure, and set the pointers to
   9     refer to the members.
  10    </p><p>
  11     The conversion routines don't care how you allocate and maintain your
  12     C structures - they just follow the pointers that you provide.
  13     Depending on the complexity of your application, and your personal
  14     taste, there are at least three different approaches that you may take
  15     when you allocate the structures.
  16    </p><p>
  17     You can use static or automatic local variables in the function that
  18     prepares the PDU. This is a simple approach, and it provides the most
  19     efficient form of memory management. While it works well for flat
  20     PDUs like the InitReqest, it will generally not be sufficient for say,
  21     the generation of an arbitrarily complex RPN query structure.
  22    </p><p>
  23     You can individually create the structure and its members using the
  24     <code class="function">malloc(2)</code> function. If you want to ensure that
  25     the data is freed when it is no longer needed, you will have to
  26     define a function that individually releases each member of a
  27     structure before freeing the structure itself.
  28    </p><p>
  29     You can use the <code class="function">odr_malloc()</code> function (see
  30     <a class="xref" href="odr.use.html" title="2. Using ODR">Section 2, &#8220;Using ODR&#8221;</a> for details). When you use
  31     <code class="function">odr_malloc()</code>, you can release all of the
  32     allocated data in a single operation, independent of any pointers and
  33     relations between the data. <code class="function">odr_malloc()</code> is based on a
  34     "nibble-memory"
  35     scheme, in which large portions of memory are allocated, and then
  36     gradually handed out with each call to <code class="function">odr_malloc()</code>.
  37     The next time you call <code class="function">odr_reset()</code>, all of the
  38     memory allocated since the last call is recycled for future use (actually,
  39     it is placed on a free-list).
  40    </p><p>
  41     You can combine all of the methods described here. This will often be
  42     the most practical approach. For instance, you might use
  43     <code class="function">odr_malloc()</code> to allocate an entire structure and
  44     some of its elements, while you leave other elements pointing to global
  45     or per-session default variables.
  46    </p><p>
  47     The Z39.50 ASN.1 module provides an important aid in creating new PDUs. For
  48     each of the PDU types (say, <code class="function">Z_InitRequest</code>), a
  49     function is provided that allocates and initializes an instance of
  50     that PDU type for you. In the case of the InitRequest, the function is
  51     simply named <code class="function">zget_InitRequest()</code>, and it sets up
  52     reasonable default value for all of the mandatory members. The optional
  53     members are generally initialized to null pointers. This last aspect
  54     is very important: it ensures that if the PDU definitions are
  55     extended after you finish your implementation (to accommodate
  56     new versions of the protocol, say), you won't get into trouble with
  57     uninitialized pointers in your structures. The functions use
  58     <code class="function">odr_malloc()</code> to
  59     allocate the PDUs and its members, so you can free everything again with a
  60     single call to <code class="function">odr_reset()</code>. We strongly recommend
  61     that you use the <code class="literal">zget_*</code>
  62     functions whenever you are preparing a PDU (in a C++ API, the
  63     <code class="literal">zget_</code>
  64     functions would probably be promoted to constructors for the
  65     individual types).
  66    </p><p>
  67    The prototype for the individual PDU types generally look like this:
  68    </p><pre class="synopsis">
  69     Z_&lt;type&gt; *zget_&lt;type&gt;(ODR o);
  70    </pre><p>
  71     eg.:
  72    </p><pre class="synopsis">
  73     Z_InitRequest *zget_InitRequest(ODR o);
  74    </pre><p>
  75    The <acronym class="acronym">ODR</acronym> handle should generally be your encoding stream, but it
  76     needn't be.
  77    </p><p>
  78    As well as the individual PDU functions, a function
  79     <code class="function">zget_APDU()</code> is provided, which allocates
  80     a top-level Z-APDU of the type requested:
  81    </p><pre class="synopsis">
  82     Z_APDU *zget_APDU(ODR o, int which);
  83    </pre><p>
  84     The <code class="varname">which</code> parameter is (of course) the discriminator
  85     belonging to the <code class="varname">Z_APDU</code> <code class="literal">CHOICE</code> type.
  86     All of the interface described here is provided by the Z39.50 ASN.1 module, and
  87     you access it through the <code class="filename">proto.h</code> header file.
  88
  89    </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="asn.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.oid.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. The Z39.50 ASN.1 Module </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3. Object Identifiers (YAZ 2)</td></tr></table></div></body></html>