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 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>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
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 —
821350367e2c7313c02eb275e8e05d5193b47cfdJeremy C. Reed 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 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.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>RETURN VALUES</title></info>
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.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>