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

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and 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_gabn.docbook,v 1.3.206.3 2005/05/12 21:36:12 sra Exp $ -->
  22
  23 <refentry>
  24 <refentryinfo>
  25
  26
  27 <date>Jun 30, 2000</date>
  28 </refentryinfo>
  29 <refmeta>
  30 <refentrytitle>lwres_gabn</refentrytitle>
  31 <manvolnum>3</manvolnum>
  32 <refmiscinfo>BIND9</refmiscinfo>
  33 </refmeta>
  34
  35   <docinfo>
  36     <copyright>
  37       <year>2004</year>
  38       <year>2005</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 *ctx</paramdef>
  65 <paramdef>lwres_gabnrequest_t *req</paramdef>
  66 <paramdef>lwres_lwpacket_t *pkt</paramdef>
  67 <paramdef>lwres_buffer_t *b</paramdef>
  68 </funcprototype>
  69 <funcprototype>
  70 <funcdef>
  71 lwres_result_t
  72 <function>lwres_gabnresponse_render</function></funcdef>
  73 <paramdef>lwres_context_t *ctx</paramdef>
  74 <paramdef>lwres_gabnresponse_t *req</paramdef>
  75 <paramdef>lwres_lwpacket_t *pkt</paramdef>
  76 <paramdef>lwres_buffer_t *b</paramdef>
  77 </funcprototype>
  78 <funcprototype>
  79 <funcdef>
  80 lwres_result_t
  81 <function>lwres_gabnrequest_parse</function></funcdef>
  82 <paramdef>lwres_context_t *ctx</paramdef>
  83 <paramdef>lwres_buffer_t *b</paramdef>
  84 <paramdef>lwres_lwpacket_t *pkt</paramdef>
  85 <paramdef>lwres_gabnrequest_t **structp</paramdef>
  86 </funcprototype>
  87 <funcprototype>
  88 <funcdef>
  89 lwres_result_t
  90 <function>lwres_gabnresponse_parse</function></funcdef>
  91 <paramdef>lwres_context_t *ctx</paramdef>
  92 <paramdef>lwres_buffer_t *b</paramdef>
  93 <paramdef>lwres_lwpacket_t *pkt</paramdef>
  94 <paramdef>lwres_gabnresponse_t **structp</paramdef>
  95 </funcprototype>
  96 <funcprototype>
  97 <funcdef>
  98 void
  99 <function>lwres_gabnresponse_free</function></funcdef>
 100 <paramdef>lwres_context_t *ctx</paramdef>
 101 <paramdef>lwres_gabnresponse_t **structp</paramdef>
 102 </funcprototype>
 103 <funcprototype>
 104 <funcdef>
 105 void
 106 <function>lwres_gabnrequest_free</function></funcdef>
 107 <paramdef>lwres_context_t *ctx</paramdef>
 108 <paramdef>lwres_gabnrequest_t **structp</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><para>
 119 There are four main functions for the getaddrbyname opcode.
 120 One render function converts a getaddrbyname request structure &mdash;
 121 <type>lwres_gabnrequest_t</type> &mdash;
 122 to the lighweight resolver's canonical format.
 123 It is complemented by a parse function that converts a packet in this
 124 canonical format to a getaddrbyname request structure.
 125 Another render function converts the getaddrbyname response structure &mdash;
 126 <type>lwres_gabnresponse_t</type> &mdash;
 127 to the canonical format.
 128 This is complemented by a parse function which converts a packet in
 129 canonical format to a getaddrbyname response structure.
 130 </para>
 131 <para>
 132 These structures are defined in
 133 <filename>&lt;lwres/lwres.h&gt;</filename>.
 134 They are shown below.
 135 <programlisting>
 136 #define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
 137
 138 typedef struct lwres_addr lwres_addr_t;
 139 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
 140
 141 typedef struct {
 142         lwres_uint32_t  flags;
 143         lwres_uint32_t  addrtypes;
 144         lwres_uint16_t  namelen;
 145         char           *name;
 146 } lwres_gabnrequest_t;
 147
 148 typedef struct {
 149         lwres_uint32_t          flags;
 150         lwres_uint16_t          naliases;
 151         lwres_uint16_t          naddrs;
 152         char                   *realname;
 153         char                  **aliases;
 154         lwres_uint16_t          realnamelen;
 155         lwres_uint16_t         *aliaslen;
 156         lwres_addrlist_t        addrs;
 157         void                   *base;
 158         size_t                  baselen;
 159 } lwres_gabnresponse_t;
 160 </programlisting>
 161 </para>
 162 <para>
 163 <function>lwres_gabnrequest_render()</function>
 164 uses resolver context
 165 <parameter>ctx</parameter>
 166 to convert getaddrbyname request structure
 167 <parameter>req</parameter>
 168 to canonical format.
 169 The packet header structure
 170 <parameter>pkt</parameter>
 171 is initialised and transferred to
 172 buffer
 173 <parameter>b</parameter>.
 174
 175 The contents of
 176 <parameter>*req</parameter>
 177 are then appended to the buffer in canonical format.
 178 <function>lwres_gabnresponse_render()</function>
 179 performs the same task, except it converts a getaddrbyname response structure
 180 <type>lwres_gabnresponse_t</type>
 181 to the lightweight resolver's canonical format.
 182 </para>
 183 <para>
 184 <function>lwres_gabnrequest_parse()</function>
 185 uses context
 186 <parameter>ctx</parameter>
 187 to convert the contents of packet
 188 <parameter>pkt</parameter>
 189 to a
 190 <type>lwres_gabnrequest_t</type>
 191 structure.
 192 Buffer
 193 <parameter>b</parameter>
 194 provides space to be used for storing this structure.
 195 When the function succeeds, the resulting
 196 <type>lwres_gabnrequest_t</type>
 197 is made available through
 198 <parameter>*structp</parameter>.
 199
 200 <function>lwres_gabnresponse_parse()</function>
 201 offers the same semantics as
 202 <function>lwres_gabnrequest_parse()</function>
 203 except it yields a
 204 <type>lwres_gabnresponse_t</type>
 205 structure.
 206 </para>
 207 <para>
 208 <function>lwres_gabnresponse_free()</function>
 209 and
 210 <function>lwres_gabnrequest_free()</function>
 211 release the memory in resolver context
 212 <parameter>ctx</parameter>
 213 that was allocated to the
 214 <type>lwres_gabnresponse_t</type>
 215 or
 216 <type>lwres_gabnrequest_t</type>
 217 structures referenced via
 218 <parameter>structp</parameter>.
 219
 220 Any memory associated with ancillary buffers and strings for those
 221 structures is also discarded.
 222 </para>
 223 </refsect1>
 224 <refsect1>
 225 <title>RETURN VALUES</title>
 226 <para>
 227 The getaddrbyname opcode functions
 228 <function>lwres_gabnrequest_render()</function>,
 229 <function>lwres_gabnresponse_render()</function>
 230 <function>lwres_gabnrequest_parse()</function>
 231 and
 232 <function>lwres_gabnresponse_parse()</function>
 233 all return
 234 <errorcode>LWRES_R_SUCCESS</errorcode>
 235 on success.
 236 They return
 237 <errorcode>LWRES_R_NOMEMORY</errorcode>
 238 if memory allocation fails.
 239 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 240 is returned if the available space in the buffer
 241 <parameter>b</parameter>
 242 is too small to accommodate the packet header or the
 243 <type>lwres_gabnrequest_t</type>
 244 and
 245 <type>lwres_gabnresponse_t</type>
 246 structures.
 247 <function>lwres_gabnrequest_parse()</function>
 248 and
 249 <function>lwres_gabnresponse_parse()</function>
 250 will return
 251 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 252 if the buffer is not empty after decoding the received packet.
 253 These functions will return
 254 <errorcode>LWRES_R_FAILURE</errorcode>
 255 if
 256 <structfield>pktflags</structfield>
 257 in the packet header structure
 258 <type>lwres_lwpacket_t</type>
 259 indicate that the packet is not a response to an earlier query.
 260 </para>
 261 </refsect1>
 262 <refsect1>
 263 <title>SEE ALSO</title>
 264 <para>
 265 <citerefentry>
 266 <refentrytitle>lwres_packet</refentrytitle><manvolnum>3
 267 </manvolnum>
 268 </citerefentry>
 269 </para>
 270 </refsect1>
 271 </refentry>