src/libfreeswan/liblwres/man/lwres_gabn.docbook

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