lwres_resutil.docbook revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!-- $Id: lwres_resutil.docbook,v 1.7 2005/04/07 03:50:04 marka Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refentrytitle>lwres_resutil</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver utility functions</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_string_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_addr_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint32_t addrtypes</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint32_t addrtype</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_uint16_t addrlen</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>const unsigned char *addr</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gnbaresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_string_parse()</function> retrieves a DNS-encoded
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonstring starting the current pointer of lightweight resolver buffer
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>b</parameter>: i.e. <constant>b->current</constant>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonWhen the function returns, the address of the first byte of the
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonencoded string is returned via <parameter>*c</parameter> and the
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonlength of that string is given by <parameter>*len</parameter>. The
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonbuffer's current pointer is advanced to point at the character
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the string length, the encoded string, and the trailing
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_addr_parse()</function> extracts an address from the
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonbuffer <parameter>b</parameter>. The buffer's current pointer
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<constant>b->current</constant> is presumed to point at an encoded
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonaddress: the address preceded by a 32-bit protocol family identifier
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonand a 16-bit length field. The encoded address is copied to
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<constant>addr->length</constant> indicates the size in bytes of
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonthe address that was copied. <constant>b->current</constant> is
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonadvanced to point at the next byte of available data in the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonfollowing the encoded address.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructure defined below:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naddrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *realname;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **aliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t realnamelen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t *aliaslen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addrlist_t addrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t baselen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnresponse_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe contents of this structure are not manipulated directly but
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthey are controlled through the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas GustafssonThe lightweight resolver uses
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_getaddrsbyname()</function> to perform foward lookups.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas GustafssonHostname <parameter>name</parameter> is looked up using the resolver
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssoncontext <parameter>ctx</parameter> for memory allocation.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>addrtypes</parameter> is a bitmask indicating which type of
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonaddresses are to be looked up. Current values for this bitmask are
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonlookup are returned in <parameter>*structp</parameter>.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_getnamebyaddr()</function> performs reverse lookups.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas GustafssonResolver context <parameter>ctx</parameter> is used for memory
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonallocation. The address type is indicated by
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>addrtype</parameter>: <type>LWRES_ADDRTYPE_V4</type> or
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is given
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonby <parameter>addr</parameter> and its length is
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>addrlen</parameter> bytes. The result of the function call
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonis made available through <parameter>*structp</parameter>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccessful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBoth functions return
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer is corrupt or
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer has less space than expected for the components of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonencoded string or address.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonon success and it returns
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the hostname
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncould not be found.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned by a successful call to
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhen memory allocation requests fail and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffers used for sending queries and receiving replies are too
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>.