<!DOCTYPE book [

<!ENTITY mdash "&#8212;">]>

<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>2004</year>

<year>2005</year>

<year>2007</year>

<year>2014</year>

<year>2015</year>

<year>2016</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>

<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 &mdash;

<type>lwres_gabnrequest_t</type> &mdash;

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

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

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