2 - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
3 - Copyright (C) 2000, 2001 Internet Software Consortium.
5 - Permission to use, copy, modify, and/or distribute this software for any
6 - purpose with or without fee is hereby granted, provided that the above
7 - copyright notice and this permission notice appear in all copies.
9 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 - PERFORMANCE OF THIS SOFTWARE.
19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
20 <title>lwres_packet</title>
21 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
23 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
24 <a name="id-1"></a><div class="titlepage"></div>
25 <div class="refnamediv">
27 <p>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader — lightweight resolver packet handling functions</p>
29 <div class="refsynopsisdiv">
31 <div class="funcsynopsis">
32 <pre class="funcsynopsisinfo">#include <lwres/lwpacket.h></pre>
33 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
35 <td><code class="funcdef">
37 <b class="fsfunc">lwres_lwpacket_renderheader</b>(</code></td>
38 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
42 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var><code>)</code>;</td>
45 <div class="funcprototype-spacer"> </div>
46 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
48 <td><code class="funcdef">
50 <b class="fsfunc">lwres_lwpacket_parseheader</b>(</code></td>
51 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
55 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var><code>)</code>;</td>
58 <div class="funcprototype-spacer"> </div>
61 <div class="refsection">
62 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
64 These functions rely on a
65 <span class="type">struct lwres_lwpacket</span>
67 <code class="filename">lwres/lwpacket.h</code>.
69 <pre class="programlisting">
70 typedef struct lwres_lwpacket lwres_lwpacket_t;
74 <pre class="programlisting">
75 struct lwres_lwpacket {
76 lwres_uint32_t length;
77 lwres_uint16_t version;
78 lwres_uint16_t pktflags;
79 lwres_uint32_t serial;
80 lwres_uint32_t opcode;
81 lwres_uint32_t result;
82 lwres_uint32_t recvlength;
83 lwres_uint16_t authtype;
84 lwres_uint16_t authlength;
90 The elements of this structure are:
92 <div class="variablelist"><dl class="variablelist">
93 <dt><span class="term"><code class="constant">length</code></span></dt>
95 the overall packet length, including the entire packet header.
96 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
99 <dt><span class="term"><code class="constant">version</code></span></dt>
101 the header format. There is currently only one format,
102 <span class="type">LWRES_LWPACKETVERSION_0</span>.
104 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
107 <dt><span class="term"><code class="constant">pktflags</code></span></dt>
109 library-defined flags for this packet: for instance whether the
111 is a request or a reply. Flag values can be set, but not defined
114 This field is filled in by the application wit the exception of
116 LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
118 lwres_gabn_*() and lwres_gnba_*() calls.
120 <dt><span class="term"><code class="constant">serial</code></span></dt>
122 is set by the requestor and is returned in all replies. If two
124 packets from the same source have the same serial number and are
126 the same source, they are assumed to be duplicates and the
129 This field must be set by the application.
131 <dt><span class="term"><code class="constant">opcode</code></span></dt>
133 indicates the operation.
134 Opcodes between 0x00000000 and 0x03ffffff are
135 reserved for use by the lightweight resolver library. Opcodes
137 0x04000000 and 0xffffffff are application defined.
138 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
141 <dt><span class="term"><code class="constant">result</code></span></dt>
143 is only valid for replies.
144 Results between 0x04000000 and 0xffffffff are application
146 Results between 0x00000000 and 0x03ffffff are reserved for
148 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
151 <dt><span class="term"><code class="constant">recvlength</code></span></dt>
153 is the maximum buffer size that the receiver can handle on
155 and the size of the buffer needed to satisfy a request when the
157 is too large for replies.
158 This field is supplied by the application.
160 <dt><span class="term"><code class="constant">authtype</code></span></dt>
162 defines the packet level authentication that is used.
163 Authorisation types between 0x1000 and 0xffff are application
165 and types between 0x0000 and 0x0fff are reserved for library
167 Currently these are not used and must be zero.
169 <dt><span class="term"><code class="constant">authlen</code></span></dt>
171 gives the length of the authentication data.
172 Since packet authentication is currently not used, this must be
179 The following opcodes are currently defined:
181 <div class="variablelist"><dl class="variablelist">
182 <dt><span class="term"><code class="constant">NOOP</code></span></dt>
184 Success is always returned and the packet contents are echoed.
185 The lwres_noop_*() functions should be used for this type.
187 <dt><span class="term"><code class="constant">GETADDRSBYNAME</code></span></dt>
189 returns all known addresses for a given name.
190 The lwres_gabn_*() functions should be used for this type.
192 <dt><span class="term"><code class="constant">GETNAMEBYADDR</code></span></dt>
194 return the hostname for the given address.
195 The lwres_gnba_*() functions should be used for this type.
200 <p><code class="function">lwres_lwpacket_renderheader()</code>
201 transfers the contents of lightweight resolver packet structure
202 <span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in
203 network byte order to the lightweight resolver buffer,
204 <em class="parameter"><code>*b</code></em>.
206 <p><code class="function">lwres_lwpacket_parseheader()</code>
207 performs the converse operation. It transfers data in network
208 byte order from buffer <em class="parameter"><code>*b</code></em> to resolver
209 packet <em class="parameter"><code>*pkt</code></em>. The contents of the buffer
210 <em class="parameter"><code>b</code></em> should correspond to a
211 <span class="type">lwres_lwpacket_t</span>.
214 <div class="refsection">
215 <a name="id-1.8"></a><h2>RETURN VALUES</h2>
218 <code class="function">lwres_lwpacket_renderheader()</code> and
219 <code class="function">lwres_lwpacket_parseheader()</code> return
220 <span class="errorcode">LWRES_R_SUCCESS</span>. If there is insufficient
221 space to copy data between the buffer <em class="parameter"><code>*b</code></em> and
222 lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both
224 return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>.