<!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_gabn</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_gabnrequest_render</refname>
    <refname>lwres_gabnresponse_render</refname>
    <refname>lwres_gabnrequest_parse</refname>
    <refname>lwres_gabnresponse_parse</refname>
    <refname>lwres_gabnresponse_free</refname>
    <refname>lwres_gabnrequest_free</refname>
    <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_gabnrequest_render</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_gabnresponse_render</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_gabnrequest_parse</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
        <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
lwres_result_t
<function>lwres_gabnresponse_parse</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
void
<function>lwres_gabnresponse_free</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
        </funcprototype>
<funcprototype>
        <funcdef>
void
<function>lwres_gabnrequest_free</function></funcdef>
        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
        <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
      </funcprototype>
</funcsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>
    <para>
      These are low-level routines for creating and parsing
      lightweight resolver name-to-address lookup request and
      response messages.
    </para>
    <para>
      There are four main functions for the getaddrbyname opcode.
      One render function converts a getaddrbyname request structure &mdash;
      <type>lwres_gabnrequest_t</type> &mdash;
      to the lighweight resolver's canonical format.
      It is complemented by a parse function that converts a packet in this
      canonical format to a getaddrbyname request structure.
      Another render function converts the getaddrbyname response structure
      &mdash; <type>lwres_gabnresponse_t</type> &mdash;
      to the canonical format.
      This is complemented by a parse function which converts a packet in
      canonical format to a getaddrbyname response structure.
    </para>
    <para>
      These structures are defined in
      <filename>&lt;lwres/lwres.h&gt;</filename>.
      They are shown below.
    </para>
    <para><programlisting>
#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
</programlisting>
    </para>
    <para><programlisting>
typedef struct lwres_addr lwres_addr_t;
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
</programlisting>
    </para>
    <para><programlisting>
typedef struct {
        lwres_uint32_t  flags;
        lwres_uint32_t  addrtypes;
        lwres_uint16_t  namelen;
        char           *name;
} lwres_gabnrequest_t;
</programlisting>
    </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><function>lwres_gabnrequest_render()</function>
      uses resolver context <parameter>ctx</parameter> to convert
      getaddrbyname request structure <parameter>req</parameter> to
      canonical format.  The packet header structure
      <parameter>pkt</parameter> is initialised and transferred to
      buffer <parameter>b</parameter>.

      The contents of <parameter>*req</parameter> are then appended to
      the buffer in canonical format.
      <function>lwres_gabnresponse_render()</function> performs the
      same task, except it converts a getaddrbyname response structure
      <type>lwres_gabnresponse_t</type> to the lightweight resolver's
      canonical format.
    </para>

    <para><function>lwres_gabnrequest_parse()</function>
      uses context <parameter>ctx</parameter> to convert the contents
      of packet <parameter>pkt</parameter> to a
      <type>lwres_gabnrequest_t</type> structure.  Buffer
      <parameter>b</parameter> provides space to be used for storing
      this structure.  When the function succeeds, the resulting
      <type>lwres_gabnrequest_t</type> is made available through
      <parameter>*structp</parameter>.

      <function>lwres_gabnresponse_parse()</function> offers the same
      semantics as <function>lwres_gabnrequest_parse()</function>
      except it yields a <type>lwres_gabnresponse_t</type> structure.
    </para>

    <para><function>lwres_gabnresponse_free()</function>
      and <function>lwres_gabnrequest_free()</function> release the
      memory in resolver context <parameter>ctx</parameter> that was
      allocated to the <type>lwres_gabnresponse_t</type> or
      <type>lwres_gabnrequest_t</type> structures referenced via
      <parameter>structp</parameter>.

      Any memory associated with ancillary buffers and strings for
      those structures is also discarded.
    </para>
  </refsect1>
  <refsect1>
    <title>RETURN VALUES</title>
    <para>
      The getaddrbyname opcode functions
      <function>lwres_gabnrequest_render()</function>,
      <function>lwres_gabnresponse_render()</function>
      <function>lwres_gabnrequest_parse()</function>
      and
      <function>lwres_gabnresponse_parse()</function>
      all return
      <errorcode>LWRES_R_SUCCESS</errorcode>
      on success.
      They return
      <errorcode>LWRES_R_NOMEMORY</errorcode>
      if memory allocation fails.
      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
      is returned if the available space in the buffer
      <parameter>b</parameter>
      is too small to accommodate the packet header or the
      <type>lwres_gabnrequest_t</type>
      and
      <type>lwres_gabnresponse_t</type>
      structures.
      <function>lwres_gabnrequest_parse()</function>
      and
      <function>lwres_gabnresponse_parse()</function>
      will return
      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
      if the buffer is not empty after decoding the received packet.
      These functions will return
      <errorcode>LWRES_R_FAILURE</errorcode>
      if
      <structfield>pktflags</structfield>
      in the packet header structure
      <type>lwres_lwpacket_t</type>
      indicate that the packet is not a response to an earlier query.
    </para>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para><citerefentry>
        <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry><!--
 - Local variables:
 - mode: sgml
 - End:
-->