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

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