<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	       [<!ENTITY mdash "&#8212;">]>
<!--
 - Copyright (C) 2004, 2005, 2007, 2012  Internet Systems Consortium, Inc. ("ISC")
 - Copyright (C) 2000, 2001  Internet Software Consortium.
 -
 - Permission to use, copy, modify, and/or distribute this software for any
 - purpose with or without fee is hereby granted, provided that the above
 - copyright notice and this permission notice appear in all copies.
 -
 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 - PERFORMANCE OF THIS SOFTWARE.
-->

<!-- $Id$ -->
<refentry>

  <refentryinfo>
    <date>Jun 30, 2000</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>lwres_resutil</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>BIND9</refmiscinfo>
  </refmeta>

  <docinfo>
    <copyright>
      <year>2004</year>
      <year>2005</year>
      <year>2007</year>
      <year>2012</year>
      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
    </copyright>
    <copyright>
      <year>2000</year>
      <year>2001</year>
      <holder>Internet Software Consortium.</holder>
    </copyright>
  </docinfo>

  <refnamediv>
    <refname>lwres_string_parse</refname>
    <refname>lwres_addr_parse</refname>
    <refname>lwres_getaddrsbyname</refname>
    <refname>lwres_getnamebyaddr</refname>
    <refpurpose>lightweight resolver utility functions</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_string_parse</function></funcdef>
        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
        <paramdef>char **<parameter>c</parameter></paramdef>
        <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_addr_parse</function></funcdef>
        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
        <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_getaddrsbyname</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>const char *<parameter>name</parameter></paramdef>
        <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef>
        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_getnamebyaddr</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef>
        <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef>
        <paramdef>const unsigned char *<parameter>addr</parameter></paramdef>
        <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
      </funcprototype>
</funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para><function>lwres_string_parse()</function>
      retrieves a DNS-encoded string starting the current pointer of
      lightweight resolver buffer <parameter>b</parameter>: i.e.
      <constant>b-&gt;current</constant>.  When the function returns,
      the address of the first byte of the encoded string is returned
      via <parameter>*c</parameter> and the length of that string is
      given by <parameter>*len</parameter>.  The buffer's current
      pointer is advanced to point at the character following the
      string length, the encoded string, and the trailing
      <type>NULL</type> character.
    </para>

    <para><function>lwres_addr_parse()</function>
      extracts an address from the buffer <parameter>b</parameter>.
      The buffer's current pointer <constant>b-&gt;current</constant>
      is presumed to point at an encoded address: the address preceded
      by a 32-bit protocol family identifier and a 16-bit length
      field.  The encoded address is copied to
      <constant>addr-&gt;address</constant> and
      <constant>addr-&gt;length</constant> indicates the size in bytes
      of the address that was copied.
      <constant>b-&gt;current</constant> is advanced to point at the
      next byte of available data in the buffer following the encoded
      address.
    </para>

    <para><function>lwres_getaddrsbyname()</function>
      and <function>lwres_getnamebyaddr()</function> use the
      <type>lwres_gnbaresponse_t</type> structure defined below:
    </para>

<para><programlisting>
typedef struct {
        lwres_uint32_t          flags;
        lwres_uint16_t          naliases;
        lwres_uint16_t          naddrs;
        char                   *realname;
        char                  **aliases;
        lwres_uint16_t          realnamelen;
        lwres_uint16_t         *aliaslen;
        lwres_addrlist_t        addrs;
        void                   *base;
        size_t                  baselen;
} lwres_gabnresponse_t;
</programlisting></para>

    <para>
      The contents of this structure are not manipulated directly but
      they are controlled through the
      <citerefentry>
        <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
      functions.
    </para>

    <para>
      The lightweight resolver uses
      <function>lwres_getaddrsbyname()</function> to perform
      foward lookups.
      Hostname <parameter>name</parameter> is looked up using the
      resolver
      context <parameter>ctx</parameter> for memory allocation.
      <parameter>addrtypes</parameter> is a bitmask indicating
      which type of
      addresses are to be looked up.  Current values for this bitmask are
      <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
      <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses.  Results of the
      lookup are returned in <parameter>*structp</parameter>.
    </para>

    <para><function>lwres_getnamebyaddr()</function>
      performs reverse lookups.  Resolver context
      <parameter>ctx</parameter> is used for memory allocation.  The
      address type is indicated by <parameter>addrtype</parameter>:
      <type>LWRES_ADDRTYPE_V4</type> or
      <type>LWRES_ADDRTYPE_V6</type>.  The address to be looked up is
      given by <parameter>addr</parameter> and its length is
      <parameter>addrlen</parameter> bytes.  The result of the
      function call is made available through
      <parameter>*structp</parameter>.
    </para>
  </refsect1>

  <refsect1>
    <title>RETURN VALUES</title>
    <para>
      Successful calls to
      <function>lwres_string_parse()</function>
      and
      <function>lwres_addr_parse()</function>
      return
      <errorcode>LWRES_R_SUCCESS.</errorcode>
      Both functions return
      <errorcode>LWRES_R_FAILURE</errorcode>
      if the buffer is corrupt or
      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
      if the buffer has less space than expected for the components of the
      encoded string or address.
    </para>

    <para><function>lwres_getaddrsbyname()</function>
      returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it
      returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname
      <parameter>name</parameter> could not be found.
    </para>
    <para><errorcode>LWRES_R_SUCCESS</errorcode>
      is returned by a successful call to
      <function>lwres_getnamebyaddr()</function>.
    </para>

    <para>
      Both
      <function>lwres_getaddrsbyname()</function>
      and
      <function>lwres_getnamebyaddr()</function>
      return
      <errorcode>LWRES_R_NOMEMORY</errorcode>
      when memory allocation requests fail and
      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
      if the buffers used for sending queries and receiving replies are too
      small.
    </para>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para><citerefentry>
        <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,

      <citerefentry>
        <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>.
    </para>

  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->