lwres_packet.docbook revision 19c7b1a0293498a3e36692c59646ed6e15ffc8d0
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
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas 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 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>