lwres_packet.html revision c651f15b30f1dae5cc2f00878fb5da5b3a35a468
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
f0aad5341752aefe5059832f6cf3abc3283c6e16Tinderbox User - Copyright (C) 2000, 2001 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - purpose with or without fee is hereby granted, provided that the above
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - copyright notice and this permission notice appear in all copies.
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - PERFORMANCE OF THIS SOFTWARE.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!-- $Id: lwres_packet.html,v 1.14 2005/04/07 03:50:04 marka Exp $ -->
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>lwres_packet</TITLE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinNAME="GENERATOR"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="REFENTRY"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserBGCOLOR="#FFFFFF"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinTEXT="#000000"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLINK="#0000FF"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinVLINK="#840084"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserALINK="#0000FF"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>lwres_packet</H1
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="REFNAMEDIV"
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader -- lightweight resolver packet handling functions</DIV
010a51c427bfb6ab658fc0056955a1a5b69810beTinderbox UserCLASS="REFSYNOPSISDIV"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="FUNCSYNOPSIS"
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserCLASS="FUNCSYNOPSISINFO"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="FUNCDEF"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>lwres_result_t
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox Userlwres_lwpacket_renderheader</CODE
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserCLASS="FUNCDEF"
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>lwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_lwpacket_parseheader</CODE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserCLASS="REFSECT1"
2b4d1b54f6ca406b8233d9e6fea9593df6dad035Tinderbox User>DESCRIPTION</H2
2b4d1b54f6ca406b8233d9e6fea9593df6dad035Tinderbox User>These functions rely on a
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>struct lwres_lwpacket</SPAN
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntwhich is defined in
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserCLASS="FILENAME"
6f64d4ab8e68f9b2333bcbfc755396d29a4a9d7cAutomatic UpdaterCLASS="PROGRAMLISTING"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User>typedef struct lwres_lwpacket lwres_lwpacket_t;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userstruct lwres_lwpacket {
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t length;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint16_t version;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint16_t pktflags;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t serial;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t opcode;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t result;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint32_t recvlength;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint16_t authtype;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User lwres_uint16_t authlength;
44d0f0256fbdce130a18655023c3b06bacacbd61Automatic Updater>The elements of this structure are:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="VARIABLELIST"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="CONSTANT"
44d0f0256fbdce130a18655023c3b06bacacbd61Automatic Updater>the overall packet length, including the entire packet header.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="CONSTANT"
bcf15a19ae0efa72a22cdfb50666a3c6ce39eb9fTinderbox User>version</CODE
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User>the header format. There is currently only one format,
260e8e04b0dc24cb884c789b5d9eb046457f264eTinderbox User>LWRES_LWPACKETVERSION_0</SPAN
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="CONSTANT"
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrews>pktflags</CODE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>library-defined flags for this packet: for instance whether the packet
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewsis a request or a reply. Flag values can be set, but not defined by
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis field is filled in by the application wit the exception of the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinLWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntlwres_gabn_*() and lwres_gnba_*() calls.</P
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="CONSTANT"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>is set by the requestor and is returned in all replies. If two or more
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinpackets from the same source have the same serial number and are from
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox Userthe same source, they are assumed to be duplicates and the latter ones
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox Usermay be dropped.
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserThis field must be set by the application.</P
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserCLASS="CONSTANT"
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>indicates the operation.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntOpcodes between 0x00000000 and 0x03ffffff are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinreserved for use by the lightweight resolver library. Opcodes between
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt0x04000000 and 0xffffffff are application defined.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="CONSTANT"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>is only valid for replies.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntResults between 0x04000000 and 0xffffffff are application defined.
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserResults between 0x00000000 and 0x03ffffff are reserved for library use.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="CONSTANT"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>recvlength</CODE
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>is the maximum buffer size that the receiver can handle on requests
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox Userand the size of the buffer needed to satisfy a request when the buffer
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntis too large for replies.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThis field is supplied by the application.</P
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="CONSTANT"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>authtype</CODE
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>defines the packet level authentication that is used.
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserAuthorisation types between 0x1000 and 0xffff are application defined
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinand types between 0x0000 and 0x0fff are reserved for library use.
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserCurrently these are not used and must be zero.</P
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinCLASS="CONSTANT"
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>authlen</CODE
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User>gives the length of the authentication data.
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox UserSince packet authentication is currently not used, this must be zero.</P
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>The following opcodes are currently defined:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="VARIABLELIST"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="CONSTANT"
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User>Success is always returned and the packet contents are echoed.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe lwres_noop_*() functions should be used for this type.</P
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="CONSTANT"
af40ebed6257e4ac1996144530b3de317cf4da11Tinderbox User>GETADDRSBYNAME</CODE
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User>returns all known addresses for a given name.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntThe lwres_gabn_*() functions should be used for this type.</P
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox UserCLASS="CONSTANT"
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User>GETNAMEBYADDR</CODE
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein>return the hostname for the given address.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob AusteinThe lwres_gnba_*() functions should be used for this type.</P
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox UserCLASS="FUNCTION"
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User>lwres_lwpacket_renderheader()</CODE
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User> transfers the
71c66a876ecca77923638d3f94cc0783152b2f03Mark Andrewscontents of lightweight resolver packet structure
e108f2ec640e1acb54999c0ade58af606149956dTinderbox User>lwres_lwpacket_t</SPAN
6d382c9fcec316a84a237779fb64bb471b6f9d43Tinderbox UserCLASS="PARAMETER"
7e71f05d8643aca84914437c900cb716444507e4Tinderbox Userbyte order to the lightweight resolver buffer,
f9aef05653eeb454c489d5bd2bde6daab774ad4aTinderbox UserCLASS="PARAMETER"
922312472e2e05ebc64993d465999c5351b83036Automatic UpdaterCLASS="FUNCTION"
922312472e2e05ebc64993d465999c5351b83036Automatic Updater>lwres_lwpacket_parseheader()</CODE
dec590a3deb8e87380a8bd3a77d535dba3729bf6Tinderbox Userconverse operation. It transfers data in network byte order from
50066670817cdf9e86c832066d73715232b29680Tinderbox UserCLASS="PARAMETER"
28b3569d6248168e6c00caab951521cc8141a49dAutomatic Updater> to resolver packet
71c66a876ecca77923638d3f94cc0783152b2f03Mark AndrewsCLASS="PARAMETER"
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews>. The contents of the buffer
7e71f05d8643aca84914437c900cb716444507e4Tinderbox UserCLASS="PARAMETER"
dec590a3deb8e87380a8bd3a77d535dba3729bf6Tinderbox User> should correspond to a
dec590a3deb8e87380a8bd3a77d535dba3729bf6Tinderbox User>lwres_lwpacket_t</SPAN
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCLASS="REFSECT1"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>RETURN VALUES</H2
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews> Successful calls to
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCLASS="FUNCTION"
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews>lwres_lwpacket_renderheader()</CODE
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCLASS="FUNCTION"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt>lwres_lwpacket_parseheader()</CODE
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntCLASS="ERRORCODE"
ad8f23aed6c75f94f238c1f23f4e17515d28eb55Tinderbox User>LWRES_R_SUCCESS</SPAN
ad8f23aed6c75f94f238c1f23f4e17515d28eb55Tinderbox User>. If there is insufficient
e2e4d321999340802f77adaacd19c797d04b4b95Automatic Updaterspace to copy data between the buffer <CODE
e2e4d321999340802f77adaacd19c797d04b4b95Automatic UpdaterCLASS="PARAMETER"
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox Userlightweight resolver packet <CODE
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox UserCLASS="PARAMETER"
1e9517ea2156b990be21f44676d3370318eacf17Tinderbox User> both functions
b6b8f8a0362da8c749021c4b6376cfb96047912bTinderbox UserCLASS="ERRORCODE"
b6b8f8a0362da8c749021c4b6376cfb96047912bTinderbox User>LWRES_R_UNEXPECTEDEND</SPAN