contrib/bind9/lib/lwres/man/lwres_gnba.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_gnba.docbook,v 1.4.206.3 2005/05/12 21:36:15 sra Exp $ -->
  22
  23 <refentry>
  24
  25 <refentryinfo>
  26 <date>Jun 30, 2000</date>
  27 </refentryinfo>
  28
  29 <refmeta>
  30 <refentrytitle>lwres_gnba</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_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 *ctx</paramdef>
  82 <paramdef>lwres_gnbaresponse_t *req</paramdef>
  83 <paramdef>lwres_lwpacket_t *pkt</paramdef>
  84 <paramdef>lwres_buffer_t *b</paramdef>
  85 </funcprototype>
  86 <funcprototype>
  87 <funcdef>
  88 lwres_result_t
  89 <function>lwres_gnbarequest_parse</function></funcdef>
  90 <paramdef>lwres_context_t *ctx</paramdef>
  91 <paramdef>lwres_buffer_t *b</paramdef>
  92 <paramdef>lwres_lwpacket_t *pkt</paramdef>
  93 <paramdef>lwres_gnbarequest_t **structp</paramdef>
  94 </funcprototype>
  95 <funcprototype>
  96 <funcdef>
  97 lwres_result_t
  98 <function>lwres_gnbaresponse_parse</function></funcdef>
  99 <paramdef>lwres_context_t *ctx</paramdef>
 100 <paramdef>lwres_buffer_t *b</paramdef>
 101 <paramdef>lwres_lwpacket_t *pkt</paramdef>
 102 <paramdef>lwres_gnbaresponse_t **structp</paramdef>
 103 </funcprototype>
 104
 105 <funcprototype>
 106 <funcdef>
 107 void
 108 <function>lwres_gnbaresponse_free</function>
 109 </funcdef>
 110 <paramdef>lwres_context_t *ctx</paramdef>
 111 <paramdef>lwres_gnbaresponse_t **structp</paramdef>
 112 </funcprototype>
 113 <funcprototype>
 114 <funcdef>
 115 void
 116 <function>lwres_gnbarequest_free</function></funcdef>
 117 <paramdef>lwres_context_t *ctx</paramdef>
 118 <paramdef>lwres_gnbarequest_t **structp</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 &mdash;
 139 <type>lwres_gnbaresponse_t</type>
 140 to the canonical format.
 141 This is complemented by a parse function which converts a packet in
 142 canonical format to a getnamebyaddr response structure.
 143 </para>
 144 <para>
 145 These structures are defined in
 146 <filename>lwres/lwres.h</filename>.
 147 They are shown below.
 148 <programlisting>
 149 #define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
 150
 151 typedef struct {
 152         lwres_uint32_t  flags;
 153         lwres_addr_t    addr;
 154 } lwres_gnbarequest_t;
 155
 156 typedef struct {
 157         lwres_uint32_t  flags;
 158         lwres_uint16_t  naliases;
 159         char           *realname;
 160         char          **aliases;
 161         lwres_uint16_t  realnamelen;
 162         lwres_uint16_t *aliaslen;
 163         void           *base;
 164         size_t          baselen;
 165 } lwres_gnbaresponse_t;
 166 </programlisting>
 167 </para>
 168 <para>
 169 <function>lwres_gnbarequest_render()</function>
 170 uses resolver context
 171 <varname>ctx</varname>
 172 to convert getnamebyaddr request structure
 173 <varname>req</varname>
 174 to canonical format.
 175 The packet header structure
 176 <varname>pkt</varname>
 177 is initialised and transferred to
 178 buffer
 179 <varname>b</varname>.
 180 The contents of
 181 <varname>*req</varname>
 182 are then appended to the buffer in canonical format.
 183 <function>lwres_gnbaresponse_render()</function>
 184 performs the same task, except it converts a getnamebyaddr response structure
 185 <type>lwres_gnbaresponse_t</type>
 186 to the lightweight resolver's canonical format.
 187 </para>
 188 <para>
 189 <function>lwres_gnbarequest_parse()</function>
 190 uses context
 191 <varname>ctx</varname>
 192 to convert the contents of packet
 193 <varname>pkt</varname>
 194 to a
 195 <type>lwres_gnbarequest_t</type>
 196 structure.
 197 Buffer
 198 <varname>b</varname>
 199 provides space to be used for storing this structure.
 200 When the function succeeds, the resulting
 201 <type>lwres_gnbarequest_t</type>
 202 is made available through
 203 <varname>*structp</varname>.
 204 <function>lwres_gnbaresponse_parse()</function>
 205 offers the same semantics as
 206 <function>lwres_gnbarequest_parse()</function>
 207 except it yields a
 208 <type>lwres_gnbaresponse_t</type>
 209 structure.
 210 </para>
 211 <para>
 212 <function>lwres_gnbaresponse_free()</function>
 213 and
 214 <function>lwres_gnbarequest_free()</function>
 215 release the memory in resolver context
 216 <varname>ctx</varname>
 217 that was allocated to the
 218 <type>lwres_gnbaresponse_t</type>
 219 or
 220 <type>lwres_gnbarequest_t</type>
 221 structures referenced via
 222 <varname>structp</varname>.
 223 Any memory associated with ancillary buffers and strings for those
 224 structures is also discarded.
 225 </para>
 226 </refsect1>
 227 <refsect1>
 228 <title>RETURN VALUES</title>
 229 <para>
 230 The getnamebyaddr opcode functions
 231 <function>lwres_gnbarequest_render()</function>,
 232 <function>lwres_gnbaresponse_render()</function>
 233 <function>lwres_gnbarequest_parse()</function>
 234 and
 235 <function>lwres_gnbaresponse_parse()</function>
 236 all return
 237 <errorcode>LWRES_R_SUCCESS</errorcode>
 238 on success.
 239 They return
 240 <errorcode>LWRES_R_NOMEMORY</errorcode>
 241 if memory allocation fails.
 242 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 243 is returned if the available space in the buffer
 244 <varname>b</varname>
 245 is too small to accommodate the packet header or the
 246 <type>lwres_gnbarequest_t</type>
 247 and
 248 <type>lwres_gnbaresponse_t</type>
 249 structures.
 250 <function>lwres_gnbarequest_parse()</function>
 251 and
 252 <function>lwres_gnbaresponse_parse()</function>
 253 will return
 254 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
 255 if the buffer is not empty after decoding the received packet.
 256 These functions will return
 257 <errorcode>LWRES_R_FAILURE</errorcode>
 258 if
 259 <structfield>pktflags</structfield>
 260 in the packet header structure
 261 <type>lwres_lwpacket_t</type>
 262 indicate that the packet is not a response to an earlier query.
 263 </para>
 264 </refsect1>
 265 <refsect1>
 266 <title>SEE ALSO</title>
 267 <para>
 268 <citerefentry>
 269 <refentrytitle>lwres_packet</refentrytitle>
 270 <manvolnum>3</manvolnum>
 271 </citerefentry>.
 272 </para>
 273 </refsect1>
 274 </refentry>