2 - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
3 - Copyright (C) 2000, 2001 Internet Software Consortium.
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.
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.
17 <!-- $Id: lwres_gabn.html,v 1.6.2.1.4.14 2007/01/30 00:11:48 marka Exp $ -->
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>lwres_gabn</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2476275"></a><div class="titlepage"></div>
26 <div class="refnamediv">
28 <p>lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free — lightweight resolver getaddrbyname message handling</p>
30 <div class="refsynopsisdiv">
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre>
34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
36 <td><code class="funcdef">
38 <b class="fsfunc">lwres_gabnrequest_render</b>(</code></td>
59 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
61 <td><code class="funcdef">
63 <b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
84 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
86 <td><code class="funcdef">
88 <b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
109 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
111 <td><code class="funcdef">
113 <b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
134 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
136 <td><code class="funcdef">
138 <b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
149 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
151 <td><code class="funcdef">
153 <b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
166 <div class="refsect1" lang="en">
167 <a name="id2543469"></a><h2>DESCRIPTION</h2>
169 These are low-level routines for creating and parsing
170 lightweight resolver name-to-address lookup request and
174 There are four main functions for the getaddrbyname opcode.
175 One render function converts a getaddrbyname request structure —
176 <span class="type">lwres_gabnrequest_t</span> —
177 to the lighweight resolver's canonical format.
178 It is complemented by a parse function that converts a packet in this
179 canonical format to a getaddrbyname request structure.
180 Another render function converts the getaddrbyname response structure —
181 <span class="type">lwres_gabnresponse_t</span> —
182 to the canonical format.
183 This is complemented by a parse function which converts a packet in
184 canonical format to a getaddrbyname response structure.
187 These structures are defined in
188 <code class="filename"><lwres/lwres.h></code>.
189 They are shown below.
191 <pre class="programlisting">
192 #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
194 typedef struct lwres_addr lwres_addr_t;
195 typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
198 lwres_uint32_t flags;
199 lwres_uint32_t addrtypes;
200 lwres_uint16_t namelen;
202 } lwres_gabnrequest_t;
205 lwres_uint32_t flags;
206 lwres_uint16_t naliases;
207 lwres_uint16_t naddrs;
210 lwres_uint16_t realnamelen;
211 lwres_uint16_t *aliaslen;
212 lwres_addrlist_t addrs;
215 } lwres_gabnresponse_t;
220 <code class="function">lwres_gabnrequest_render()</code>
221 uses resolver context
222 <em class="parameter"><code>ctx</code></em>
223 to convert getaddrbyname request structure
224 <em class="parameter"><code>req</code></em>
226 The packet header structure
227 <em class="parameter"><code>pkt</code></em>
228 is initialised and transferred to
230 <em class="parameter"><code>b</code></em>.
233 <em class="parameter"><code>*req</code></em>
234 are then appended to the buffer in canonical format.
235 <code class="function">lwres_gabnresponse_render()</code>
236 performs the same task, except it converts a getaddrbyname response structure
237 <span class="type">lwres_gabnresponse_t</span>
238 to the lightweight resolver's canonical format.
241 <code class="function">lwres_gabnrequest_parse()</code>
243 <em class="parameter"><code>ctx</code></em>
244 to convert the contents of packet
245 <em class="parameter"><code>pkt</code></em>
247 <span class="type">lwres_gabnrequest_t</span>
250 <em class="parameter"><code>b</code></em>
251 provides space to be used for storing this structure.
252 When the function succeeds, the resulting
253 <span class="type">lwres_gabnrequest_t</span>
254 is made available through
255 <em class="parameter"><code>*structp</code></em>.
257 <code class="function">lwres_gabnresponse_parse()</code>
258 offers the same semantics as
259 <code class="function">lwres_gabnrequest_parse()</code>
261 <span class="type">lwres_gabnresponse_t</span>
265 <code class="function">lwres_gabnresponse_free()</code>
267 <code class="function">lwres_gabnrequest_free()</code>
268 release the memory in resolver context
269 <em class="parameter"><code>ctx</code></em>
270 that was allocated to the
271 <span class="type">lwres_gabnresponse_t</span>
273 <span class="type">lwres_gabnrequest_t</span>
274 structures referenced via
275 <em class="parameter"><code>structp</code></em>.
277 Any memory associated with ancillary buffers and strings for those
278 structures is also discarded.
281 <div class="refsect1" lang="en">
282 <a name="id2543593"></a><h2>RETURN VALUES</h2>
284 The getaddrbyname opcode functions
285 <code class="function">lwres_gabnrequest_render()</code>,
286 <code class="function">lwres_gabnresponse_render()</code>
287 <code class="function">lwres_gabnrequest_parse()</code>
289 <code class="function">lwres_gabnresponse_parse()</code>
291 <span class="errorcode">LWRES_R_SUCCESS</span>
294 <span class="errorcode">LWRES_R_NOMEMORY</span>
295 if memory allocation fails.
296 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
297 is returned if the available space in the buffer
298 <em class="parameter"><code>b</code></em>
299 is too small to accommodate the packet header or the
300 <span class="type">lwres_gabnrequest_t</span>
302 <span class="type">lwres_gabnresponse_t</span>
304 <code class="function">lwres_gabnrequest_parse()</code>
306 <code class="function">lwres_gabnresponse_parse()</code>
308 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
309 if the buffer is not empty after decoding the received packet.
310 These functions will return
311 <span class="errorcode">LWRES_R_FAILURE</span>
313 <em class="structfield"><code>pktflags</code></em>
314 in the packet header structure
315 <span class="type">lwres_lwpacket_t</span>
316 indicate that the packet is not a response to an earlier query.
319 <div class="refsect1" lang="en">
320 <a name="id2543658"></a><h2>SEE ALSO</h2>
322 <span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3