lwres_gnba.docbook revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas 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.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas 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_gnba.docbook,v 1.6 2005/04/07 03:50:03 marka Exp $ -->
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</refentryinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refname>lwres_gnbarequest_render</refname>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refname>lwres_gnbaresponse_render</refname>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refname>lwres_gnbarequest_parse</refname>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refname>lwres_gnbaresponse_parse</refname>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refname>lwres_gnbaresponse_free</refname>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<refsynopsisdiv>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_render</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_render</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_gnbaresponse_t *req</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_parse</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_gnbarequest_t **structp</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_parse</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_gnbaresponse_t **structp</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_free</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_gnbaresponse_t **structp</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_free</function></funcdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<paramdef>lwres_gnbarequest_t **structp</paramdef>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsis>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</refsynopsisdiv>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThese are low-level routines for creating and parsing
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonlightweight resolver address-to-name lookup request and
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonresponse messages.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThere are four main functions for the getnamebyaddr opcode.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonOne render function converts a getnamebyaddr request structure —
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto the lightweight resolver's canonical format.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonIt is complemented by a parse function that converts a packet in this
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssoncanonical format to a getnamebyaddr request structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAnother render function converts the getnamebyaddr response structure —
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto the canonical format.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThis is complemented by a parse function which converts a packet in
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssoncanonical format to a getnamebyaddr response structure.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThese structures are defined in
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThey are shown below.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<programlisting>
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addr_t addr;
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson} lwres_gnbarequest_t;
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t naliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char *realname;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson char **aliases;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t realnamelen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t *aliaslen;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson size_t baselen;
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson} lwres_gnbaresponse_t;
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_render()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonuses resolver context
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto convert getnamebyaddr request structure
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto canonical format.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe packet header structure
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonis initialised and transferred to
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe contents of
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonare then appended to the buffer in canonical format.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_render()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonperforms the same task, except it converts a getnamebyaddr response structure
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto the lightweight resolver's canonical format.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_parse()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonto convert the contents of packet
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonprovides space to be used for storing this structure.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonWhen the function succeeds, the resulting
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonis made available through
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_parse()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonoffers the same semantics as
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_parse()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonexcept it yields a
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_free()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_free()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonrelease the memory in resolver context
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonthat was allocated to the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonstructures referenced via
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonAny memory associated with ancillary buffers and strings for those
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonstructures is also discarded.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThe getnamebyaddr opcode functions
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_render()</function>,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_render()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_parse()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_parse()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonif memory allocation fails.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonis returned if the available space in the buffer
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonis too small to accommodate the packet header or the
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_parse()</function>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonif the buffer is not empty after decoding the received packet.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas GustafssonThese functions will return
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonin the packet header structure
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssonindicate that the packet is not a response to an earlier query.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_packet</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>.