lwres_resutil.docbook revision f5d30e2864e048a42c4dc1134993ae7efdb5d6c3
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein [<!ENTITY mdash "—">]>
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.
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews<!-- $Id: lwres_resutil.docbook,v 1.9 2005/05/13 01:35:48 marka Exp $ -->
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver utility functions</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_string_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>char **<parameter>c</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_addr_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getaddrsbyname</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const char *<parameter>name</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_getnamebyaddr</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein retrieves a DNS-encoded string starting the current pointer of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver buffer <parameter>b</parameter>: i.e.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>b->current</constant>. When the function returns,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the address of the first byte of the encoded string is returned
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein via <parameter>*c</parameter> and the length of that string is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein given by <parameter>*len</parameter>. The buffer's current
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein pointer is advanced to point at the character following the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein string length, the encoded string, and the trailing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein extracts an address from the buffer <parameter>b</parameter>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The buffer's current pointer <constant>b->current</constant>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is presumed to point at an encoded address: the address preceded
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein by a 32-bit protocol family identifier and a 16-bit length
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein field. The encoded address is copied to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>addr->length</constant> indicates the size in bytes
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein of the address that was copied.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <constant>b->current</constant> is advanced to point at the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein next byte of available data in the buffer following the encoded
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getaddrsbyname()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and <function>lwres_getnamebyaddr()</function> use the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gnbaresponse_t</type> structure defined below:
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;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The contents of this structure are not manipulated directly but
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein they are controlled through the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The lightweight resolver uses
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_getaddrsbyname()</function> to perform
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein foward lookups.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Hostname <parameter>name</parameter> is looked up using the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein context <parameter>ctx</parameter> for memory allocation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>addrtypes</parameter> is a bitmask indicating
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein which type of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein addresses are to be looked up. Current values for this bitmask are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lookup are returned in <parameter>*structp</parameter>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getnamebyaddr()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein performs reverse lookups. Resolver context
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>ctx</parameter> is used for memory allocation. The
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein address type is indicated by <parameter>addrtype</parameter>:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein given by <parameter>addr</parameter> and its length is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>addrlen</parameter> bytes. The result of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein function call is made available through
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Successful calls to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Both functions return
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffer is corrupt or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffer has less space than expected for the components of the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein encoded string or address.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_getaddrsbyname()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned by a successful call to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein when memory allocation requests fail and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffers used for sending queries and receiving replies are too
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Local variables:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - mode: sgml