lwres_packet.html revision 8eea877894ea5bcf5cdd9ca124a8601ad421d753
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson - Copyright (C) 2000, 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.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_packet</TITLE
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonNAME="GENERATOR"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCONTENT="Modular DocBook HTML Stylesheet Version 1.61
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
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontransfers the contents of lightweight resolver packet structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin network byte order to the lightweight resolver buffer,
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="FUNCTION"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_parseheader()</TT
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms the converse operation.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt transfers data in network byte order from buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto resolver packet
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe contents of the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonshould correspond to a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>lwres_lwpacket_t</SPAN
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>Both functions have assertion checks to ensure that
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="REFSECT1"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>RETURN VALUES</H2
ddccd5811feff696ba460dabfb666ce61040f545Andreas 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
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIf there is insufficient space to copy data between the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonand lightweight resolver packet
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="PARAMETER"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonboth functions return
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonCLASS="ERRORCODE"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson>LWRES_R_UNEXPECTEDEND</SPAN