lwres_resutil.docbook revision ec5347e2c775f027573ce5648b910361aa926c01
4d237bbe075b1d2c19428cd954d721d65b31f67cwrowe<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
ec79b29695b183f794264bbb578c51e93d1f9b1emartin "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
1a5f954324f2584984fc9cee7a7a8ebe8ef39aeajim [<!ENTITY mdash "—">]>
6951fc02abfd7642e45333902c14855836717fadrpluem - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
6951fc02abfd7642e45333902c14855836717fadrpluem - Copyright (C) 2000, 2001 Internet Software Consortium.
6951fc02abfd7642e45333902c14855836717fadrpluem - Permission to use, copy, modify, and/or distribute this software for any
6951fc02abfd7642e45333902c14855836717fadrpluem - purpose with or without fee is hereby granted, provided that the above
9f8f1913ecffb74c74e1136a1dfa5ec6ea7452fbcovener - copyright notice and this permission notice appear in all copies.
9f8f1913ecffb74c74e1136a1dfa5ec6ea7452fbcovener - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9f8f1913ecffb74c74e1136a1dfa5ec6ea7452fbcovener - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
aced0f6381ba4b9ec6ca8b9f9253f5aeb1a0b1actdonovan - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
aced0f6381ba4b9ec6ca8b9f9253f5aeb1a0b1actdonovan - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
aced0f6381ba4b9ec6ca8b9f9253f5aeb1a0b1actdonovan - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
f66adfbe73a6cbad477dd15b02e3eb7cb3779244rpluem - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
f66adfbe73a6cbad477dd15b02e3eb7cb3779244rpluem - PERFORMANCE OF THIS SOFTWARE.
db455cbc662c98dbbf53175393c50086ff63370cchrisd<!-- $Id: lwres_resutil.docbook,v 1.12 2007/06/18 23:47:51 tbox Exp $ -->
db455cbc662c98dbbf53175393c50086ff63370cchrisd <refentryinfo>
2e242dca7111f99d54dd144b7b8418d88d560032chrisd </refentryinfo>
b5d91f803b61ef5b13666e423173eb72d96f8938niq </refmeta>
b6b1df87b7ce62620d48526a7ab630897cdaad90chrisd <copyright>
4cf58054a85830c67dc23890ee613f62e1f7bdc8minfrin <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
4cf58054a85830c67dc23890ee613f62e1f7bdc8minfrin </copyright>
4cf58054a85830c67dc23890ee613f62e1f7bdc8minfrin <copyright>
caaa32f2d2e3b28063c745c2632d3979da7f8326minfrin </copyright>
caaa32f2d2e3b28063c745c2632d3979da7f8326minfrin <refnamediv>
e02cb8f5090d904c054633ff33dfd1111e16e404minfrin <refpurpose>lightweight resolver utility functions</refpurpose>
66a8e1cc29cc4612cd938bc8fcabc0ef569e5769rpluem </refnamediv>
e02cb8f5090d904c054633ff33dfd1111e16e404minfrin <refsynopsisdiv>
8a3e2ef19ddfb8addcccdc61da0d1442695a8280rpluem <funcsynopsis>
8a3e2ef19ddfb8addcccdc61da0d1442695a8280rpluem<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
8a3e2ef19ddfb8addcccdc61da0d1442695a8280rpluem<funcprototype>
213e520edc00641400771fc8f90b37a967a2d9ebdirkxlwres_result_t
213e520edc00641400771fc8f90b37a967a2d9ebdirkx <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
a449830d5caa5b9900fe64cc383658b3641f9810dirkx <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
a449830d5caa5b9900fe64cc383658b3641f9810dirkx </funcprototype>
a449830d5caa5b9900fe64cc383658b3641f9810dirkx<funcprototype>
a449830d5caa5b9900fe64cc383658b3641f9810dirkxlwres_result_t
a449830d5caa5b9900fe64cc383658b3641f9810dirkx <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
a449830d5caa5b9900fe64cc383658b3641f9810dirkx <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
06d3a46db9574ad55b65fed36b856fee72bd71a7rpluem </funcprototype>
06d3a46db9574ad55b65fed36b856fee72bd71a7rpluem<funcprototype>
82632a19f2f9c346fee2b28a65920ba9737b3973minfrinlwres_result_t
82632a19f2f9c346fee2b28a65920ba9737b3973minfrin <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
82632a19f2f9c346fee2b28a65920ba9737b3973minfrin <paramdef>const char *<parameter>name</parameter></paramdef>
82632a19f2f9c346fee2b28a65920ba9737b3973minfrin <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
0481ff0599c9e3c0c7ad5c1930939dcdac908582chrisd <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
0481ff0599c9e3c0c7ad5c1930939dcdac908582chrisd </funcprototype>
0481ff0599c9e3c0c7ad5c1930939dcdac908582chrisd<funcprototype>
835d676191444a46d695171e8760d55a66c60fecminfrinlwres_result_t
835d676191444a46d695171e8760d55a66c60fecminfrin <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
723f9f463f1922eaef3d24d00cb289e10daa73ffminfrin <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
723f9f463f1922eaef3d24d00cb289e10daa73ffminfrin <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
723f9f463f1922eaef3d24d00cb289e10daa73ffminfrin <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
723f9f463f1922eaef3d24d00cb289e10daa73ffminfrin <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
c2213b3a46a2666e2e7606ceec509cc4978f187fminfrin </funcprototype>
c2213b3a46a2666e2e7606ceec509cc4978f187fminfrin</funcsynopsis>
c2213b3a46a2666e2e7606ceec509cc4978f187fminfrin </refsynopsisdiv>
fd279fe992f7171dc3f6d4d40d6db5bb74f2d96eminfrin retrieves a DNS-encoded string starting the current pointer of
fd279fe992f7171dc3f6d4d40d6db5bb74f2d96eminfrin lightweight resolver buffer <parameter>b</parameter>: i.e.
fd279fe992f7171dc3f6d4d40d6db5bb74f2d96eminfrin <constant>b->current</constant>. When the function returns,
fed63d1b62cc7e56aad77b70ee5b5cc7f5c6aademinfrin the address of the first byte of the encoded string is returned
fed63d1b62cc7e56aad77b70ee5b5cc7f5c6aademinfrin via <parameter>*c</parameter> and the length of that string is
fed63d1b62cc7e56aad77b70ee5b5cc7f5c6aademinfrin given by <parameter>*len</parameter>. The buffer's current
fed63d1b62cc7e56aad77b70ee5b5cc7f5c6aademinfrin pointer is advanced to point at the character following the
fed63d1b62cc7e56aad77b70ee5b5cc7f5c6aademinfrin string length, the encoded string, and the trailing
abe0d0e38b9705f21a13ac8748bce1e3ed35e488minfrin extracts an address from the buffer <parameter>b</parameter>.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin The buffer's current pointer <constant>b->current</constant>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin is presumed to point at an encoded address: the address preceded
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin by a 32-bit protocol family identifier and a 16-bit length
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin field. The encoded address is copied to
a72211e92bab814bfa28ee086ca9b2a1a6095c92chrisd <constant>addr->length</constant> indicates the size in bytes
a72211e92bab814bfa28ee086ca9b2a1a6095c92chrisd of the address that was copied.
a72211e92bab814bfa28ee086ca9b2a1a6095c92chrisd <constant>b->current</constant> is advanced to point at the
a72211e92bab814bfa28ee086ca9b2a1a6095c92chrisd next byte of available data in the buffer following the encoded
9582ad6e149d28b118d4e8571101ecb6f85e0191niq <type>lwres_gnbaresponse_t</type> structure defined below:
d56bacbfefa5aa883ce5162a115747372fc38d13chrisdtypedef struct {
d56bacbfefa5aa883ce5162a115747372fc38d13chrisd lwres_uint32_t flags;
d56bacbfefa5aa883ce5162a115747372fc38d13chrisd lwres_uint16_t naliases;
d56bacbfefa5aa883ce5162a115747372fc38d13chrisd lwres_uint16_t naddrs;
d64dd2fd4516c2b1b664c5e59c0628d9aff26984covener char *realname;
d64dd2fd4516c2b1b664c5e59c0628d9aff26984covener char **aliases;
d64dd2fd4516c2b1b664c5e59c0628d9aff26984covener lwres_uint16_t realnamelen;
ed0d39878e79220baaa50c15b79b1fdf877cb919niq lwres_uint16_t *aliaslen;
1e911973bcb9df6701a4c16c037771ecf25ade13niq lwres_addrlist_t addrs;
1e911973bcb9df6701a4c16c037771ecf25ade13niq void *base;
1e911973bcb9df6701a4c16c037771ecf25ade13niq size_t baselen;
1e911973bcb9df6701a4c16c037771ecf25ade13niq} lwres_gabnresponse_t;
e47d58d5d983426584c8d16416c50f5c58070746dirkx The contents of this structure are not manipulated directly but
e47d58d5d983426584c8d16416c50f5c58070746dirkx they are controlled through the
e47d58d5d983426584c8d16416c50f5c58070746dirkx <citerefentry>
33aad3911b15cb5d523075f7df829274fe298a13dirkx <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
33aad3911b15cb5d523075f7df829274fe298a13dirkx </citerefentry>
433dcb1fbaae82d36634f5120bff71a04296904ddirkx The lightweight resolver uses
433dcb1fbaae82d36634f5120bff71a04296904ddirkx <function>lwres_getaddrsbyname()</function> to perform
433dcb1fbaae82d36634f5120bff71a04296904ddirkx foward lookups.
433dcb1fbaae82d36634f5120bff71a04296904ddirkx Hostname <parameter>name</parameter> is looked up using the
d7fcc79b0bee660d71b0cccfe9bbc2765ee6420erederpj context <parameter>ctx</parameter> for memory allocation.
d7fcc79b0bee660d71b0cccfe9bbc2765ee6420erederpj <parameter>addrtypes</parameter> is a bitmask indicating
d7fcc79b0bee660d71b0cccfe9bbc2765ee6420erederpj which type of
d7fcc79b0bee660d71b0cccfe9bbc2765ee6420erederpj addresses are to be looked up. Current values for this bitmask are
d7fcc79b0bee660d71b0cccfe9bbc2765ee6420erederpj <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
cb9999606fbbda475b7b40e164699731521e9eb1niq <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx performs reverse lookups. Resolver context
40beb03c240a9c60805388592f1005d9bf9d2362fuankg <parameter>ctx</parameter> is used for memory allocation. The
65cb7f00eca6689c8a89dc809359991ade1285bcwrowe address type is indicated by <parameter>addrtype</parameter>:
65cb7f00eca6689c8a89dc809359991ade1285bcwrowe <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
65cb7f00eca6689c8a89dc809359991ade1285bcwrowe given by <parameter>addr</parameter> and its length is
65cb7f00eca6689c8a89dc809359991ade1285bcwrowe <parameter>addrlen</parameter> bytes. The result of the
39c7699ec0799d394d3f67145d4a12ed82f587b8jorton function call is made available through
c6d33447e28403a90ad817dba4df75fae785be28pquerna </refsect1>
439ccf2a084e1da566548931c585cbcc3a9e7f4cminfrin Successful calls to
795c9499a77c25695bcb9710ed67bbe51492e181rpluem Both functions return
a72ba68ecbbc61e4b513e50d6000245c33f753dcwrowe if the buffer is corrupt or
7a079e0cd696baca90ac43e325f64582e2945c68wrowe if the buffer has less space than expected for the components of the
a72ba68ecbbc61e4b513e50d6000245c33f753dcwrowe encoded string or address.
ecc1538af1c08282fc2773d2eb3f1a54251862f9minfrin returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
ecc1538af1c08282fc2773d2eb3f1a54251862f9minfrin returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
3f5585f7f4a7d74f2f94ec729ea8c1879d419e35rederpj is returned by a successful call to
108ebbb87b2a46f4416ec507824471a483c39fe1sctemme when memory allocation requests fail and
108ebbb87b2a46f4416ec507824471a483c39fe1sctemme if the buffers used for sending queries and receiving replies are too
10d486b9267800c5e376c22f6c0d45dc2ae86f67chrisd </refsect1>
3e155218733389e7b1ea3a9ffd0aea533fd929cechrisd <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
3e155218733389e7b1ea3a9ffd0aea533fd929cechrisd </citerefentry>,
3e155218733389e7b1ea3a9ffd0aea533fd929cechrisd <citerefentry>
dd6199828976e6c7850ca6abd7a1ceba99e9ed16chrisd <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
dd6199828976e6c7850ca6abd7a1ceba99e9ed16chrisd </citerefentry>.
ab43b4a17b2ac31ccb1cf280be8c42a8a314cecbjorton </refsect1>
ab43b4a17b2ac31ccb1cf280be8c42a8a314cecbjorton - Local variables:
67139e2d50d1e11558d87f7042f61cb04bb0d1d2jim - mode: sgml