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

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007 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 <!-- $Id: lwres_gnba.html,v 1.24.214.1 2009/07/11 01:43:34 tbox Exp $ -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>lwres_gnba</title>
  22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23 </head>
  24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
  25 <a name="id2476275"></a><div class="titlepage"></div>
  26 <div class="refnamediv">
  27 <h2>Name</h2>
  28 <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>
  29 </div>
  30 <div class="refsynopsisdiv">
  31 <h2>Synopsis</h2>
  32 <div class="funcsynopsis">
  33 <pre class="funcsynopsisinfo">
  34 #include &lt;lwres/lwres.h&gt;
  35 </pre>
  36 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  37 <tr>
  38 <td><code class="funcdef">
  39 lwres_result_t
  40 <b class="fsfunc">lwres_gnbarequest_render</b>
  41 (</code></td>
  42 <td>lwres_context_t * </td>
  43 <td>
  44 <var class="pdparam">ctx</var>, </td>
  45 </tr>
  46 <tr>
  47 <td> </td>
  48 <td>lwres_gnbarequest_t * </td>
  49 <td>
  50 <var class="pdparam">req</var>, </td>
  51 </tr>
  52 <tr>
  53 <td> </td>
  54 <td>lwres_lwpacket_t * </td>
  55 <td>
  56 <var class="pdparam">pkt</var>, </td>
  57 </tr>
  58 <tr>
  59 <td> </td>
  60 <td>lwres_buffer_t * </td>
  61 <td>
  62 <var class="pdparam">b</var><code>)</code>;</td>
  63 </tr>
  64 </table>
  65 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  66 <tr>
  67 <td><code class="funcdef">
  68 lwres_result_t
  69 <b class="fsfunc">lwres_gnbaresponse_render</b>
  70 (</code></td>
  71 <td>lwres_context_t * </td>
  72 <td>
  73 <var class="pdparam">ctx</var>, </td>
  74 </tr>
  75 <tr>
  76 <td> </td>
  77 <td>lwres_gnbaresponse_t * </td>
  78 <td>
  79 <var class="pdparam">req</var>, </td>
  80 </tr>
  81 <tr>
  82 <td> </td>
  83 <td>lwres_lwpacket_t * </td>
  84 <td>
  85 <var class="pdparam">pkt</var>, </td>
  86 </tr>
  87 <tr>
  88 <td> </td>
  89 <td>lwres_buffer_t * </td>
  90 <td>
  91 <var class="pdparam">b</var><code>)</code>;</td>
  92 </tr>
  93 </table>
  94 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  95 <tr>
  96 <td><code class="funcdef">
  97 lwres_result_t
  98 <b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
  99 <td>lwres_context_t * </td>
 100 <td>
 101 <var class="pdparam">ctx</var>, </td>
 102 </tr>
 103 <tr>
 104 <td> </td>
 105 <td>lwres_buffer_t * </td>
 106 <td>
 107 <var class="pdparam">b</var>, </td>
 108 </tr>
 109 <tr>
 110 <td> </td>
 111 <td>lwres_lwpacket_t * </td>
 112 <td>
 113 <var class="pdparam">pkt</var>, </td>
 114 </tr>
 115 <tr>
 116 <td> </td>
 117 <td>lwres_gnbarequest_t ** </td>
 118 <td>
 119 <var class="pdparam">structp</var><code>)</code>;</td>
 120 </tr>
 121 </table>
 122 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 123 <tr>
 124 <td><code class="funcdef">
 125 lwres_result_t
 126 <b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
 127 <td>lwres_context_t * </td>
 128 <td>
 129 <var class="pdparam">ctx</var>, </td>
 130 </tr>
 131 <tr>
 132 <td> </td>
 133 <td>lwres_buffer_t * </td>
 134 <td>
 135 <var class="pdparam">b</var>, </td>
 136 </tr>
 137 <tr>
 138 <td> </td>
 139 <td>lwres_lwpacket_t * </td>
 140 <td>
 141 <var class="pdparam">pkt</var>, </td>
 142 </tr>
 143 <tr>
 144 <td> </td>
 145 <td>lwres_gnbaresponse_t ** </td>
 146 <td>
 147 <var class="pdparam">structp</var><code>)</code>;</td>
 148 </tr>
 149 </table>
 150 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 151 <tr>
 152 <td><code class="funcdef">
 153 void
 154 <b class="fsfunc">lwres_gnbaresponse_free</b>
 155 (</code></td>
 156 <td>lwres_context_t * </td>
 157 <td>
 158 <var class="pdparam">ctx</var>, </td>
 159 </tr>
 160 <tr>
 161 <td> </td>
 162 <td>lwres_gnbaresponse_t ** </td>
 163 <td>
 164 <var class="pdparam">structp</var><code>)</code>;</td>
 165 </tr>
 166 </table>
 167 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
 168 <tr>
 169 <td><code class="funcdef">
 170 void
 171 <b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
 172 <td>lwres_context_t * </td>
 173 <td>
 174 <var class="pdparam">ctx</var>, </td>
 175 </tr>
 176 <tr>
 177 <td> </td>
 178 <td>lwres_gnbarequest_t ** </td>
 179 <td>
 180 <var class="pdparam">structp</var><code>)</code>;</td>
 181 </tr>
 182 </table>
 183 </div>
 184 </div>
 185 <div class="refsect1" lang="en">
 186 <a name="id2543525"></a><h2>DESCRIPTION</h2>
 187 <p>
 188       These are low-level routines for creating and parsing
 189       lightweight resolver address-to-name lookup request and
 190       response messages.
 191     </p>
 192 <p>
 193       There are four main functions for the getnamebyaddr opcode.
 194       One render function converts a getnamebyaddr request structure &#8212;
 195       <span class="type">lwres_gnbarequest_t</span> &#8212;
 196       to the lightweight resolver's canonical format.
 197       It is complemented by a parse function that converts a packet in this
 198       canonical format to a getnamebyaddr request structure.
 199       Another render function converts the getnamebyaddr response structure
 200       &#8212;
 201       <span class="type">lwres_gnbaresponse_t</span>
 202       to the canonical format.
 203       This is complemented by a parse function which converts a packet in
 204       canonical format to a getnamebyaddr response structure.
 205     </p>
 206 <p>
 207       These structures are defined in
 208       <code class="filename">lwres/lwres.h</code>.
 209       They are shown below.
 210     </p>
 211 <pre class="programlisting">
 212 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 213 </pre>
 214 <p>
 215     </p>
 216 <pre class="programlisting">
 217 typedef struct {
 218         lwres_uint32_t  flags;
 219         lwres_addr_t    addr;
 220 } lwres_gnbarequest_t;
 221 </pre>
 222 <p>
 223     </p>
 224 <pre class="programlisting">
 225 typedef struct {
 226         lwres_uint32_t  flags;
 227         lwres_uint16_t  naliases;
 228         char           *realname;
 229         char          **aliases;
 230         lwres_uint16_t  realnamelen;
 231         lwres_uint16_t *aliaslen;
 232         void           *base;
 233         size_t          baselen;
 234 } lwres_gnbaresponse_t;
 235 </pre>
 236 <p>
 237     </p>
 238 <p><code class="function">lwres_gnbarequest_render()</code>
 239       uses resolver context <code class="varname">ctx</code> to convert
 240       getnamebyaddr request structure <code class="varname">req</code> to
 241       canonical format.  The packet header structure
 242       <code class="varname">pkt</code> is initialised and transferred to buffer
 243       <code class="varname">b</code>.  The contents of <code class="varname">*req</code>
 244       are then appended to the buffer in canonical format.
 245       <code class="function">lwres_gnbaresponse_render()</code> performs the
 246       same task, except it converts a getnamebyaddr response structure
 247       <span class="type">lwres_gnbaresponse_t</span> to the lightweight resolver's
 248       canonical format.
 249     </p>
 250 <p><code class="function">lwres_gnbarequest_parse()</code>
 251       uses context <code class="varname">ctx</code> to convert the contents of
 252       packet <code class="varname">pkt</code> to a
 253       <span class="type">lwres_gnbarequest_t</span> structure.  Buffer
 254       <code class="varname">b</code> provides space to be used for storing this
 255       structure.  When the function succeeds, the resulting
 256       <span class="type">lwres_gnbarequest_t</span> is made available through
 257       <code class="varname">*structp</code>.
 258       <code class="function">lwres_gnbaresponse_parse()</code> offers the same
 259       semantics as <code class="function">lwres_gnbarequest_parse()</code>
 260       except it yields a <span class="type">lwres_gnbaresponse_t</span> structure.
 261     </p>
 262 <p><code class="function">lwres_gnbaresponse_free()</code>
 263       and <code class="function">lwres_gnbarequest_free()</code> release the
 264       memory in resolver context <code class="varname">ctx</code> that was
 265       allocated to the <span class="type">lwres_gnbaresponse_t</span> or
 266       <span class="type">lwres_gnbarequest_t</span> structures referenced via
 267       <code class="varname">structp</code>.  Any memory associated with
 268       ancillary buffers and strings for those structures is also
 269       discarded.
 270     </p>
 271 </div>
 272 <div class="refsect1" lang="en">
 273 <a name="id2543665"></a><h2>RETURN VALUES</h2>
 274 <p>
 275       The getnamebyaddr opcode functions
 276       <code class="function">lwres_gnbarequest_render()</code>,
 277       <code class="function">lwres_gnbaresponse_render()</code>
 278       <code class="function">lwres_gnbarequest_parse()</code>
 279       and
 280       <code class="function">lwres_gnbaresponse_parse()</code>
 281       all return
 282       <span class="errorcode">LWRES_R_SUCCESS</span>
 283       on success.
 284       They return
 285       <span class="errorcode">LWRES_R_NOMEMORY</span>
 286       if memory allocation fails.
 287       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 288       is returned if the available space in the buffer
 289       <code class="varname">b</code>
 290       is too small to accommodate the packet header or the
 291       <span class="type">lwres_gnbarequest_t</span>
 292       and
 293       <span class="type">lwres_gnbaresponse_t</span>
 294       structures.
 295       <code class="function">lwres_gnbarequest_parse()</code>
 296       and
 297       <code class="function">lwres_gnbaresponse_parse()</code>
 298       will return
 299       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 300       if the buffer is not empty after decoding the received packet.
 301       These functions will return
 302       <span class="errorcode">LWRES_R_FAILURE</span>
 303       if
 304       <em class="structfield"><code>pktflags</code></em>
 305       in the packet header structure
 306       <span class="type">lwres_lwpacket_t</span>
 307       indicate that the packet is not a response to an earlier query.
 308     </p>
 309 </div>
 310 <div class="refsect1" lang="en">
 311 <a name="id2543731"></a><h2>SEE ALSO</h2>
 312 <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.
 313     </p>
 314 </div>
 315 </div></body>
 316 </html>