lwres_packet.docbook revision c1a883f2e04d94e99c433b1f6cfd0c0338f4ed85
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe [<!ENTITY mdash "—">]>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Copyright (C) 2000, 2001 Internet Software Consortium.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Permission to use, copy, modify, and distribute this software for any
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - purpose with or without fee is hereby granted, provided that the above
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - copyright notice and this permission notice appear in all copies.
ead9bb4b1be81d7bbf8ed86ee41d6c1e58b069a3Yuri Pankov - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
ead9bb4b1be81d7bbf8ed86ee41d6c1e58b069a3Yuri Pankov - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
ead9bb4b1be81d7bbf8ed86ee41d6c1e58b069a3Yuri Pankov - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - PERFORMANCE OF THIS SOFTWARE.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<!-- $Id: lwres_packet.docbook,v 1.12 2007/01/29 23:57:22 marka Exp $ -->
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <refentryinfo>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </refentryinfo>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </copyright>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </copyright>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <refnamediv>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <refpurpose>lightweight resolver packet handling functions</refpurpose>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </refnamediv>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <refsynopsisdiv>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <funcsynopsis>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<funcprototype>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_result_t
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<function>lwres_lwpacket_renderheader</function></funcdef>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </funcprototype>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<funcprototype>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowelwres_result_t
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe<function>lwres_lwpacket_parseheader</function></funcdef>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </funcprototype>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe</funcsynopsis>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </refsynopsisdiv>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe These functions rely on a
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe which is defined in
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowetypedef struct lwres_lwpacket lwres_lwpacket_t;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </programlisting>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowestruct lwres_lwpacket {
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint32_t length;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint16_t version;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint16_t pktflags;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint32_t serial;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint32_t opcode;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint32_t result;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint32_t recvlength;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint16_t authtype;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_uint16_t authlength;
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe</programlisting>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The elements of this structure are:
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <variablelist>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe the overall packet length, including the entire packet header.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe the header format. There is currently only one format,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe library-defined flags for this packet: for instance whether the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe is a request or a reply. Flag values can be set, but not defined
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field is filled in by the application wit the exception of
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lwres_gabn_*() and lwres_gnba_*() calls.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe is set by the requestor and is returned in all replies. If two
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe packets from the same source have the same serial number and are
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe the same source, they are assumed to be duplicates and the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe may be dropped.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field must be set by the application.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe indicates the operation.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Opcodes between 0x00000000 and 0x03ffffff are
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe reserved for use by the lightweight resolver library. Opcodes
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe 0x04000000 and 0xffffffff are application defined.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe is only valid for replies.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Results between 0x04000000 and 0xffffffff are application
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Results between 0x00000000 and 0x03ffffff are reserved for
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe library use.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe is the maximum buffer size that the receiver can handle on
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and the size of the buffer needed to satisfy a request when the
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe is too large for replies.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe This field is supplied by the application.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe defines the packet level authentication that is used.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Authorisation types between 0x1000 and 0xffff are application
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe and types between 0x0000 and 0x0fff are reserved for library
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Currently these are not used and must be zero.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe gives the length of the authentication data.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Since packet authentication is currently not used, this must be
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </variablelist>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The following opcodes are currently defined:
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <variablelist>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Success is always returned and the packet contents are echoed.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The lwres_noop_*() functions should be used for this type.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <term><constant>GETADDRSBYNAME</constant></term>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe returns all known addresses for a given name.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The lwres_gabn_*() functions should be used for this type.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <term><constant>GETNAMEBYADDR</constant></term>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe return the hostname for the given address.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe The lwres_gnba_*() functions should be used for this type.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </varlistentry>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe </variablelist>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <para><function>lwres_lwpacket_renderheader()</function>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe transfers the contents of lightweight resolver packet structure
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe network byte order to the lightweight resolver buffer,
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <para><function>lwres_lwpacket_parseheader()</function>
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe performs the converse operation. It transfers data in network
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe byte order from buffer <parameter>*b</parameter> to resolver
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe packet <parameter>*pkt</parameter>. The contents of the buffer
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <parameter>b</parameter> should correspond to a
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe Successful calls to
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <function>lwres_lwpacket_renderheader()</function> and
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <function>lwres_lwpacket_parseheader()</function> return
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe space to copy data between the buffer <parameter>*b</parameter> and
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe lightweight resolver packet <parameter>*pkt</parameter> both
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - Local variables:
c10c16dec587a0662068f6e2991c29ed3a9db943Richard Lowe - mode: sgml