Merge from vendor branch CVS:
[dragonfly.git] / contrib / bind-9.2.4rc7 / lib / lwres / man / lwres_packet.html
1 <!--
2  - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
3  - Copyright (C) 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
18 <!-- $Id: lwres_packet.html,v 1.8.2.2 2004/03/15 04:45:04 marka Exp $ -->
19
20 <HTML
21 ><HEAD
22 ><TITLE
23 >lwres_packet</TITLE
24 ><META
25 NAME="GENERATOR"
26 CONTENT="Modular DocBook HTML Stylesheet Version 1.73
27 "></HEAD
28 ><BODY
29 CLASS="REFENTRY"
30 BGCOLOR="#FFFFFF"
31 TEXT="#000000"
32 LINK="#0000FF"
33 VLINK="#840084"
34 ALINK="#0000FF"
35 ><H1
36 ><A
37 NAME="AEN1"
38 >lwres_packet</A
39 ></H1
40 ><DIV
41 CLASS="REFNAMEDIV"
42 ><A
43 NAME="AEN8"
44 ></A
45 ><H2
46 >Name</H2
47 >lwres_lwpacket_renderheader, lwres_lwpacket_parseheader&nbsp;--&nbsp;lightweight resolver packet handling functions</DIV
48 ><DIV
49 CLASS="REFSYNOPSISDIV"
50 ><A
51 NAME="AEN12"
52 ></A
53 ><H2
54 >Synopsis</H2
55 ><DIV
56 CLASS="FUNCSYNOPSIS"
57 ><A
58 NAME="AEN13"
59 ></A
60 ><P
61 ></P
62 ><PRE
63 CLASS="FUNCSYNOPSISINFO"
64 >#include &lt;lwres/lwpacket.h&gt;</PRE
65 ><P
66 ><CODE
67 ><CODE
68 CLASS="FUNCDEF"
69 >lwres_result_t
70 lwres_lwpacket_renderheader</CODE
71 >(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
72 ></P
73 ><P
74 ><CODE
75 ><CODE
76 CLASS="FUNCDEF"
77 >lwres_result_t
78 lwres_lwpacket_parseheader</CODE
79 >(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
80 ></P
81 ><P
82 ></P
83 ></DIV
84 ></DIV
85 ><DIV
86 CLASS="REFSECT1"
87 ><A
88 NAME="AEN25"
89 ></A
90 ><H2
91 >DESCRIPTION</H2
92 ><P
93 >These functions rely on a
94 <SPAN
95 CLASS="TYPE"
96 >struct lwres_lwpacket</SPAN
97 >
98 which is defined in
99 <TT
100 CLASS="FILENAME"
101 >lwres/lwpacket.h</TT
102 >.
103
104 <PRE
105 CLASS="PROGRAMLISTING"
106 >typedef struct lwres_lwpacket lwres_lwpacket_t;
107
108 struct lwres_lwpacket {
109         lwres_uint32_t          length;
110         lwres_uint16_t          version;
111         lwres_uint16_t          pktflags;
112         lwres_uint32_t          serial;
113         lwres_uint32_t          opcode;
114         lwres_uint32_t          result;
115         lwres_uint32_t          recvlength;
116         lwres_uint16_t          authtype;
117         lwres_uint16_t          authlength;
118 };</PRE
119 ></P
120 ><P
121 >The elements of this structure are:
122 <P
123 ></P
124 ><DIV
125 CLASS="VARIABLELIST"
126 ><DL
127 ><DT
128 ><TT
129 CLASS="CONSTANT"
130 >length</TT
131 ></DT
132 ><DD
133 ><P
134 >the overall packet length, including the entire packet header.
135 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
136 calls.</P
137 ></DD
138 ><DT
139 ><TT
140 CLASS="CONSTANT"
141 >version</TT
142 ></DT
143 ><DD
144 ><P
145 >the header format. There is currently only one format,
146 <SPAN
147 CLASS="TYPE"
148 >LWRES_LWPACKETVERSION_0</SPAN
149 >.
150
151 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
152 calls.</P
153 ></DD
154 ><DT
155 ><TT
156 CLASS="CONSTANT"
157 >pktflags</TT
158 ></DT
159 ><DD
160 ><P
161 >library-defined flags for this packet: for instance whether the packet
162 is a request or a reply. Flag values can be set, but not defined by
163 the caller.
164 This field is filled in by the application wit the exception of the
165 LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
166 lwres_gabn_*() and lwres_gnba_*() calls.</P
167 ></DD
168 ><DT
169 ><TT
170 CLASS="CONSTANT"
171 >serial</TT
172 ></DT
173 ><DD
174 ><P
175 >is set by the requestor and is returned in all replies. If two or more
176 packets from the same source have the same serial number and are from
177 the same source, they are assumed to be duplicates and the latter ones
178 may be dropped.
179 This field must be set by the application.</P
180 ></DD
181 ><DT
182 ><TT
183 CLASS="CONSTANT"
184 >opcode</TT
185 ></DT
186 ><DD
187 ><P
188 >indicates the operation.
189 Opcodes between 0x00000000 and 0x03ffffff are
190 reserved for use by the lightweight resolver library. Opcodes between
191 0x04000000 and 0xffffffff are application defined.
192 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
193 calls.</P
194 ></DD
195 ><DT
196 ><TT
197 CLASS="CONSTANT"
198 >result</TT
199 ></DT
200 ><DD
201 ><P
202 >is only valid for replies.
203 Results between 0x04000000 and 0xffffffff are application defined.
204 Results between 0x00000000 and 0x03ffffff are reserved for library use.
205 This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
206 calls.</P
207 ></DD
208 ><DT
209 ><TT
210 CLASS="CONSTANT"
211 >recvlength</TT
212 ></DT
213 ><DD
214 ><P
215 >is the maximum buffer size that the receiver can handle on requests
216 and the size of the buffer needed to satisfy a request when the buffer
217 is too large for replies.
218 This field is supplied by the application.</P
219 ></DD
220 ><DT
221 ><TT
222 CLASS="CONSTANT"
223 >authtype</TT
224 ></DT
225 ><DD
226 ><P
227 >defines the packet level authentication that is used.
228 Authorisation types between 0x1000 and 0xffff are application defined
229 and types between 0x0000 and 0x0fff are reserved for library use.
230 Currently these are not used and must be zero.</P
231 ></DD
232 ><DT
233 ><TT
234 CLASS="CONSTANT"
235 >authlen</TT
236 ></DT
237 ><DD
238 ><P
239 >gives the length of the authentication data.
240 Since packet authentication is currently not used, this must be zero.</P
241 ></DD
242 ></DL
243 ></DIV
244 ></P
245 ><P
246 >The following opcodes are currently defined:
247 <P
248 ></P
249 ><DIV
250 CLASS="VARIABLELIST"
251 ><DL
252 ><DT
253 ><TT
254 CLASS="CONSTANT"
255 >NOOP</TT
256 ></DT
257 ><DD
258 ><P
259 >Success is always returned and the packet contents are echoed.
260 The lwres_noop_*() functions should be used for this type.</P
261 ></DD
262 ><DT
263 ><TT
264 CLASS="CONSTANT"
265 >GETADDRSBYNAME</TT
266 ></DT
267 ><DD
268 ><P
269 >returns all known addresses for a given name.
270 The lwres_gabn_*() functions should be used for this type.</P
271 ></DD
272 ><DT
273 ><TT
274 CLASS="CONSTANT"
275 >GETNAMEBYADDR</TT
276 ></DT
277 ><DD
278 ><P
279 >return the hostname for the given address.
280 The lwres_gnba_*() functions should be used for this type.</P
281 ></DD
282 ></DL
283 ></DIV
284 ></P
285 ><P
286 ><TT
287 CLASS="FUNCTION"
288 >lwres_lwpacket_renderheader()</TT
289 > transfers the
290 contents of lightweight resolver packet structure
291 <SPAN
292 CLASS="TYPE"
293 >lwres_lwpacket_t</SPAN
294 > <TT
295 CLASS="PARAMETER"
296 ><I
297 >*pkt</I
298 ></TT
299 > in network
300 byte order to the lightweight resolver buffer,
301 <TT
302 CLASS="PARAMETER"
303 ><I
304 >*b</I
305 ></TT
306 >.</P
307 ><P
308 ><TT
309 CLASS="FUNCTION"
310 >lwres_lwpacket_parseheader()</TT
311 > performs the
312 converse operation.  It transfers data in network byte order from
313 buffer <TT
314 CLASS="PARAMETER"
315 ><I
316 >*b</I
317 ></TT
318 > to resolver packet
319 <TT
320 CLASS="PARAMETER"
321 ><I
322 >*pkt</I
323 ></TT
324 >.  The contents of the buffer
325 <TT
326 CLASS="PARAMETER"
327 ><I
328 >b</I
329 ></TT
330 > should correspond to a
331 <SPAN
332 CLASS="TYPE"
333 >lwres_lwpacket_t</SPAN
334 >.</P
335 ></DIV
336 ><DIV
337 CLASS="REFSECT1"
338 ><A
339 NAME="AEN107"
340 ></A
341 ><H2
342 >RETURN VALUES</H2
343 ><P
344 > Successful calls to
345 <TT
346 CLASS="FUNCTION"
347 >lwres_lwpacket_renderheader()</TT
348 > and
349 <TT
350 CLASS="FUNCTION"
351 >lwres_lwpacket_parseheader()</TT
352 > return
353 <SPAN
354 CLASS="ERRORCODE"
355 >LWRES_R_SUCCESS</SPAN
356 >.  If there is insufficient
357 space to copy data between the buffer <TT
358 CLASS="PARAMETER"
359 ><I
360 >*b</I
361 ></TT
362 > and
363 lightweight resolver packet <TT
364 CLASS="PARAMETER"
365 ><I
366 >*pkt</I
367 ></TT
368 > both functions
369 return <SPAN
370 CLASS="ERRORCODE"
371 >LWRES_R_UNEXPECTEDEND</SPAN
372 >.</P
373 ></DIV
374 ></BODY
375 ></HTML
376 >