lwres_gnba.docbook revision 30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!ENTITY mdash "—">]>
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - Permission to use, copy, modify, and/or 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.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
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 getnamebyaddress message handling</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsisinfo>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_render</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gnbarequest_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>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_render</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gnbaresponse_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>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_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_gnbarequest_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_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_gnbaresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbaresponse_free</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson<function>lwres_gnbarequest_free</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These are low-level routines for creating and parsing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver address-to-name lookup request and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein response messages.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein There are four main functions for the getnamebyaddr opcode.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein One render function converts a getnamebyaddr request structure —
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to the lightweight 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 getnamebyaddr request structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Another render function converts the getnamebyaddr response structure
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 getnamebyaddr response structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These structures are defined in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They are shown below.
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t flags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_addr_t addr;
9ffbbce6a624b6051b3d001edcbad1e02c69bd45Andreas Gustafsson} lwres_gnbarequest_t;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
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>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_gnbarequest_render()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein uses resolver context <varname>ctx</varname> to convert
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein getnamebyaddr request structure <varname>req</varname> to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format. The packet header structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varname>pkt</varname> is initialised and transferred to buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varname>b</varname>. The contents of <varname>*req</varname>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein are then appended to the buffer in canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gnbaresponse_render()</function> performs the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein same task, except it converts a getnamebyaddr response structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gnbaresponse_t</type> to the lightweight resolver's
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_gnbarequest_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein uses context <varname>ctx</varname> to convert the contents of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gnbarequest_t</type> structure. Buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varname>b</varname> provides space to be used for storing this
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein structure. When the function succeeds, the resulting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gnbarequest_t</type> is made available through
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gnbaresponse_parse()</function> offers the same
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein semantics as <function>lwres_gnbarequest_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein except it yields a <type>lwres_gnbaresponse_t</type> structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_gnbaresponse_free()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and <function>lwres_gnbarequest_free()</function> release the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein memory in resolver context <varname>ctx</varname> that was
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein allocated to the <type>lwres_gnbaresponse_t</type> or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_gnbarequest_t</type> structures referenced via
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varname>structp</varname>. Any memory associated with
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein ancillary buffers and strings for those structures is also
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>RETURN VALUES</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The getnamebyaddr opcode functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gnbarequest_render()</function>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_gnbaresponse_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.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>