14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!ENTITY mdash "—">]>
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - This Source Code Form is subject to the terms of the Mozilla Public
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - License, v. 2.0. If a copy of the MPL was not distributed with this
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - file, You can obtain one at http://mozilla.org/MPL/2.0/.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!-- Converted by db4-upgrade version 1.0 -->
83a28ca274521e15086fc39febde507bcc4e145eMark Andrews<refentry xmlns:db="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 <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>