]>

 - Copyright (C) Internet Systems Consortium, Inc. ("ISC")

 -

 - This Source Code Form is subject to the terms of the Mozilla Public

 - License, v. 2.0. If a copy of the MPL was not distributed with this

 - file, you can obtain one at https://mozilla.org/MPL/2.0/.

 -

 - See the COPYRIGHT file distributed with this work for additional

 - information regarding copyright ownership.

-->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">

  <info>

    <date>2007-06-18</date>

  </info>

  <refentryinfo>

    <corpname>ISC</corpname>

    <corpauthor>Internet Systems Consortium, Inc.</corpauthor>

  </refentryinfo>

  <refmeta>

    <refentrytitle>lwres_gabn</refentrytitle>

    <manvolnum>3</manvolnum>

    <refmiscinfo>BIND9</refmiscinfo>

  </refmeta>

  <docinfo>

    <copyright>

      <year>2000</year>

      <year>2001</year>

      <year>2004</year>

      <year>2005</year>

      <year>2007</year>

      <year>2014</year>

      <year>2015</year>

      <year>2016</year>

      <year>2018</year>

      <year>2019</year>

      <year>2020</year>

      <holder>Internet Systems Consortium, Inc. ("ISC")</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 <lwres/lwres.h></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>

  <refsection><info><title>DESCRIPTION</title></info>

    <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 —

      <type>lwres_gabnrequest_t</type> —

      to the lightweight 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

      — <type>lwres_gabnresponse_t</type> —

      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><lwres/lwres.h></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 {

        uint32_t  flags;

        uint32_t  addrtypes;

        uint16_t  namelen;

        char           *name;

} lwres_gabnrequest_t;

</programlisting>

    </para>

    <para><programlisting>

typedef struct {

        uint32_t          flags;

        uint16_t          naliases;

        uint16_t          naddrs;

        char                   *realname;

        char                  **aliases;

        uint16_t          realnamelen;

        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>

  </refsection>

  <refsection><info><title>RETURN VALUES</title></info>

    <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

      <varname remap="structfield">pktflags</varname>

      in the packet header structure

      <type>lwres_lwpacket_t</type>

      indicate that the packet is not a response to an earlier query.

    </para>

  </refsection>

  <refsection><info><title>SEE ALSO</title></info>

    <para><citerefentry>

        <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>

      </citerefentry>

    </para>

  </refsection>

</refentry>