lwres_packet.docbook revision 86b0285d7e65601645db4090d62ee6cb63abad6c
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - Copyright (C) 2001 Internet Software Consortium.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - Permission to use, copy, modify, and distribute this software for any
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - purpose with or without fee is hereby granted, provided that the above
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - copyright notice and this permission notice appear in all copies.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<!-- $Id: lwres_packet.docbook,v 1.5 2001/06/18 22:07:01 gson Exp $ -->
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<refentryinfo>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</refentryinfo>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<refnamediv>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<refpurpose>lightweight resolver packet handling functions</refpurpose>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</refnamediv>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<refsynopsisdiv>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<funcsynopsis>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<funcprototype>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynclwres_result_t
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<function>lwres_lwpacket_renderheader</function></funcdef>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</funcprototype>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<funcprototype>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynclwres_result_t
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<function>lwres_lwpacket_parseheader</function></funcdef>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</funcprototype>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</funcsynopsis>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</refsynopsisdiv>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThese functions rely on a
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncwhich is defined in
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<programlisting>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynctypedef struct lwres_lwpacket lwres_lwpacket_t;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncstruct lwres_lwpacket {
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint32_t length;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint16_t version;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint16_t pktflags;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint32_t serial;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint32_t opcode;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint32_t result;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint32_t recvlength;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint16_t authtype;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync lwres_uint16_t authlength;
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</programlisting>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThe elements of this structure are:
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<variablelist>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>length</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncthe overall packet length, including the entire packet header.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>version</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncthe header format. There is currently only one format,
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>pktflags</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynclibrary-defined flags for this packet: for instance whether the packet
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncis a request or a reply. Flag values can be set, but not defined by
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field is filled in by the application wit the exception of the
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncLWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynclwres_gabn_*() and lwres_gnba_*() calls.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>serial</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncis set by the requestor and is returned in all replies. If two or more
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncpackets from the same source have the same serial number and are from
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncthe same source, they are assumed to be duplicates and the latter ones
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncmay be dropped.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field must be set by the application.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>opcode</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncindicates the operation.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncOpcodes between 0x00000000 and 0x03ffffff are
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncreserved for use by the lightweight resolver library. Opcodes between
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync0x04000000 and 0xffffffff are application defined.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>result</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncis only valid for replies.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncResults between 0x04000000 and 0xffffffff are application defined.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncResults between 0x00000000 and 0x03ffffff are reserved for library use.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>recvlength</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncis the maximum buffer size that the receiver can handle on requests
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncand the size of the buffer needed to satisfy a request when the buffer
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncis too large for replies.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThis field is supplied by the application.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>authtype</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncdefines the packet level authentication that is used.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncAuthorisation types between 0x1000 and 0xffff are application defined
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncand types between 0x0000 and 0x0fff are reserved for library use.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncCurrently these are not used and must be zero.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>authlen</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncgives the length of the authentication data.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncSince packet authentication is currently not used, this must be zero.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</variablelist>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThe following opcodes are currently defined:
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<variablelist>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>NOOP</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncSuccess is always returned and the packet contents are echoed.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThe lwres_noop_*() functions should be used for this type.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>GETADDRSBYNAME</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncreturns all known addresses for a given name.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThe lwres_gabn_*() functions should be used for this type.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<varlistentry><term><constant>GETNAMEBYADDR</constant></term>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncreturn the hostname for the given address.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncThe lwres_gnba_*() functions should be used for this type.
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync</variablelist>
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<function>lwres_lwpacket_renderheader()</function> transfers the
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynccontents of lightweight resolver packet structure
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncbyte order to the lightweight resolver buffer,
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<function>lwres_lwpacket_parseheader()</function> performs the
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncconverse operation. It transfers data in network byte order from
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<parameter>*pkt</parameter>. The contents of the buffer
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncBoth functions have assertion checks to ensure that
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<parameter>b</parameter> and <parameter>pkt</parameter> are not
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<para> Successful calls to
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<function>lwres_lwpacket_renderheader()</function> and
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<function>lwres_lwpacket_parseheader()</function> return
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsync<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncspace to copy data between the buffer <parameter>*b</parameter> and
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsynclightweight resolver packet <parameter>*pkt</parameter> both functions
14ea49401f3c8c61422aefbda43809e275f60c6cvboxsyncreturn <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.