lwres_gabn.docbook revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - 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.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<!-- $Id: lwres_gabn.docbook,v 1.5 2005/04/07 03:50:01 marka 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>
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas 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 {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t addrtypes;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t namelen;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_gabnrequest_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naddrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *realname;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **aliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t realnamelen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t *aliaslen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addrlist_t addrs;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas 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>