lwres_gabn.docbook revision ddccd5811feff696ba460dabfb666ce61040f545
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Copyright (C) 2000, 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!-- $Id: lwres_gabn.docbook,v 1.1 2001/03/31 00:08:07 gson Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_gabnrequest_render</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_gabnresponse_render</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_gabnrequest_parse</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_gabnresponse_parse</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_gabnresponse_free</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_render</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnrequest_t *req</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_render</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnresponse_t *req</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnrequest_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_free</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_free</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_gabnrequest_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese are low-level routines for creating and parsing
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlightweight resolver name-to-address lookup request and
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonresponse messages.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThere are four main functions for the getaddrbyname opcode.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonOne render function converts a getaddrbyname request structure —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the lighweight resolver's canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt is complemented by a parse function that converts a packet in this
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncanonical format to a getaddrbyname request structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAnother render function converts the getaddrbyname response structure —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis is complemented by a parse function which converts a packet in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncanonical format to a getaddrbyname response structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese structures are defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<filename><lwres/lwres.h></filename>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThey are shown below.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct lwres_addr lwres_addr_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint32_t flags;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint32_t addrtypes;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t namelen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnrequest_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint32_t flags;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t naliases;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t naddrs;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char *realname;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson char **aliases;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t realnamelen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t *aliaslen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_addrlist_t addrs;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson size_t baselen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnresponse_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonuses resolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto convert getaddrbyname request structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe packet header structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis initialised and transferred to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe contents of
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonare then appended to the buffer in canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms the same task, except it converts a getaddrbyname response structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the lightweight resolver's canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto convert the contents of packet
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprovides space to be used for storing this structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonWhen the function succeeds, the resulting
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis made available through
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonoffers the same semantics as
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonexcept it yields a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_free()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_free()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonrelease the memory in resolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthat was allocated to the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructures referenced via
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAny memory associated with ancillary buffers and strings for those
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructures is also discarded.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe getaddrbyname opcode functions
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_render()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif memory allocation fails.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned if the available space in the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis too small to accommodate the packet header or the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer is not empty after decoding the received packet.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese functions will return
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin the packet header structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonindicate that the packet is not a response to an earlier query.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>