d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

32098293b78922a5fbd10906afa28624820d3756Tinderbox User [<!ENTITY mdash "&#8212;">]>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<refentry>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentryinfo>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <date>Jun 30, 2000</date>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refentryinfo>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refmeta>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refentrytitle>lwres_gnba</refentrytitle>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <manvolnum>3</manvolnum>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refmiscinfo>BIND9</refmiscinfo>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refmeta>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <docinfo>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <copyright>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <year>2004</year>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <year>2005</year>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <year>2007</year>

af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User <holder>Internet Systems Consortium, Inc. ("ISC")</holder>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User </copyright>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <copyright>

af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User <year>2000</year>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <year>2001</year>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <holder>Internet Software Consortium.</holder>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </copyright>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </docinfo>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User <refnamediv>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <refname>lwres_gnbarequest_render</refname>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <refname>lwres_gnbaresponse_render</refname>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refname>lwres_gnbarequest_parse</refname>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <refname>lwres_gnbaresponse_parse</refname>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <refname>lwres_gnbaresponse_free</refname>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <refname>lwres_gnbarequest_free</refname>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refnamediv>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refsynopsisdiv>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <funcsynopsis>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<funcsynopsisinfo>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User#include &lt;lwres/lwres.h&gt;

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User</funcsynopsisinfo>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcprototype>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <funcdef>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userlwres_result_t

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<function>lwres_gnbarequest_render</function>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews</funcdef>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews <paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews </funcprototype>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews<funcprototype>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrews <funcdef>

48abcd3eb789fdd24a2e0a6155b25e6979a39ae0Mark Andrewslwres_result_t

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<function>lwres_gnbaresponse_render</function>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User</funcdef>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </funcprototype>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<funcprototype>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <funcdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<function>lwres_gnbarequest_parse</function></funcdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </funcprototype>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<funcprototype>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <funcdef>

af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox Userlwres_result_t

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<function>lwres_gnbaresponse_parse</function></funcdef>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </funcprototype>

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<funcprototype>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <funcdef>

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewsvoid

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<function>lwres_gnbaresponse_free</function>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein</funcdef>

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User </funcprototype>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<funcprototype>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Uservoid

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews<function>lwres_gnbarequest_free</function></funcdef>

fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </funcprototype>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User</funcsynopsis>

7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </refsynopsisdiv>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <refsect1>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <title>DESCRIPTION</title>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <para>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These are low-level routines for creating and parsing

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lightweight resolver address-to-name lookup request and

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein response messages.

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein </para>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <para>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein There are four main functions for the getnamebyaddr opcode.

71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews One render function converts a getnamebyaddr request structure &mdash;

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <type>lwres_gnbarequest_t</type> &mdash;

cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User to the lightweight resolver's canonical format.

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein It is complemented by a parse function that converts a packet in this

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein canonical format to a getnamebyaddr request structure.

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Another render function converts the getnamebyaddr response structure

350e5eecadfc5ee72b11b2cc46828c9a0bcd717cTinderbox User &mdash;

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <type>lwres_gnbaresponse_t</type>

60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein to the canonical format.

This is complemented by a parse function which converts a packet in

canonical format to a getnamebyaddr response structure.

</para>

<para>

These structures are defined in

<filename>lwres/lwres.h</filename>.

They are shown below.

</para>

<para><programlisting>

#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U

</programlisting>

</para>

<para><programlisting>

typedef struct {

lwres_uint32_t flags;

lwres_addr_t addr;

} lwres_gnbarequest_t;

</programlisting>

</para>

<para><programlisting>

typedef struct {

lwres_uint32_t flags;

lwres_uint16_t naliases;

char *realname;

char **aliases;

lwres_uint16_t realnamelen;

lwres_uint16_t *aliaslen;

void *base;

size_t baselen;

} lwres_gnbaresponse_t;

</programlisting>

</para>

<para><function>lwres_gnbarequest_render()</function>

uses resolver context <varname>ctx</varname> to convert

getnamebyaddr request structure <varname>req</varname> to

canonical format. The packet header structure

<varname>pkt</varname> is initialised and transferred to buffer

<varname>b</varname>. The contents of <varname>*req</varname>

are then appended to the buffer in canonical format.

<function>lwres_gnbaresponse_render()</function> performs the

same task, except it converts a getnamebyaddr response structure

<type>lwres_gnbaresponse_t</type> to the lightweight resolver's

canonical format.

</para>

<para><function>lwres_gnbarequest_parse()</function>

uses context <varname>ctx</varname> to convert the contents of

packet <varname>pkt</varname> to a

<type>lwres_gnbarequest_t</type> structure. Buffer

<varname>b</varname> provides space to be used for storing this

structure. When the function succeeds, the resulting

<type>lwres_gnbarequest_t</type> is made available through

<varname>*structp</varname>.

<function>lwres_gnbaresponse_parse()</function> offers the same

semantics as <function>lwres_gnbarequest_parse()</function>

except it yields a <type>lwres_gnbaresponse_t</type> structure.

</para>

<para><function>lwres_gnbaresponse_free()</function>

and <function>lwres_gnbarequest_free()</function> release the

memory in resolver context <varname>ctx</varname> that was

allocated to the <type>lwres_gnbaresponse_t</type> or

<type>lwres_gnbarequest_t</type> structures referenced via

<varname>structp</varname>. Any memory associated with

ancillary buffers and strings for those structures is also

discarded.

</para>

</refsect1>

<refsect1>

<title>RETURN VALUES</title>

<para>

The getnamebyaddr opcode functions

<function>lwres_gnbarequest_render()</function>,

<function>lwres_gnbaresponse_render()</function>

<function>lwres_gnbarequest_parse()</function>

and

<function>lwres_gnbaresponse_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

<varname>b</varname>

is too small to accommodate the packet header or the

<type>lwres_gnbarequest_t</type>

and

<type>lwres_gnbaresponse_t</type>

structures.

<function>lwres_gnbarequest_parse()</function>

and

<function>lwres_gnbaresponse_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><!--