lwres_packet.html revision 8a66318e41ed14c5a88130e8c362610e8faa2121
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - 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.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
8a66318e41ed14c5a88130e8c362610e8faa2121Mark Andrews<!-- $Id: lwres_packet.html,v 1.9 2004/03/05 08:32:21 marka Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet</TITLE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
8a66318e41ed14c5a88130e8c362610e8faa2121Mark AndrewsCONTENT="Modular DocBook HTML Stylesheet Version 1.73
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFENTRY"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonBGCOLOR="#FFFFFF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonVLINK="#840084"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonALINK="#0000FF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet</A
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFNAMEDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader -- lightweight resolver packet handling functions</DIV
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSYNOPSISDIV"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSIS"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCSYNOPSISINFO"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_lwpacket_renderheader</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCDEF"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_result_t
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlwres_lwpacket_parseheader</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>DESCRIPTION</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>These functions rely on a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>struct lwres_lwpacket</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonwhich is defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FILENAME"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PROGRAMLISTING"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>typedef 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>The elements of this structure are:
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARIABLELIST"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>the overall packet length, including the entire packet header.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>the header format. There is currently only one format,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_LWPACKETVERSION_0</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>library-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.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>is 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.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>indicates 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 GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>is 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 GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>recvlength</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>is 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.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>defines 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.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>gives the length of the authentication data.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonSince packet authentication is currently not used, this must be zero.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>The following opcodes are currently defined:
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="VARIABLELIST"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Success is always returned and the packet contents are echoed.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lwres_noop_*() functions should be used for this type.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>GETADDRSBYNAME</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>returns all known addresses for a given name.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lwres_gabn_*() functions should be used for this type.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="CONSTANT"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>GETNAMEBYADDR</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>return the hostname for the given address.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe lwres_gnba_*() functions should be used for this type.</P
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_renderheader()</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> transfers the
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssoncontents of lightweight resolver packet structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonbyte order to the lightweight resolver buffer,
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_parseheader()</TT
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonconverse operation. It transfers data in network byte order from
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> to resolver packet
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson>. The contents of the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> should correspond to a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>RETURN VALUES</H2
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> Successful calls to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_renderheader()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_parseheader()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_SUCCESS</SPAN
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson>. If there is insufficient
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonspace to copy data between the buffer <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafssonlightweight resolver packet <TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ac299c4f5ca236370b9df2a91b18b149b1d344a7Andreas Gustafsson> both functions
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_UNEXPECTEDEND</SPAN