external/bsd/bind/dist/lib/lwres/man/lwres_gabn.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, 2014  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 <refentry>
  22
  23   <refentryinfo>
  24     <date>June 18, 2007</date>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle>lwres_gabn</refentrytitle>
  29     <manvolnum>3</manvolnum>
  30     <refmiscinfo>BIND9</refmiscinfo>
  31   </refmeta>
  32
  33   <docinfo>
  34     <copyright>
  35       <year>2004</year>
  36       <year>2005</year>
  37       <year>2007</year>
  38       <year>2014</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_gabnrequest_render</refname>
  50     <refname>lwres_gabnresponse_render</refname>
  51     <refname>lwres_gabnrequest_parse</refname>
  52     <refname>lwres_gabnresponse_parse</refname>
  53     <refname>lwres_gabnresponse_free</refname>
  54     <refname>lwres_gabnrequest_free</refname>
  55     <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
  56   </refnamediv>
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59 <funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
  60 <funcprototype>
  61         <funcdef>
  62 lwres_result_t
  63 <function>lwres_gabnrequest_render</function></funcdef>
  64         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  65         <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
  66         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  67         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  68         </funcprototype>
  69 <funcprototype>
  70         <funcdef>
  71 lwres_result_t
  72 <function>lwres_gabnresponse_render</function></funcdef>
  73         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  74         <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
  75         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  76         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  77         </funcprototype>
  78 <funcprototype>
  79         <funcdef>
  80 lwres_result_t
  81 <function>lwres_gabnrequest_parse</function></funcdef>
  82         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  83         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  84         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  85         <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
  86         </funcprototype>
  87 <funcprototype>
  88         <funcdef>
  89 lwres_result_t
  90 <function>lwres_gabnresponse_parse</function></funcdef>
  91         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  92         <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  93         <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  94         <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
  95         </funcprototype>
  96 <funcprototype>
  97         <funcdef>
  98 void
  99 <function>lwres_gabnresponse_free</function></funcdef>
 100         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 101         <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
 102         </funcprototype>
 103 <funcprototype>
 104         <funcdef>
 105 void
 106 <function>lwres_gabnrequest_free</function></funcdef>
 107         <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 108         <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
 109       </funcprototype>
 110 </funcsynopsis>
 111   </refsynopsisdiv>
 112   <refsect1>
 113     <title>DESCRIPTION</title>
 114     <para>
 115       These are low-level routines for creating and parsing
 116       lightweight resolver name-to-address lookup request and
 117       response messages.
 118     </para>
 119     <para>
 120       There are four main functions for the getaddrbyname opcode.
 121       One render function converts a getaddrbyname request structure &mdash;
 122       <type>lwres_gabnrequest_t</type> &mdash;
 123       to the lightweight resolver's canonical format.
 124       It is complemented by a parse function that converts a packet in this
 125       canonical format to a getaddrbyname request structure.
 126       Another render function converts the getaddrbyname response structure
 127       &mdash; <type>lwres_gabnresponse_t</type> &mdash;
 128       to the canonical format.
 129       This is complemented by a parse function which converts a packet in
 130       canonical format to a getaddrbyname response structure.
 131     </para>
 132     <para>
 133       These structures are defined in
 134       <filename>&lt;lwres/lwres.h&gt;</filename>.
 135       They are shown below.
 136     </para>
 137     <para><programlisting>
 138 #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 139 </programlisting>
 140     </para>
 141     <para><programlisting>
 142 typedef struct lwres_addr lwres_addr_t;
 143 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 144 </programlisting>
 145     </para>
 146     <para><programlisting>
 147 typedef struct {
 148         lwres_uint32_t  flags;
 149         lwres_uint32_t  addrtypes;
 150         lwres_uint16_t  namelen;
 151         char           *name;
 152 } lwres_gabnrequest_t;
 153 </programlisting>
 154     </para>
 155     <para><programlisting>
 156 typedef struct {
 157         lwres_uint32_t          flags;
 158         lwres_uint16_t          naliases;
 159         lwres_uint16_t          naddrs;
 160         char                   *realname;
 161         char                  **aliases;
 162         lwres_uint16_t          realnamelen;
 163         lwres_uint16_t         *aliaslen;
 164         lwres_addrlist_t        addrs;
 165         void                   *base;
 166         size_t                  baselen;
 167 } lwres_gabnresponse_t;
 168 </programlisting>
 169     </para>
 170
 171     <para><function>lwres_gabnrequest_render()</function>
 172       uses resolver context <parameter>ctx</parameter> to convert
 173       getaddrbyname request structure <parameter>req</parameter> to
 174       canonical format.  The packet header structure
 175       <parameter>pkt</parameter> is initialised and transferred to
 176       buffer <parameter>b</parameter>.
 177
 178       The contents of <parameter>*req</parameter> are then appended to
 179       the buffer in canonical format.
 180       <function>lwres_gabnresponse_render()</function> performs the
 181       same task, except it converts a getaddrbyname response structure
 182       <type>lwres_gabnresponse_t</type> to the lightweight resolver's
 183       canonical format.
 184     </para>
 185
 186     <para><function>lwres_gabnrequest_parse()</function>
 187       uses context <parameter>ctx</parameter> to convert the contents
 188       of packet <parameter>pkt</parameter> to a
 189       <type>lwres_gabnrequest_t</type> structure.  Buffer
 190       <parameter>b</parameter> provides space to be used for storing
 191       this structure.  When the function succeeds, the resulting
 192       <type>lwres_gabnrequest_t</type> is made available through
 193       <parameter>*structp</parameter>.
 194
 195       <function>lwres_gabnresponse_parse()</function> offers the same
 196       semantics as <function>lwres_gabnrequest_parse()</function>
 197       except it yields a <type>lwres_gabnresponse_t</type> structure.
 198     </para>
 199
 200     <para><function>lwres_gabnresponse_free()</function>
 201       and <function>lwres_gabnrequest_free()</function> release the
 202       memory in resolver context <parameter>ctx</parameter> that was
 203       allocated to the <type>lwres_gabnresponse_t</type> or
 204       <type>lwres_gabnrequest_t</type> structures referenced via
 205       <parameter>structp</parameter>.
 206
 207       Any memory associated with ancillary buffers and strings for
 208       those structures is also discarded.
 209     </para>
 210   </refsect1>
 211   <refsect1>
 212     <title>RETURN VALUES</title>
 213     <para>
 214       The getaddrbyname opcode functions
 215       <function>lwres_gabnrequest_render()</function>,
 216       <function>lwres_gabnresponse_render()</function>
 217       <function>lwres_gabnrequest_parse()</function>
 218       and
 219       <function>lwres_gabnresponse_parse()</function>
 220       all return
 221       <errorcode>LWRES_R_SUCCESS</errorcode>
 222       on success.
 223       They return
 224       <errorcode>LWRES_R_NOMEMORY</errorcode>
 225       if memory allocation fails.
 226       <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 227       is returned if the available space in the buffer
 228       <parameter>b</parameter>
 229       is too small to accommodate the packet header or the
 230       <type>lwres_gabnrequest_t</type>
 231       and
 232       <type>lwres_gabnresponse_t</type>
 233       structures.
 234       <function>lwres_gabnrequest_parse()</function>
 235       and
 236       <function>lwres_gabnresponse_parse()</function>
 237       will return
 238       <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 239       if the buffer is not empty after decoding the received packet.
 240       These functions will return
 241       <errorcode>LWRES_R_FAILURE</errorcode>
 242       if
 243       <structfield>pktflags</structfield>
 244       in the packet header structure
 245       <type>lwres_lwpacket_t</type>
 246       indicate that the packet is not a response to an earlier query.
 247     </para>
 248   </refsect1>
 249   <refsect1>
 250     <title>SEE ALSO</title>
 251     <para><citerefentry>
 252         <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
 253       </citerefentry>
 254     </para>
 255   </refsect1>
 256 </refentry><!--
 257  - Local variables:
 258  - mode: sgml
 259  - End:
 260 -->