lwres_packet.docbook revision 86b0285d7e65601645db4090d62ee6cb63abad6c
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and 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.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<!-- $Id: lwres_packet.docbook,v 1.5 2001/06/18 22:07:01 gson Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_packet</refentrytitle>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_lwpacket_renderheader</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_lwpacket_parseheader</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver packet handling functions</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_lwpacket_renderheader</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_lwpacket_parseheader</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese functions rely on a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct lwres_lwpacket lwres_lwpacket_t;
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>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe elements of this structure are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>length</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthe overall packet length, including the entire packet header.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>version</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthe header format. There is currently only one format,
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>pktflags</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlibrary-defined flags for this packet: for instance whether the packet
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis a request or a reply. Flag values can be set, but not defined by
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the application wit the exception of the
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonLWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_gabn_*() and lwres_gnba_*() calls.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>serial</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis set by the requestor and is returned in all replies. If two or more
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonpackets from the same source have the same serial number and are from
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthe same source, they are assumed to be duplicates and the latter ones
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonmay be dropped.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field must be set by the application.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>opcode</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonindicates the operation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonOpcodes between 0x00000000 and 0x03ffffff are
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreserved for use by the lightweight resolver library. Opcodes between
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson0x04000000 and 0xffffffff are application defined.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>result</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis only valid for replies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonResults between 0x04000000 and 0xffffffff are application defined.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonResults between 0x00000000 and 0x03ffffff are reserved for library use.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>recvlength</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis the maximum buffer size that the receiver can handle on requests
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand the size of the buffer needed to satisfy a request when the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis too large for replies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is supplied by the application.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>authtype</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssondefines the packet level authentication that is used.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAuthorisation types between 0x1000 and 0xffff are application defined
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand types between 0x0000 and 0x0fff are reserved for library use.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCurrently these are not used and must be zero.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>authlen</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssongives the length of the authentication data.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSince packet authentication is currently not used, this must be zero.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe following opcodes are currently defined:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>NOOP</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSuccess is always returned and the packet contents are echoed.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lwres_noop_*() functions should be used for this type.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>GETADDRSBYNAME</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreturns all known addresses for a given name.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lwres_gabn_*() functions should be used for this type.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<varlistentry><term><constant>GETNAMEBYADDR</constant></term>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonreturn the hostname for the given address.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lwres_gnba_*() functions should be used for this type.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</variablelist>
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_lwpacket_renderheader()</function> transfers the
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssoncontents of lightweight resolver packet structure
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonbyte order to the lightweight resolver buffer,
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_lwpacket_parseheader()</function> performs the
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonconverse operation. It transfers data in network byte order from
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonbuffer <parameter>*b</parameter> to resolver packet
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>*pkt</parameter>. The contents of the buffer
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>b</parameter> should correspond to a
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBoth functions have assertion checks to ensure that
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>b</parameter> and <parameter>pkt</parameter> are not
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<para> Successful calls to
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_lwpacket_renderheader()</function> and
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_lwpacket_parseheader()</function> return
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonspace to copy data between the buffer <parameter>*b</parameter> and
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonlightweight resolver packet <parameter>*pkt</parameter> both functions
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonreturn <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.