contrib/bind9/lib/lwres/man/lwres_gnba.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001 Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and/or distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17 <html>
  18 <head>
  19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  20 <title>lwres_gnba</title>
  21 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
  22 </head>
  23 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
  24 <a name="id-1"></a><div class="titlepage"></div>
  25 <div class="refnamediv">
  26 <h2>Name</h2>
  27 <p>lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free &#8212; lightweight resolver getnamebyaddress message handling</p>
  28 </div>
  29 <div class="refsynopsisdiv">
  30 <h2>Synopsis</h2>
  31 <div class="funcsynopsis">
  32 <pre class="funcsynopsisinfo">
  33 #include &lt;lwres/lwres.h&gt;
  34 </pre>
  35 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  36 <tr>
  37 <td><code class="funcdef">
  38 lwres_result_t
  39 <b class="fsfunc">lwres_gnbarequest_render</b>
  40 (</code></td>
  41 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  42 </tr>
  43 <tr>
  44 <td> </td>
  45 <td>lwres_gnbarequest_t *<var class="pdparam">req</var>, </td>
  46 </tr>
  47 <tr>
  48 <td> </td>
  49 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  50 </tr>
  51 <tr>
  52 <td> </td>
  53 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  54 </tr>
  55 </table>
  56 <div class="funcprototype-spacer"> </div>
  57 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  58 <tr>
  59 <td><code class="funcdef">
  60 lwres_result_t
  61 <b class="fsfunc">lwres_gnbaresponse_render</b>
  62 (</code></td>
  63 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  64 </tr>
  65 <tr>
  66 <td> </td>
  67 <td>lwres_gnbaresponse_t *<var class="pdparam">req</var>, </td>
  68 </tr>
  69 <tr>
  70 <td> </td>
  71 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  72 </tr>
  73 <tr>
  74 <td> </td>
  75 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  76 </tr>
  77 </table>
  78 <div class="funcprototype-spacer"> </div>
  79 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  80 <tr>
  81 <td><code class="funcdef">
  82 lwres_result_t
  83 <b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
  84 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  85 </tr>
  86 <tr>
  87 <td> </td>
  88 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
  89 </tr>
  90 <tr>
  91 <td> </td>
  92 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  93 </tr>
  94 <tr>
  95 <td> </td>
  96 <td>lwres_gnbarequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
  97 </tr>
  98 </table>
  99 <div class="funcprototype-spacer"> </div>
 100 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 101 <tr>
 102 <td><code class="funcdef">
 103 lwres_result_t
 104 <b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
 105 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 106 </tr>
 107 <tr>
 108 <td> </td>
 109 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 110 </tr>
 111 <tr>
 112 <td> </td>
 113 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
 114 </tr>
 115 <tr>
 116 <td> </td>
 117 <td>lwres_gnbaresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
 118 </tr>
 119 </table>
 120 <div class="funcprototype-spacer"> </div>
 121 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 122 <tr>
 123 <td><code class="funcdef">
 124 void
 125 <b class="fsfunc">lwres_gnbaresponse_free</b>
 126 (</code></td>
 127 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 128 </tr>
 129 <tr>
 130 <td> </td>
 131 <td>lwres_gnbaresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
 132 </tr>
 133 </table>
 134 <div class="funcprototype-spacer"> </div>
 135 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 136 <tr>
 137 <td><code class="funcdef">
 138 void
 139 <b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
 140 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 141 </tr>
 142 <tr>
 143 <td> </td>
 144 <td>lwres_gnbarequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
 145 </tr>
 146 </table>
 147 <div class="funcprototype-spacer"> </div>
 148 </div>
 149 </div>
 150 <div class="refsection">
 151 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
 152 <p>
 153       These are low-level routines for creating and parsing
 154       lightweight resolver address-to-name lookup request and
 155       response messages.
 156     </p>
 157 <p>
 158       There are four main functions for the getnamebyaddr opcode.
 159       One render function converts a getnamebyaddr request structure &#8212;
 160       <span class="type">lwres_gnbarequest_t</span> &#8212;
 161       to the lightweight resolver's canonical format.
 162       It is complemented by a parse function that converts a packet in this
 163       canonical format to a getnamebyaddr request structure.
 164       Another render function converts the getnamebyaddr response structure
 165       &#8212;
 166       <span class="type">lwres_gnbaresponse_t</span>
 167       to the canonical format.
 168       This is complemented by a parse function which converts a packet in
 169       canonical format to a getnamebyaddr response structure.
 170     </p>
 171 <p>
 172       These structures are defined in
 173       <code class="filename">lwres/lwres.h</code>.
 174       They are shown below.
 175     </p>
 176 <pre class="programlisting">
 177 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 178 </pre>
 179 <p>
 180     </p>
 181 <pre class="programlisting">
 182 typedef struct {
 183         lwres_uint32_t  flags;
 184         lwres_addr_t    addr;
 185 } lwres_gnbarequest_t;
 186 </pre>
 187 <p>
 188     </p>
 189 <pre class="programlisting">
 190 typedef struct {
 191         lwres_uint32_t  flags;
 192         lwres_uint16_t  naliases;
 193         char           *realname;
 194         char          **aliases;
 195         lwres_uint16_t  realnamelen;
 196         lwres_uint16_t *aliaslen;
 197         void           *base;
 198         size_t          baselen;
 199 } lwres_gnbaresponse_t;
 200 </pre>
 201 <p>
 202     </p>
 203 <p><code class="function">lwres_gnbarequest_render()</code>
 204       uses resolver context <code class="varname">ctx</code> to convert
 205       getnamebyaddr request structure <code class="varname">req</code> to
 206       canonical format.  The packet header structure
 207       <code class="varname">pkt</code> is initialised and transferred to buffer
 208       <code class="varname">b</code>.  The contents of <code class="varname">*req</code>
 209       are then appended to the buffer in canonical format.
 210       <code class="function">lwres_gnbaresponse_render()</code> performs the
 211       same task, except it converts a getnamebyaddr response structure
 212       <span class="type">lwres_gnbaresponse_t</span> to the lightweight resolver's
 213       canonical format.
 214     </p>
 215 <p><code class="function">lwres_gnbarequest_parse()</code>
 216       uses context <code class="varname">ctx</code> to convert the contents of
 217       packet <code class="varname">pkt</code> to a
 218       <span class="type">lwres_gnbarequest_t</span> structure.  Buffer
 219       <code class="varname">b</code> provides space to be used for storing this
 220       structure.  When the function succeeds, the resulting
 221       <span class="type">lwres_gnbarequest_t</span> is made available through
 222       <code class="varname">*structp</code>.
 223       <code class="function">lwres_gnbaresponse_parse()</code> offers the same
 224       semantics as <code class="function">lwres_gnbarequest_parse()</code>
 225       except it yields a <span class="type">lwres_gnbaresponse_t</span> structure.
 226     </p>
 227 <p><code class="function">lwres_gnbaresponse_free()</code>
 228       and <code class="function">lwres_gnbarequest_free()</code> release the
 229       memory in resolver context <code class="varname">ctx</code> that was
 230       allocated to the <span class="type">lwres_gnbaresponse_t</span> or
 231       <span class="type">lwres_gnbarequest_t</span> structures referenced via
 232       <code class="varname">structp</code>.  Any memory associated with
 233       ancillary buffers and strings for those structures is also
 234       discarded.
 235     </p>
 236 </div>
 237 <div class="refsection">
 238 <a name="id-1.8"></a><h2>RETURN VALUES</h2>
 239 <p>
 240       The getnamebyaddr opcode functions
 241       <code class="function">lwres_gnbarequest_render()</code>,
 242       <code class="function">lwres_gnbaresponse_render()</code>
 243       <code class="function">lwres_gnbarequest_parse()</code>
 244       and
 245       <code class="function">lwres_gnbaresponse_parse()</code>
 246       all return
 247       <span class="errorcode">LWRES_R_SUCCESS</span>
 248       on success.
 249       They return
 250       <span class="errorcode">LWRES_R_NOMEMORY</span>
 251       if memory allocation fails.
 252       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 253       is returned if the available space in the buffer
 254       <code class="varname">b</code>
 255       is too small to accommodate the packet header or the
 256       <span class="type">lwres_gnbarequest_t</span>
 257       and
 258       <span class="type">lwres_gnbaresponse_t</span>
 259       structures.
 260       <code class="function">lwres_gnbarequest_parse()</code>
 261       and
 262       <code class="function">lwres_gnbaresponse_parse()</code>
 263       will return
 264       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 265       if the buffer is not empty after decoding the received packet.
 266       These functions will return
 267       <span class="errorcode">LWRES_R_FAILURE</span>
 268       if
 269       <code class="varname">pktflags</code>
 270       in the packet header structure
 271       <span class="type">lwres_lwpacket_t</span>
 272       indicate that the packet is not a response to an earlier query.
 273     </p>
 274 </div>
 275 <div class="refsection">
 276 <a name="id-1.9"></a><h2>SEE ALSO</h2>
 277 <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.
 278     </p>
 279 </div>
 280 </div></body>
 281 </html>