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

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