Merge from vendor branch LESS:
[dragonfly.git] / contrib / bind-9.3 / lib / lwres / man / lwres_packet.html
1 <!--
2  - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 2000, 2001 Internet Software Consortium.
4  - 
5  - Permission to use, copy, modify, and 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.
8  - 
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.
16 -->
17 <!-- $Id: lwres_packet.html,v 1.8.2.1.4.9 2005/10/13 02:33:57 marka Exp $ -->
18 <html>
19 <head>
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>lwres_packet</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
23 </head>
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2463721"></a><div class="titlepage"></div>
26 <div class="refnamediv">
27 <h2>Name</h2>
28 <p>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader &#8212; lightweight resolver packet handling functions</p>
29 </div>
30 <div class="refsynopsisdiv">
31 <h2>Synopsis</h2>
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">#include &lt;lwres/lwpacket.h&gt;</pre>
34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
35 <tr>
36 <td><code class="funcdef">
37 lwres_result_t
38 <b class="fsfunc">lwres_lwpacket_renderheader</b>(</code></td>
39 <td> </td>
40 <td>, </td>
41 </tr>
42 <tr>
43 <td> </td>
44 <td> </td>
45 <td>
46 <code>)</code>;</td>
47 </tr>
48 </table>
49 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
50 <tr>
51 <td><code class="funcdef">
52 lwres_result_t
53 <b class="fsfunc">lwres_lwpacket_parseheader</b>(</code></td>
54 <td> </td>
55 <td>, </td>
56 </tr>
57 <tr>
58 <td> </td>
59 <td> </td>
60 <td>
61 <code>)</code>;</td>
62 </tr>
63 </table>
64 </div>
65 </div>
66 <div class="refsect1" lang="en">
67 <a name="id2525865"></a><h2>DESCRIPTION</h2>
68 <p>
69 These functions rely on a
70 <span class="type">struct lwres_lwpacket</span>
71 which is defined in
72 <code class="filename">lwres/lwpacket.h</code>.
73
74 </p>
75 <pre class="programlisting">
76 typedef struct lwres_lwpacket lwres_lwpacket_t;
77
78 struct lwres_lwpacket {
79         lwres_uint32_t          length;
80         lwres_uint16_t          version;
81         lwres_uint16_t          pktflags;
82         lwres_uint32_t          serial;
83         lwres_uint32_t          opcode;
84         lwres_uint32_t          result;
85         lwres_uint32_t          recvlength;
86         lwres_uint16_t          authtype;
87         lwres_uint16_t          authlength;
88 };
89 </pre>
90 <p>
91 </p>
92 <p>
93 The elements of this structure are:
94 </p>
95 <div class="variablelist"><dl>
96 <dt><span class="term"><code class="constant">length</code></span></dt>
97 <dd><p>
98 the overall packet length, including the entire packet header.
99 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
100 calls.
101 </p></dd>
102 <dt><span class="term"><code class="constant">version</code></span></dt>
103 <dd><p>
104 the header format. There is currently only one format,
105 <span class="type">LWRES_LWPACKETVERSION_0</span>.
106
107 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
108 calls.
109 </p></dd>
110 <dt><span class="term"><code class="constant">pktflags</code></span></dt>
111 <dd><p>
112 library-defined flags for this packet: for instance whether the packet
113 is a request or a reply. Flag values can be set, but not defined by
114 the caller.
115 This field is filled in by the application wit the exception of the
116 LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
117 lwres_gabn_*() and lwres_gnba_*() calls.
118 </p></dd>
119 <dt><span class="term"><code class="constant">serial</code></span></dt>
120 <dd><p>
121 is set by the requestor and is returned in all replies. If two or more
122 packets from the same source have the same serial number and are from
123 the same source, they are assumed to be duplicates and the latter ones
124 may be dropped.
125 This field must be set by the application.
126 </p></dd>
127 <dt><span class="term"><code class="constant">opcode</code></span></dt>
128 <dd><p>
129 indicates the operation.
130 Opcodes between 0x00000000 and 0x03ffffff are
131 reserved for use by the lightweight resolver library. Opcodes between
132 0x04000000 and 0xffffffff are application defined.
133 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
134 calls.
135 </p></dd>
136 <dt><span class="term"><code class="constant">result</code></span></dt>
137 <dd><p>
138 is only valid for replies.
139 Results between 0x04000000 and 0xffffffff are application defined.
140 Results between 0x00000000 and 0x03ffffff are reserved for library use.
141 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
142 calls.
143 </p></dd>
144 <dt><span class="term"><code class="constant">recvlength</code></span></dt>
145 <dd><p>
146 is the maximum buffer size that the receiver can handle on requests
147 and the size of the buffer needed to satisfy a request when the buffer
148 is too large for replies.
149 This field is supplied by the application.
150 </p></dd>
151 <dt><span class="term"><code class="constant">authtype</code></span></dt>
152 <dd><p>
153 defines the packet level authentication that is used.
154 Authorisation types between 0x1000 and 0xffff are application defined
155 and types between 0x0000 and 0x0fff are reserved for library use.
156 Currently these are not used and must be zero.
157 </p></dd>
158 <dt><span class="term"><code class="constant">authlen</code></span></dt>
159 <dd><p>
160 gives the length of the authentication data.
161 Since packet authentication is currently not used, this must be zero.
162 </p></dd>
163 </dl></div>
164 <p>
165 </p>
166 <p>
167 The following opcodes are currently defined:
168 </p>
169 <div class="variablelist"><dl>
170 <dt><span class="term"><code class="constant">NOOP</code></span></dt>
171 <dd><p>
172 Success is always returned and the packet contents are echoed.
173 The lwres_noop_*() functions should be used for this type.
174 </p></dd>
175 <dt><span class="term"><code class="constant">GETADDRSBYNAME</code></span></dt>
176 <dd><p>
177 returns all known addresses for a given name.
178 The lwres_gabn_*() functions should be used for this type.
179 </p></dd>
180 <dt><span class="term"><code class="constant">GETNAMEBYADDR</code></span></dt>
181 <dd><p>
182 return the hostname for the given address.
183 The lwres_gnba_*() functions should be used for this type.
184 </p></dd>
185 </dl></div>
186 <p>
187 </p>
188 <p>
189 <code class="function">lwres_lwpacket_renderheader()</code> transfers the
190 contents of lightweight resolver packet structure
191 <span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in network
192 byte order to the lightweight resolver buffer,
193 <em class="parameter"><code>*b</code></em>.
194 </p>
195 <p>
196 <code class="function">lwres_lwpacket_parseheader()</code> performs the
197 converse operation.  It transfers data in network byte order from
198 buffer <em class="parameter"><code>*b</code></em> to resolver packet
199 <em class="parameter"><code>*pkt</code></em>.  The contents of the buffer
200 <em class="parameter"><code>b</code></em> should correspond to a
201 <span class="type">lwres_lwpacket_t</span>.
202 </p>
203 </div>
204 <div class="refsect1" lang="en">
205 <a name="id2526068"></a><h2>RETURN VALUES</h2>
206 <p> Successful calls to
207 <code class="function">lwres_lwpacket_renderheader()</code> and
208 <code class="function">lwres_lwpacket_parseheader()</code> return
209 <span class="errorcode">LWRES_R_SUCCESS</span>.  If there is insufficient
210 space to copy data between the buffer <em class="parameter"><code>*b</code></em> and
211 lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both functions
212 return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>.
213 </p>
214 </div>
215 </div></body>
216 </html>