bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refentry>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refentryinfo>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore

0dc2366f7b9f9f36e10909b1e95edbf2a261c2acVenugopal Iyer

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<date>Jun 30, 2000</date>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</refentryinfo>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refmeta>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refentrytitle>lwres_gabn</refentrytitle>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<manvolnum>3</manvolnum>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refmiscinfo>BIND9</refmiscinfo>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</refmeta>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refnamediv>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refname>lwres_gabnrequest_render</refname>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refname>lwres_gabnresponse_render</refname>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refname>lwres_gabnrequest_parse</refname>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refname>lwres_gabnresponse_parse</refname>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refname>lwres_gabnresponse_free</refname>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refname>lwres_gabnrequest_free</refname>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</refnamediv>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<refsynopsisdiv>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcsynopsis>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcsynopsisinfo>#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amorelwres_result_t

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<function>lwres_gabnrequest_render</function></funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_context_t *ctx</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_gabnrequest_t *req</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_lwpacket_t *pkt</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_buffer_t *b</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amorelwres_result_t

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<function>lwres_gabnresponse_render</function></funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_context_t *ctx</paramdef>

0dc2366f7b9f9f36e10909b1e95edbf2a261c2acVenugopal Iyer<paramdef>lwres_gabnresponse_t *req</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_lwpacket_t *pkt</paramdef>

7014882c6a3672fd0e5d60200af8643ae53c5928Richard Lowe<paramdef>lwres_buffer_t *b</paramdef>

7014882c6a3672fd0e5d60200af8643ae53c5928Richard Lowe</funcprototype>

7014882c6a3672fd0e5d60200af8643ae53c5928Richard Lowe<funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amorelwres_result_t

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<function>lwres_gabnrequest_parse</function></funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_context_t *ctx</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_buffer_t *b</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_lwpacket_t *pkt</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_gabnrequest_t **structp</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amorelwres_result_t

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<function>lwres_gabnresponse_parse</function></funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_context_t *ctx</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_buffer_t *b</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_lwpacket_t *pkt</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_gabnresponse_t **structp</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amorevoid

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<function>lwres_gabnresponse_free</function></funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_context_t *ctx</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<paramdef>lwres_gabnresponse_t **structp</paramdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore</funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcprototype>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amore<funcdef>

bdb9230ac765cb7af3fc1f4119caf2c5720dceb3Garrett D'Amorevoid

<function>lwres_gabnrequest_free</function></funcdef>

<paramdef>lwres_context_t *ctx</paramdef>

<paramdef>lwres_gabnrequest_t **structp</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.

<programlisting>

#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U

typedef struct lwres_addr lwres_addr_t;

typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;

typedef struct {

lwres_uint32_t flags;

lwres_uint32_t addrtypes;

lwres_uint16_t namelen;

char *name;

} lwres_gabnrequest_t;

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>