lwres_gnba.docbook revision 8eea877894ea5bcf5cdd9ca124a8601ad421d753
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 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.
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson<!-- $Id: lwres_gnba.docbook,v 1.4 2001/04/24 18:11:16 gson 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>.