lwres_gabn.docbook revision c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85
5cd4555ad444fd391002ae32450572054369fd42Rob Austein<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
5cd4555ad444fd391002ae32450572054369fd42Rob Austein "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein [<!ENTITY mdash "—">]>
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews - Copyright (C) 2004, 2005, 2007 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.
c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85Mark Andrews<!-- $Id: lwres_gabn.docbook,v 1.9 2007/01/29 23:57:22 marka Exp $ -->
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_render</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_render</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnresponse_free</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_gabnrequest_free</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These are low-level routines for creating and parsing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver name-to-address lookup request and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein response messages.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein There are four main functions for the getaddrbyname opcode.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein One render function converts a getaddrbyname request structure —
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to the lighweight resolver's canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein It is complemented by a parse function that converts a packet in this
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format to a getaddrbyname request structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Another render function converts the getaddrbyname response structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein — <type>lwres_gabnresponse_t</type> —
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to the canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is complemented by a parse function which converts a packet in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format to a getaddrbyname response structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These structures are defined in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They are shown below.
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct lwres_addr lwres_addr_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
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;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
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>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_gabnrequest_render()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein uses resolver context <parameter>ctx</parameter> to convert
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein getaddrbyname request structure <parameter>req</parameter> to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format. The packet header structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>pkt</parameter> is initialised and transferred to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The contents of <parameter>*req</parameter> are then appended to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the buffer in canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gabnresponse_render()</function> performs the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein same task, except it converts a getaddrbyname response structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gabnresponse_t</type> to the lightweight resolver's
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_gabnrequest_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein uses context <parameter>ctx</parameter> to convert the contents
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gabnrequest_t</type> structure. Buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>b</parameter> provides space to be used for storing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein this structure. When the function succeeds, the resulting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gabnrequest_t</type> is made available through
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gabnresponse_parse()</function> offers the same
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein semantics as <function>lwres_gabnrequest_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein except it yields a <type>lwres_gabnresponse_t</type> structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_gabnresponse_free()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and <function>lwres_gabnrequest_free()</function> release the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein memory in resolver context <parameter>ctx</parameter> that was
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein allocated to the <type>lwres_gabnresponse_t</type> or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gabnrequest_t</type> structures referenced via
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Any memory associated with ancillary buffers and strings for
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein those structures is also discarded.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The getaddrbyname opcode functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gabnrequest_render()</function>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gabnresponse_render()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if memory allocation fails.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned if the available space in the buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is too small to accommodate the packet header or the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffer is not empty after decoding the received packet.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions will return
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in the packet header structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein indicate that the packet is not a response to an earlier query.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - Local variables:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - mode: sgml