lwres_packet.html revision 010a51c427bfb6ab658fc0056955a1a5b69810be
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
a02a0a8a7eb461619931f4a0e896afa247b52c54Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews - Permission to use, copy, modify, and/or distribute this software for any
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - purpose with or without fee is hereby granted, provided that the above
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - copyright notice and this permission notice appear in all copies.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
0756445a735e2df39bf798d8de42ae5dd030aa3bMark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews - PERFORMANCE OF THIS SOFTWARE.
a02a0a8a7eb461619931f4a0e896afa247b52c54Mark Andrews<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
0756445a735e2df39bf798d8de42ae5dd030aa3bMark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres_packet">
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<a name="idp60761424"></a><div class="titlepage"></div>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews lwres_lwpacket_renderheader,
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews lwres_lwpacket_parseheader
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews — lightweight resolver packet handling functions
a0624cf8d5711cca4e3907859fbc8062a7e460faMark Andrews<pre class="funcsynopsisinfo">#include <lwres/lwpacket.h></pre>
a0624cf8d5711cca4e3907859fbc8062a7e460faMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrewslwres_result_t
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<b class="fsfunc">lwres_lwpacket_renderheader</b>(</code></td>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<td>lwres_lwpacket_t *<var class="pdparam">pkt</var><code>)</code>;</td>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
068a66979695c77359e7a9181bb3f831c965b21cMark Andrewslwres_result_t
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<b class="fsfunc">lwres_lwpacket_parseheader</b>(</code></td>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<td>lwres_lwpacket_t *<var class="pdparam">pkt</var><code>)</code>;</td>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson These functions rely on a
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <span class="type">struct lwres_lwpacket</span>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson which is defined in
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <code class="filename">lwres/lwpacket.h</code>.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssontypedef struct lwres_lwpacket lwres_lwpacket_t;
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellingtonstruct lwres_lwpacket {
c25080dc50542213058c240226c9f342186e6285Mark Andrews lwres_uint32_t length;
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews lwres_uint16_t version;
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews lwres_uint16_t pktflags;
413988c8166976498250c0ebb2e3a645d0366bd3Mark Andrews lwres_uint32_t serial;
0756445a735e2df39bf798d8de42ae5dd030aa3bMark Andrews lwres_uint32_t opcode;
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews lwres_uint32_t result;
c25080dc50542213058c240226c9f342186e6285Mark Andrews lwres_uint32_t recvlength;
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews lwres_uint16_t authtype;
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews lwres_uint16_t authlength;
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews The elements of this structure are:
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<dt><span class="term"><code class="constant">length</code></span></dt>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews the overall packet length, including the entire packet header.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<dt><span class="term"><code class="constant">version</code></span></dt>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews the header format. There is currently only one format,
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews <span class="type">LWRES_LWPACKETVERSION_0</span>.
413988c8166976498250c0ebb2e3a645d0366bd3Mark Andrews This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<dt><span class="term"><code class="constant">pktflags</code></span></dt>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews library-defined flags for this packet: for instance whether the
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews is a request or a reply. Flag values can be set, but not defined
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews This field is filled in by the application wit the exception of
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews lwres_gabn_*() and lwres_gnba_*() calls.
c25080dc50542213058c240226c9f342186e6285Mark Andrews<dt><span class="term"><code class="constant">serial</code></span></dt>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews is set by the requestor and is returned in all replies. If two
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews packets from the same source have the same serial number and are
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews the same source, they are assumed to be duplicates and the
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews may be dropped.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington This field must be set by the application.
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<dt><span class="term"><code class="constant">opcode</code></span></dt>
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews indicates the operation.
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson Opcodes between 0x00000000 and 0x03ffffff are
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson reserved for use by the lightweight resolver library. Opcodes
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews 0x04000000 and 0xffffffff are application defined.
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<dt><span class="term"><code class="constant">result</code></span></dt>
fd42a013f17611b34cd49cc0abee0a6b0d251a6bMark Andrews is only valid for replies.
09344332cf7840e7e219215128fd52ea4c3d6942Mark Andrews Results between 0x04000000 and 0xffffffff are application
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson Results between 0x00000000 and 0x03ffffff are reserved for
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews library use.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews<dt><span class="term"><code class="constant">recvlength</code></span></dt>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews is the maximum buffer size that the receiver can handle on
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews and the size of the buffer needed to satisfy a request when the
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews is too large for replies.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews This field is supplied by the application.
e076d0c88be69de7c190ab924d095e69d2e11f7aAndreas Gustafsson<dt><span class="term"><code class="constant">authtype</code></span></dt>
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews defines the packet level authentication that is used.
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews Authorisation types between 0x1000 and 0xffff are application
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson and types between 0x0000 and 0x0fff are reserved for library
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews Currently these are not used and must be zero.
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews<dt><span class="term"><code class="constant">authlen</code></span></dt>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington gives the length of the authentication data.
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews Since packet authentication is currently not used, this must be
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The following opcodes are currently defined:
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<dt><span class="term"><code class="constant">NOOP</code></span></dt>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Success is always returned and the packet contents are echoed.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The lwres_noop_*() functions should be used for this type.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<dt><span class="term"><code class="constant">GETADDRSBYNAME</code></span></dt>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington returns all known addresses for a given name.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The lwres_gabn_*() functions should be used for this type.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<dt><span class="term"><code class="constant">GETNAMEBYADDR</code></span></dt>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington return the hostname for the given address.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington The lwres_gnba_*() functions should be used for this type.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <p><code class="function">lwres_lwpacket_renderheader()</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington transfers the contents of lightweight resolver packet structure
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington network byte order to the lightweight resolver buffer,
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>*b</code></em>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <p><code class="function">lwres_lwpacket_parseheader()</code>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington performs the converse operation. It transfers data in network
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington byte order from buffer <em class="parameter"><code>*b</code></em> to resolver
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington packet <em class="parameter"><code>*pkt</code></em>. The contents of the buffer
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <em class="parameter"><code>b</code></em> should correspond to a
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <span class="type">lwres_lwpacket_t</span>.
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <div class="refsection" title="RETURN VALUES">
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington<a name="idp60827728"></a><h2>RETURN VALUES</h2>
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington Successful calls to
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_lwpacket_renderheader()</code> and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington <code class="function">lwres_lwpacket_parseheader()</code> return
75216e007570b8ea36b3ac9cca096bf70c0ca6f6Mark Andrews <span class="errorcode">LWRES_R_SUCCESS</span>. If there is insufficient
068a66979695c77359e7a9181bb3f831c965b21cMark Andrews space to copy data between the buffer <em class="parameter"><code>*b</code></em> and
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>.