lwres_packet.html revision 2eeb74d1cf5355dd98f6d507a10086e16bb08c4b
794b79e6bbc3f5db1ea6ae154d739b9f1ef1a375Tinderbox User - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
75c0816e8295e180f4bc7f10db3d0d880383bc1cMark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721Automatic Updater - Permission to use, copy, modify, and/or 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
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein - 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.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres_packet">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<a name="idp60887888"></a><div class="titlepage"></div>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_lwpacket_renderheader,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User lwres_lwpacket_parseheader
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User — lightweight resolver packet handling functions
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <div class="refsynopsisdiv" title="Synopsis">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<pre class="funcsynopsisinfo">#include <lwres/lwpacket.h></pre>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_lwpacket_renderheader</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeinlwres_result_t
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<b class="fsfunc">lwres_lwpacket_parseheader</b>(</code></td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<td>lwres_lwpacket_t *<var class="pdparam">pkt</var><code>)</code>;</td>
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<a name="idp60919760"></a><h2>DESCRIPTION</h2>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein These functions rely on a
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein which is defined in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austeintypedef 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;
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The elements of this structure are:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">length</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the overall packet length, including the entire packet header.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">version</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the header format. There is currently only one format,
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">LWRES_LWPACKETVERSION_0</span>.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">pktflags</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein library-defined flags for this packet: for instance whether the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is a request or a reply. Flag values can be set, but not defined
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field is filled in by the application wit the exception of
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lwres_gabn_*() and lwres_gnba_*() calls.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">serial</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is set by the requestor and is returned in all replies. If two
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein packets from the same source have the same serial number and are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein the same source, they are assumed to be duplicates and the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein may be dropped.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field must be set by the application.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">opcode</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein indicates the operation.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Opcodes between 0x00000000 and 0x03ffffff are
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein reserved for use by the lightweight resolver library. Opcodes
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein 0x04000000 and 0xffffffff are application defined.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">result</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is only valid for replies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Results between 0x04000000 and 0xffffffff are application
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Results between 0x00000000 and 0x03ffffff are reserved for
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein library use.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">recvlength</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is the maximum buffer size that the receiver can handle on
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and the size of the buffer needed to satisfy a request when the
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein is too large for replies.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein This field is supplied by the application.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">authtype</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein defines the packet level authentication that is used.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Authorisation types between 0x1000 and 0xffff are application
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein and types between 0x0000 and 0x0fff are reserved for library
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Currently these are not used and must be zero.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">authlen</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein gives the length of the authentication data.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Since packet authentication is currently not used, this must be
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The following opcodes are currently defined:
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">NOOP</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Success is always returned and the packet contents are echoed.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The lwres_noop_*() functions should be used for this type.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">GETADDRSBYNAME</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein returns all known addresses for a given name.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The lwres_gabn_*() functions should be used for this type.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein<dt><span class="term"><code class="constant">GETNAMEBYADDR</code></span></dt>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein return the hostname for the given address.
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein The lwres_gnba_*() functions should be used for this type.
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <p><code class="function">lwres_lwpacket_renderheader()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein transfers the contents of lightweight resolver packet structure
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein network byte order to the lightweight resolver buffer,
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <p><code class="function">lwres_lwpacket_parseheader()</code>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein performs the converse operation. It transfers data in network
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein byte order from buffer <em class="parameter"><code>*b</code></em> to resolver
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein packet <em class="parameter"><code>*pkt</code></em>. The contents of the buffer
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <em class="parameter"><code>b</code></em> should correspond to a
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User <div class="refsection" title="RETURN VALUES">
2eeb74d1cf5355dd98f6d507a10086e16bb08c4bTinderbox User<a name="idp60953808"></a><h2>RETURN VALUES</h2>
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein Successful calls to
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_lwpacket_renderheader()</code> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <code class="function">lwres_lwpacket_parseheader()</code> return
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein <span class="errorcode">LWRES_R_SUCCESS</span>. If there is insufficient
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein space to copy data between the buffer <em class="parameter"><code>*b</code></em> and
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both
60e5e10f8d2e2b0c41e8abad38cacd867caa6ab2Rob Austein return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>.