lwres_resutil.docbook revision ec5347e2c775f027573ce5648b910361aa926c01
436aad11e01e916f75e68a2e9cb89ac217a990d3Tinderbox User<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic Updater "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
18920d790825d96ca3943aa2dcb6eb80dc611c5fTinderbox User [<!ENTITY mdash "—">]>
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User - Copyright (C) 2000, 2001 Internet Software Consortium.
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews - Permission to use, copy, modify, and/or distribute this software for any
1f4c645185bd8fc70048e0a69eee46193a284e5cTinderbox User - purpose with or without fee is hereby granted, provided that the above
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - copyright notice and this permission notice appear in all copies.
02b47c5d62e1e827743684c28a08e871da454a2dMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
e20309353e6246485c521278131d3fced73d7957Tinderbox User - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
e20309353e6246485c521278131d3fced73d7957Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!-- $Id: lwres_resutil.docbook,v 1.12 2007/06/18 23:47:51 tbox Exp $ -->
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <refentryinfo>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </refentryinfo>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </copyright>
e9e4257668ff6c4e583b0c0db2508650b0b677b8Tinderbox User <refpurpose>lightweight resolver utility functions</refpurpose>
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunt </refnamediv>
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox User <refsynopsisdiv>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <funcsynopsis>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<function>lwres_string_parse</function></funcdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>char **<parameter>c</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater </funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewslwres_result_t
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrews </funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<funcprototype>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewslwres_result_t
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<function>lwres_getaddrsbyname</function></funcdef>
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <paramdef>const char *<parameter>name</parameter></paramdef>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
24934f08b9ff81c2be711e566e8002d145573031Tinderbox User <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
e20309353e6246485c521278131d3fced73d7957Tinderbox User </funcprototype>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<funcprototype>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewslwres_result_t
ad411d8ccf8a27eb903b842ab507ba6729d0246bTinderbox User<function>lwres_getnamebyaddr</function></funcdef>
80faf1588895fd26490f82f95a7a1b771df1c324Automatic Updater <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
18920d790825d96ca3943aa2dcb6eb80dc611c5fTinderbox User <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
77932ac533c711eca5cd86de4e7eca8d91102b43Tinderbox User </funcprototype>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews</funcsynopsis>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </refsynopsisdiv>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <para><function>lwres_string_parse()</function>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews retrieves a DNS-encoded string starting the current pointer of
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews lightweight resolver buffer <parameter>b</parameter>: i.e.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <constant>b->current</constant>. When the function returns,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews the address of the first byte of the encoded string is returned
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews via <parameter>*c</parameter> and the length of that string is
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews given by <parameter>*len</parameter>. The buffer's current
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson pointer is advanced to point at the character following the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews string length, the encoded string, and the trailing
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson extracts an address from the buffer <parameter>b</parameter>.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews The buffer's current pointer <constant>b->current</constant>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews is presumed to point at an encoded address: the address preceded
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews by a 32-bit protocol family identifier and a 16-bit length
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews field. The encoded address is copied to
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <constant>addr->length</constant> indicates the size in bytes
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews of the address that was copied.
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <constant>b->current</constant> is advanced to point at the
3349f0044fda807e1fd6681c833d3593a22dad86Tinderbox User next byte of available data in the buffer following the encoded
37d8e0a4455876fe1e4cca511076cc2c5ab9eedeTinderbox User <para><function>lwres_getaddrsbyname()</function>
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrews and <function>lwres_getnamebyaddr()</function> use the
2a31bd531072824ef252c18303859d6af7451b00Francis Dupont <type>lwres_gnbaresponse_t</type> structure defined below:
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewstypedef struct {
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews lwres_uint32_t flags;
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews lwres_uint16_t naliases;
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews lwres_uint16_t naddrs;
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews char *realname;
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews char **aliases;
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews lwres_uint16_t realnamelen;
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews lwres_uint16_t *aliaslen;
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews lwres_addrlist_t addrs;
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews size_t baselen;
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews} lwres_gabnresponse_t;
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews The contents of this structure are not manipulated directly but
e20788e1216ed720aefa84f3295f7899d9f28c22Mark Andrews they are controlled through the
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <citerefentry>
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews </citerefentry>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews The lightweight resolver uses
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <function>lwres_getaddrsbyname()</function> to perform
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews foward lookups.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Hostname <parameter>name</parameter> is looked up using the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews context <parameter>ctx</parameter> for memory allocation.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <parameter>addrtypes</parameter> is a bitmask indicating
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews which type of
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews addresses are to be looked up. Current values for this bitmask are
e16b482740c5e7ad4c27e271fa829b957cdf67d4Mark Andrews <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox User <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
e16b482740c5e7ad4c27e271fa829b957cdf67d4Mark Andrews lookup are returned in <parameter>*structp</parameter>.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <para><function>lwres_getnamebyaddr()</function>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews performs reverse lookups. Resolver context
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater <parameter>ctx</parameter> is used for memory allocation. The
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews address type is indicated by <parameter>addrtype</parameter>:
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews given by <parameter>addr</parameter> and its length is
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <parameter>addrlen</parameter> bytes. The result of the
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson function call is made available through
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Successful calls to
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews Both functions return
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews if the buffer is corrupt or
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson if the buffer has less space than expected for the components of the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews encoded string or address.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <para><function>lwres_getaddrsbyname()</function>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <parameter>name</parameter> could not be found.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews is returned by a successful call to
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox User when memory allocation requests fail and
7ca715ad1587a68a531ea1cdea07515d7232567eTinderbox User if the buffers used for sending queries and receiving replies are too
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrews <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
91d187ce035f39073f0732ff2a401a45c3c955fbMark Andrews </citerefentry>,
bc0a53583d92309bebcf93c408e2f3247ebd3d3cAutomatic Updater <citerefentry>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
ce9cad6bb04869c5e94d9dc721032b25117f9210Automatic Updater </citerefentry>.
59528addd704f8d5757b54e540520f74e588a7c7Automatic Updater - Local variables: