lwres_packet.html revision 2cd182921e1b04ccda0a56995c4cc491c882af04
235N/A<!--
235N/A - Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
822N/A - Copyright (C) 2001 Internet Software Consortium.
822N/A -
822N/A - Permission to use, copy, modify, and distribute this software for any
235N/A - purpose with or without fee is hereby granted, provided that the above
935N/A - copyright notice and this permission notice appear in all copies.
235N/A -
235N/A - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
919N/A - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
919N/A - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
919N/A - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
919N/A - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
919N/A - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
919N/A - PERFORMANCE OF THIS SOFTWARE.
919N/A-->
919N/A
919N/A<!-- $Id: lwres_packet.html,v 1.12 2004/08/23 00:05:48 marka Exp $ -->
919N/A
919N/A<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
919N/A<HTML
919N/A><HEAD
919N/A><TITLE
919N/A>lwres_packet</TITLE
919N/A><META
919N/ANAME="GENERATOR"
235N/ACONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
235N/A><BODY
235N/ACLASS="REFENTRY"
235N/ABGCOLOR="#FFFFFF"
822N/ATEXT="#000000"
235N/ALINK="#0000FF"
235N/AVLINK="#840084"
822N/AALINK="#0000FF"
235N/A><H1
911N/A><A
911N/ANAME="AEN1"
911N/A></A
911N/A>lwres_packet</H1
235N/A><DIV
493N/ACLASS="REFNAMEDIV"
493N/A><A
235N/ANAME="AEN8"
235N/A></A
235N/A><H2
235N/A>Name</H2
822N/A>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader&nbsp;--&nbsp;lightweight resolver packet handling functions</DIV
235N/A><DIV
235N/ACLASS="REFSYNOPSISDIV"
822N/A><A
235N/ANAME="AEN12"
235N/A></A
235N/A><H2
235N/A>Synopsis</H2
235N/A><DIV
851N/ACLASS="FUNCSYNOPSIS"
851N/A><P
851N/A></P
851N/A><A
822N/ANAME="AEN13"
851N/A></A
851N/A><PRE
822N/ACLASS="FUNCSYNOPSISINFO"
822N/A>#include &lt;lwres/lwpacket.h&gt;</PRE
822N/A><P
865N/A><CODE
949N/A><CODE
949N/ACLASS="FUNCDEF"
235N/A>lwres_result_t
947N/Alwres_lwpacket_renderheader</CODE
235N/A>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
247N/A></P
947N/A><P
235N/A><CODE
247N/A><CODE
947N/ACLASS="FUNCDEF"
947N/A>lwres_result_t
947N/Alwres_lwpacket_parseheader</CODE
947N/A>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
947N/A></P
947N/A><P
947N/A></P
947N/A></DIV
947N/A></DIV
947N/A><DIV
947N/ACLASS="REFSECT1"
235N/A><A
241N/ANAME="AEN25"
493N/A></A
493N/A><H2
235N/A>DESCRIPTION</H2
493N/A><P
493N/A>These functions rely on a
963N/A<SPAN
963N/ACLASS="TYPE"
493N/A>struct lwres_lwpacket</SPAN
493N/A>
822N/Awhich is defined in
822N/A<TT
822N/ACLASS="FILENAME"
493N/A>lwres/lwpacket.h</TT
822N/A>.
822N/A
822N/A<PRE
493N/ACLASS="PROGRAMLISTING"
235N/A>typedef struct lwres_lwpacket lwres_lwpacket_t;
916N/A
916N/Astruct lwres_lwpacket {
916N/A lwres_uint32_t length;
916N/A lwres_uint16_t version;
916N/A lwres_uint16_t pktflags;
916N/A lwres_uint32_t serial;
916N/A lwres_uint32_t opcode;
916N/A lwres_uint32_t result;
963N/A lwres_uint32_t recvlength;
963N/A lwres_uint16_t authtype;
963N/A lwres_uint16_t authlength;
963N/A};</PRE
822N/A></P
235N/A><P
235N/A>The elements of this structure are:
822N/A<P
822N/A></P
963N/A><DIV
963N/ACLASS="VARIABLELIST"
935N/A><DL
935N/A><DT
935N/A><CODE
935N/ACLASS="CONSTANT"
935N/A>length</CODE
935N/A></DT
235N/A><DD
935N/A><P
963N/A>the overall packet length, including the entire packet header.
963N/AThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
935N/Acalls.</P
963N/A></DD
935N/A><DT
963N/A><CODE
963N/ACLASS="CONSTANT"
963N/A>version</CODE
235N/A></DT
963N/A><DD
235N/A><P
935N/A>the header format. There is currently only one format,
935N/A<SPAN
963N/ACLASS="TYPE"
963N/A>LWRES_LWPACKETVERSION_0</SPAN
935N/A>.
963N/A
963N/AThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
963N/Acalls.</P
235N/A></DD
493N/A><DT
493N/A><CODE
493N/ACLASS="CONSTANT"
851N/A>pktflags</CODE
235N/A></DT
493N/A><DD
493N/A><P
822N/A>library-defined flags for this packet: for instance whether the packet
606N/Ais a request or a reply. Flag values can be set, but not defined by
822N/Athe caller.
822N/AThis field is filled in by the application wit the exception of the
822N/ALWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
235N/Alwres_gabn_*() and lwres_gnba_*() calls.</P
493N/A></DD
822N/A><DT
241N/A><CODE
235N/ACLASS="CONSTANT"
493N/A>serial</CODE
235N/A></DT
493N/A><DD
235N/A><P
235N/A>is set by the requestor and is returned in all replies. If two or more
493N/Apackets from the same source have the same serial number and are from
493N/Athe same source, they are assumed to be duplicates and the latter ones
493N/Amay be dropped.
235N/AThis field must be set by the application.</P
454N/A></DD
454N/A><DT
454N/A><CODE
454N/ACLASS="CONSTANT"
454N/A>opcode</CODE
235N/A></DT
454N/A><DD
454N/A><P
493N/A>indicates the operation.
235N/AOpcodes between 0x00000000 and 0x03ffffff are
606N/Areserved for use by the lightweight resolver library. Opcodes between
606N/A0x04000000 and 0xffffffff are application defined.
606N/AThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
606N/Acalls.</P
235N/A></DD
922N/A><DT
599N/A><CODE
599N/ACLASS="CONSTANT"
493N/A>result</CODE
599N/A></DT
599N/A><DD
493N/A><P
235N/A>is only valid for replies.
822N/AResults between 0x04000000 and 0xffffffff are application defined.
235N/AResults between 0x00000000 and 0x03ffffff are reserved for library use.
922N/AThis field is filled in by the lwres_gabn_*() and lwres_gnba_*()
235N/Acalls.</P
599N/A></DD
599N/A><DT
235N/A><CODE
822N/ACLASS="CONSTANT"
606N/A>recvlength</CODE
606N/A></DT
606N/A><DD
606N/A><P
235N/A>is the maximum buffer size that the receiver can handle on requests
822N/Aand the size of the buffer needed to satisfy a request when the buffer
235N/Ais too large for replies.
606N/AThis field is supplied by the application.</P
606N/A></DD
822N/A><DT
822N/A><CODE
247N/ACLASS="CONSTANT"
235N/A>authtype</CODE
235N/A></DT
963N/A><DD
235N/A><P
235N/A>defines the packet level authentication that is used.
247N/AAuthorisation types between 0x1000 and 0xffff are application defined
822N/Aand types between 0x0000 and 0x0fff are reserved for library use.
247N/ACurrently these are not used and must be zero.</P
963N/A></DD
235N/A><DT
963N/A><CODE
235N/ACLASS="CONSTANT"
963N/A>authlen</CODE
235N/A></DT
963N/A><DD
247N/A><P
963N/A>gives the length of the authentication data.
963N/ASince packet authentication is currently not used, this must be zero.</P
822N/A></DD
963N/A></DL
963N/A></DIV
822N/A></P
822N/A><P
822N/A>The following opcodes are currently defined:
822N/A<P
822N/A></P
822N/A><DIV
822N/ACLASS="VARIABLELIST"
822N/A><DL
822N/A><DT
822N/A><CODE
922N/ACLASS="CONSTANT"
822N/A>NOOP</CODE
822N/A></DT
822N/A><DD
822N/A><P
822N/A>Success is always returned and the packet contents are echoed.
822N/AThe lwres_noop_*() functions should be used for this type.</P
822N/A></DD
922N/A><DT
822N/A><CODE
822N/ACLASS="CONSTANT"
822N/A>GETADDRSBYNAME</CODE
822N/A></DT
822N/A><DD
822N/A><P
822N/A>returns all known addresses for a given name.
822N/AThe lwres_gabn_*() functions should be used for this type.</P
822N/A></DD
822N/A><DT
822N/A><CODE
822N/ACLASS="CONSTANT"
963N/A>GETNAMEBYADDR</CODE
></DT
><DD
><P
>return the hostname for the given address.
The lwres_gnba_*() functions should be used for this type.</P
></DD
></DL
></DIV
></P
><P
><CODE
CLASS="FUNCTION"
>lwres_lwpacket_renderheader()</CODE
> transfers the
contents of lightweight resolver packet structure
<SPAN
CLASS="TYPE"
>lwres_lwpacket_t</SPAN
> <VAR
CLASS="PARAMETER"
>*pkt</VAR
> in network
byte order to the lightweight resolver buffer,
<VAR
CLASS="PARAMETER"
>*b</VAR
>.</P
><P
><CODE
CLASS="FUNCTION"
>lwres_lwpacket_parseheader()</CODE
> performs the
converse operation. It transfers data in network byte order from
buffer <VAR
CLASS="PARAMETER"
>*b</VAR
> to resolver packet
<VAR
CLASS="PARAMETER"
>*pkt</VAR
>. The contents of the buffer
<VAR
CLASS="PARAMETER"
>b</VAR
> should correspond to a
<SPAN
CLASS="TYPE"
>lwres_lwpacket_t</SPAN
>.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN107"
></A
><H2
>RETURN VALUES</H2
><P
> Successful calls to
<CODE
CLASS="FUNCTION"
>lwres_lwpacket_renderheader()</CODE
> and
<CODE
CLASS="FUNCTION"
>lwres_lwpacket_parseheader()</CODE
> return
<SPAN
CLASS="ERRORCODE"
>LWRES_R_SUCCESS</SPAN
>. If there is insufficient
space to copy data between the buffer <VAR
CLASS="PARAMETER"
>*b</VAR
> and
lightweight resolver packet <VAR
CLASS="PARAMETER"
>*pkt</VAR
> both functions
return <SPAN
CLASS="ERRORCODE"
>LWRES_R_UNEXPECTEDEND</SPAN
>.</P
></DIV
></BODY
></HTML
>