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 packet handling functions</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_lwpacket_renderheader</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_lwpacket_parseheader</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>DESCRIPTION</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions rely on a
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein which is defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct lwres_lwpacket lwres_lwpacket_t;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstruct lwres_lwpacket {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t length;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t version;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t pktflags;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t serial;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t opcode;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t result;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint32_t recvlength;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t authtype;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t authlength;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The elements of this structure are:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the overall packet length, including the entire packet header.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the header format. There is currently only one format,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein library-defined flags for this packet: for instance whether the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is a request or a reply. Flag values can be set, but not defined
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field is filled in by the application wit the exception of
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_gabn_*() and lwres_gnba_*() calls.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is set by the requestor and is returned in all replies. If two
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein packets from the same source have the same serial number and are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the same source, they are assumed to be duplicates and the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein may be dropped.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field must be set by the application.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein indicates the operation.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Opcodes between 0x00000000 and 0x03ffffff are
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein reserved for use by the lightweight resolver library. Opcodes
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 0x04000000 and 0xffffffff are application defined.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is only valid for replies.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Results between 0x04000000 and 0xffffffff are application
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Results between 0x00000000 and 0x03ffffff are reserved for
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein library use.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is the maximum buffer size that the receiver can handle on
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and the size of the buffer needed to satisfy a request when the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is too large for replies.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This field is supplied by the application.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein defines the packet level authentication that is used.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Authorisation types between 0x1000 and 0xffff are application
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and types between 0x0000 and 0x0fff are reserved for library
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Currently these are not used and must be zero.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein gives the length of the authentication data.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Since packet authentication is currently not used, this must be
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The following opcodes are currently defined:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Success is always returned and the packet contents are echoed.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The lwres_noop_*() functions should be used for this type.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <term><constant>GETADDRSBYNAME</constant></term>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein returns all known addresses for a given name.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The lwres_gabn_*() functions should be used for this type.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein return the hostname for the given address.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The lwres_gnba_*() functions should be used for this type.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </varlistentry>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </variablelist>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_lwpacket_renderheader()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein transfers the contents of lightweight resolver packet structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein network byte order to the lightweight resolver buffer,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_lwpacket_parseheader()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein performs the converse operation. It transfers data in network
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein byte order from buffer <parameter>*b</parameter> to resolver
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein packet <parameter>*pkt</parameter>. The contents of the buffer
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <refsection><info><title>RETURN VALUES</title></info>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Successful calls to
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_lwpacket_renderheader()</function> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_lwpacket_parseheader()</function> return
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein space to copy data between the buffer <parameter>*b</parameter> and
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver packet <parameter>*pkt</parameter> both
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refsection>