lwres_resutil.docbook revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - Copyright (C) 2000, 2001 Internet Software Consortium.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - Permission to use, copy, modify, and distribute this software for any
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - purpose with or without fee is hereby granted, provided that the above
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - copyright notice and this permission notice appear in all copies.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor - PERFORMANCE OF THIS SOFTWARE.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<!-- $Id: lwres_resutil.docbook,v 1.7 2005/04/07 03:50:04 marka Exp $ -->
1ed53a3f65abecaadc1b967e341970ad0f6b2aebBill Taylor<refentryinfo>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</refentryinfo>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<refpurpose>lightweight resolver utility functions</refpurpose>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</refnamediv>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<refsynopsisdiv>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<funcsynopsis>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorlwres_result_t
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_string_parse</function></funcdef>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorlwres_result_t
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorlwres_result_t
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_getaddrsbyname</function></funcdef>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<paramdef>lwres_gabnresponse_t **structp</paramdef>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorlwres_result_t
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_getnamebyaddr</function></funcdef>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<paramdef>lwres_gnbaresponse_t **structp</paramdef>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</funcprototype>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</funcsynopsis>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</refsynopsisdiv>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_string_parse()</function> retrieves a DNS-encoded
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorstring starting the current pointer of lightweight resolver buffer
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<parameter>b</parameter>: i.e. <constant>b->current</constant>.
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorWhen the function returns, the address of the first byte of the
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorencoded string is returned via <parameter>*c</parameter> and the
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorlength of that string is given by <parameter>*len</parameter>. The
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorbuffer's current pointer is advanced to point at the character
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorfollowing the string length, the encoded string, and the trailing
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_addr_parse()</function> extracts an address from the
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorbuffer <parameter>b</parameter>. The buffer's current pointer
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<constant>b->current</constant> is presumed to point at an encoded
9e39c5ba00a55fa05777cc94b148296af305e135Bill Tayloraddress: the address preceded by a 32-bit protocol family identifier
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorand a 16-bit length field. The encoded address is copied to
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<constant>addr->length</constant> indicates the size in bytes of
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorthe address that was copied. <constant>b->current</constant> is
9e39c5ba00a55fa05777cc94b148296af305e135Bill Tayloradvanced to point at the next byte of available data in the buffer
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorfollowing the encoded address.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorstructure defined below:
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<programlisting>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylortypedef struct {
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor lwres_uint32_t flags;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor lwres_uint16_t naliases;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor lwres_uint16_t naddrs;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor char *realname;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor char **aliases;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor lwres_uint16_t realnamelen;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor lwres_uint16_t *aliaslen;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor lwres_addrlist_t addrs;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor size_t baselen;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor} lwres_gabnresponse_t;
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</programlisting>
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorThe contents of this structure are not manipulated directly but
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorthey are controlled through the
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<citerefentry>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</citerefentry>
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorThe lightweight resolver uses
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_getaddrsbyname()</function> to perform foward lookups.
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorHostname <parameter>name</parameter> is looked up using the resolver
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorcontext <parameter>ctx</parameter> for memory allocation.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<parameter>addrtypes</parameter> is a bitmask indicating which type of
9e39c5ba00a55fa05777cc94b148296af305e135Bill Tayloraddresses are to be looked up. Current values for this bitmask are
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorlookup are returned in <parameter>*structp</parameter>.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<function>lwres_getnamebyaddr()</function> performs reverse lookups.
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorResolver context <parameter>ctx</parameter> is used for memory
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorallocation. The address type is indicated by
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<parameter>addrtype</parameter>: <type>LWRES_ADDRTYPE_V4</type> or
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is given
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<parameter>addrlen</parameter> bytes. The result of the function call
9e39c5ba00a55fa05777cc94b148296af305e135Bill Tayloris made available through <parameter>*structp</parameter>.
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorSuccessful calls to
9e39c5ba00a55fa05777cc94b148296af305e135Bill TaylorBoth functions return
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorif the buffer is corrupt or
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorif the buffer has less space than expected for the components of the
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorencoded string or address.
9e39c5ba00a55fa05777cc94b148296af305e135Bill Tayloron success and it returns
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorif the hostname
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorcould not be found.
1ed53a3f65abecaadc1b967e341970ad0f6b2aebBill Tayloris returned by a successful call to
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorwhen memory allocation requests fail and
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylorif the buffers used for sending queries and receiving replies are too
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<citerefentry>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</citerefentry>,
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<citerefentry>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
9e39c5ba00a55fa05777cc94b148296af305e135Bill Taylor</citerefentry>.