lwres_packet.docbook revision ac299c4f5ca236370b9df2a91b18b149b1d344a7
f743002678eb67b99bbc29fee116b65d9530fec0wrowe<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem - Copyright (C) 2001 Internet Software Consortium.
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - Permission to use, copy, modify, and distribute this software for any
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - purpose with or without fee is hereby granted, provided that the above
1337c7673efc1f80f634139fbad7cbb98a0dc657ylavic - copyright notice and this permission notice appear in all copies.
4da61833a1cbbca94094f9653fd970582b97a72etrawick - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
4da61833a1cbbca94094f9653fd970582b97a72etrawick - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
4da61833a1cbbca94094f9653fd970582b97a72etrawick - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
4da61833a1cbbca94094f9653fd970582b97a72etrawick - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
4789804be088bcd86ae637a29cdb7fda25169521jailletc - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
4789804be088bcd86ae637a29cdb7fda25169521jailletc - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
4789804be088bcd86ae637a29cdb7fda25169521jailletc - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
e50c3026198fd496f183cda4c32a202925476778covener<!-- $Id: lwres_packet.docbook,v 1.6 2001/06/18 22:56:30 gson Exp $ -->
6c3b9cebb551140fbb25d58bae08b539b3802133ylavic<refentryinfo>
4f29b65ab4b547ad5dbe506e2d0ff5d12ead9247ylavic</refentryinfo>
69301145375a889e7e37caf7cc7321ac0f91801erpluem<refnamediv>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza<refpurpose>lightweight resolver packet handling functions</refpurpose>
506bfe33206b2fece40ef25f695af39dd4130facjkaluza</refnamediv>
d58a848a016d401b965111e50ef829e1641f7834minfrin<refsynopsisdiv>
d58a848a016d401b965111e50ef829e1641f7834minfrin<funcsynopsis>
d58a848a016d401b965111e50ef829e1641f7834minfrin<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sf<funcprototype>
2e6f4d654c96c98b761fb012fd25c5d5b1558c44sflwres_result_t
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic<function>lwres_lwpacket_renderheader</function></funcdef>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic</funcprototype>
17e6c95f3b22d18acdf8380fb26a8d0e10c80767ylavic<funcprototype>
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylaviclwres_result_t
e8bd80a4bb88199d2f9a24a50345688e52d9c116ylavic<function>lwres_lwpacket_parseheader</function></funcdef>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</funcprototype>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</funcsynopsis>
330e16bea8fe9cace4de90c349750c03dfb1fe64ylavic</refsynopsisdiv>
d7205b1a86c51c27b71a2c458dc453fd53a261c1covenerThese functions rely on a
d7205b1a86c51c27b71a2c458dc453fd53a261c1covenerwhich is defined in
44ff304057225e944e220e981d434a046d14cf06covener<programlisting>
44ff304057225e944e220e981d434a046d14cf06covenertypedef struct lwres_lwpacket lwres_lwpacket_t;
5d1ba75b8794925e67591c209085a49279791de9covenerstruct lwres_lwpacket {
5d1ba75b8794925e67591c209085a49279791de9covener lwres_uint32_t length;
5d1ba75b8794925e67591c209085a49279791de9covener lwres_uint16_t version;
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand lwres_uint16_t pktflags;
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand lwres_uint32_t serial;
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand lwres_uint32_t opcode;
032982212dbcc7c3cce95bf89c503bb56e185ac7kbrand lwres_uint32_t result;
caad2986f81ab263f7af41467dd622dc9add17f3ylavic lwres_uint32_t recvlength;
caad2986f81ab263f7af41467dd622dc9add17f3ylavic lwres_uint16_t authtype;
caad2986f81ab263f7af41467dd622dc9add17f3ylavic lwres_uint16_t authlength;
45a10d38e6051fd7bdf9d742aaae633d97ff02abjailletc</programlisting>
a34684a59b60a4173c25035d0c627ef17e6dc215rpluemThe elements of this structure are:
a34684a59b60a4173c25035d0c627ef17e6dc215rpluem<variablelist>
1e2d421a36999d292042a5539971070d54aa6c63ylavic<varlistentry><term><constant>length</constant></term>
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedoohthe overall packet length, including the entire packet header.
fa7ed98b9dc94c5845cf845aea0a44ecacd290c9humbedoohThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
0b67eb8568cd58bb77082703951679b42cf098actrawick<varlistentry><term><constant>version</constant></term>
5ef3c61605a3a021ff71f488983cb0065f8e1a79covenerthe header format. There is currently only one format,
6502b7b32f980cc2093bb3ebce37e5e4dc68fba4ylavicThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
c1a63b8fad09c419c1a64f75993feb8a343a6801ylavic<varlistentry><term><constant>pktflags</constant></term>
e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletclibrary-defined flags for this packet: for instance whether the packet
e6b4bd1113567627ab6bb6c6a7105e1e01a7d889jailletcis a request or a reply. Flag values can be set, but not defined by
e466c40e1801982602ee0200c9e8b61cc148742djailletcThis field is filled in by the application wit the exception of the
457468b82e59d01eba00dd9d0817309c8f5e414ejimLWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
457468b82e59d01eba00dd9d0817309c8f5e414ejimlwres_gabn_*() and lwres_gnba_*() calls.
04983e3bd1754764eec7d6bb772fe3b0bf391771jorton<varlistentry><term><constant>serial</constant></term>
15660979a30d251681463de2e0584853890082accoveneris set by the requestor and is returned in all replies. If two or more
15660979a30d251681463de2e0584853890082accovenerpackets from the same source have the same serial number and are from
49dacedb6c387b786b7911082ff35121a45f414bcovenerthe same source, they are assumed to be duplicates and the latter ones
49dacedb6c387b786b7911082ff35121a45f414bcovenermay be dropped.
cfd9415521847b2f9394fad04fb701cfb955f503rjungThis field must be set by the application.
28c31fb73c1264bd1d0ff932573677030b024c7dwroweindicates the operation.
28c31fb73c1264bd1d0ff932573677030b024c7dwroweOpcodes between 0x00000000 and 0x03ffffff are
28c31fb73c1264bd1d0ff932573677030b024c7dwrowereserved for use by the lightweight resolver library. Opcodes between
8491e0600f69b0405e156ea8a419653c065c645bcovener0x04000000 and 0xffffffff are application defined.
63b9f1f5880391261705f696d7d65507bbe9ace3covenerThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
49dacedb6c387b786b7911082ff35121a45f414bcovener<varlistentry><term><constant>result</constant></term>
49dacedb6c387b786b7911082ff35121a45f414bcoveneris only valid for replies.
3c990331fc6702119e4f5b8ba9eae3021aea5265jimResults between 0x04000000 and 0xffffffff are application defined.
3c990331fc6702119e4f5b8ba9eae3021aea5265jimResults between 0x00000000 and 0x03ffffff are reserved for library use.
3c990331fc6702119e4f5b8ba9eae3021aea5265jimThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
fc42512879dd0504532f52fe5d0d0383dda96a1eniq<varlistentry><term><constant>recvlength</constant></term>
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niqis the maximum buffer size that the receiver can handle on requests
0451df5dc50fa5d8b3e07d92ee6a92e36a1181a5niqand the size of the buffer needed to satisfy a request when the buffer
da0442c0440caef34706e2c2f3af05cb65921cc0jailletcis too large for replies.
983528026996668ea295be95aedb9c7a346af470ylavicThis field is supplied by the application.
da0442c0440caef34706e2c2f3af05cb65921cc0jailletc<varlistentry><term><constant>authtype</constant></term>
06b8f183140c8e02e0974e938a05078b511d1603covenerdefines the packet level authentication that is used.
15890c9306ba98f6fc243e15a3c4778ddc7d773erpluemAuthorisation types between 0x1000 and 0xffff are application defined
259878293a997ff49f5ddfc53d3739cbdc25444ecovenerand types between 0x0000 and 0x0fff are reserved for library use.
259878293a997ff49f5ddfc53d3739cbdc25444ecovenerCurrently these are not used and must be zero.
259878293a997ff49f5ddfc53d3739cbdc25444ecovener<varlistentry><term><constant>authlen</constant></term>
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfringives the length of the authentication data.
b54b024c06a19926832d77d40ba35ad8c41e4d3dminfrinSince packet authentication is currently not used, this must be zero.
65967d05f839dbf27cf91d91fa79585eeae19660minfrin</variablelist>
8152945ae46857b170cb227e79bb799f4fc7710dminfrinThe following opcodes are currently defined:
8152945ae46857b170cb227e79bb799f4fc7710dminfrin<variablelist>
75f5c2db254c0167a0e396254460de09b775d203trawickSuccess is always returned and the packet contents are echoed.
75f5c2db254c0167a0e396254460de09b775d203trawickThe lwres_noop_*() functions should be used for this type.
4f0358189bfa57b8e75bd6b94db264302a8f336amrumph<varlistentry><term><constant>GETADDRSBYNAME</constant></term>
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawickreturns all known addresses for a given name.
5716f9c6daa92dde5f2f9d11ed63f7c9549c223atrawickThe lwres_gabn_*() functions should be used for this type.
54d750a84a175d8e338880514d440773eb986b50covener<varlistentry><term><constant>GETNAMEBYADDR</constant></term>
54d750a84a175d8e338880514d440773eb986b50covenerreturn the hostname for the given address.
54d750a84a175d8e338880514d440773eb986b50covenerThe lwres_gnba_*() functions should be used for this type.
54d750a84a175d8e338880514d440773eb986b50covener</variablelist>
54d750a84a175d8e338880514d440773eb986b50covener<function>lwres_lwpacket_renderheader()</function> transfers the
83b50288fa7d306324bba68832011ea08f5c7832covenercontents of lightweight resolver packet structure
4e30ef014533a7e93c92d88306291f5e49c9692ftrawick<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network
83b50288fa7d306324bba68832011ea08f5c7832covenerbyte order to the lightweight resolver buffer,
2e15620d724fb8e3a5be183b917359a2fd6e9468covener<function>lwres_lwpacket_parseheader()</function> performs the
2e15620d724fb8e3a5be183b917359a2fd6e9468covenerconverse operation. It transfers data in network byte order from
1b988c41ee505962781d110a3e4c2c90f1ea0aa4covener<parameter>*pkt</parameter>. The contents of the buffer
f06e7c4b1bce6b6491e5de0b7998d3f5696b293dchrisd<para> Successful calls to
179565be4043d7e5f9161aa75271fa0a001866d9covener<function>lwres_lwpacket_renderheader()</function> and
179565be4043d7e5f9161aa75271fa0a001866d9covener<function>lwres_lwpacket_parseheader()</function> return
179565be4043d7e5f9161aa75271fa0a001866d9covener<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
111436a32ba1254291e4883292fb116d15fe8f64covenerspace to copy data between the buffer <parameter>*b</parameter> and
fce4949fb0b309a5744afcd503c6ed2d35621ee2covenerlightweight resolver packet <parameter>*pkt</parameter> both functions