2 - Copyright (C) 2004, 2005 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_gnba.html,v 1.6.2.1.4.9 2005/10/13 02:33:57 marka Exp $ -->
20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
21 <title>lwres_gnba</title>
22 <meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
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">
28 <p>lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free — lightweight resolver getnamebyaddress message handling</p>
30 <div class="refsynopsisdiv">
32 <div class="funcsynopsis">
33 <pre class="funcsynopsisinfo">
34 #include <lwres/lwres.h>
36 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
38 <td><code class="funcdef">
40 <b class="fsfunc">lwres_gnbarequest_render</b>
42 <td>lwres_context_t * </td>
44 <var class="pdparam">ctx</var>, </td>
48 <td>lwres_gnbarequest_t * </td>
50 <var class="pdparam">req</var>, </td>
54 <td>lwres_lwpacket_t * </td>
56 <var class="pdparam">pkt</var>, </td>
60 <td>lwres_buffer_t * </td>
62 <var class="pdparam">b</var><code>)</code>;</td>
65 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
67 <td><code class="funcdef">
69 <b class="fsfunc">lwres_gnbaresponse_render</b>
91 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
93 <td><code class="funcdef">
95 <b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
116 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
118 <td><code class="funcdef">
120 <b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
141 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
143 <td><code class="funcdef">
145 <b class="fsfunc">lwres_gnbaresponse_free</b>
157 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
159 <td><code class="funcdef">
161 <b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
174 <div class="refsect1" lang="en">
175 <a name="id2525975"></a><h2>DESCRIPTION</h2>
177 These are low-level routines for creating and parsing
178 lightweight resolver address-to-name lookup request and
182 There are four main functions for the getnamebyaddr opcode.
183 One render function converts a getnamebyaddr request structure —
184 <span class="type">lwres_gnbarequest_t</span> —
185 to the lightweight resolver's canonical format.
186 It is complemented by a parse function that converts a packet in this
187 canonical format to a getnamebyaddr request structure.
188 Another render function converts the getnamebyaddr response structure —
189 <span class="type">lwres_gnbaresponse_t</span>
190 to the canonical format.
191 This is complemented by a parse function which converts a packet in
192 canonical format to a getnamebyaddr response structure.
195 These structures are defined in
196 <code class="filename">lwres/lwres.h</code>.
197 They are shown below.
199 <pre class="programlisting">
200 #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
203 lwres_uint32_t flags;
205 } lwres_gnbarequest_t;
208 lwres_uint32_t flags;
209 lwres_uint16_t naliases;
212 lwres_uint16_t realnamelen;
213 lwres_uint16_t *aliaslen;
216 } lwres_gnbaresponse_t;
221 <code class="function">lwres_gnbarequest_render()</code>
222 uses resolver context
223 <code class="varname">ctx</code>
224 to convert getnamebyaddr request structure
225 <code class="varname">req</code>
227 The packet header structure
228 <code class="varname">pkt</code>
229 is initialised and transferred to
231 <code class="varname">b</code>.
233 <code class="varname">*req</code>
234 are then appended to the buffer in canonical format.
235 <code class="function">lwres_gnbaresponse_render()</code>
236 performs the same task, except it converts a getnamebyaddr response structure
237 <span class="type">lwres_gnbaresponse_t</span>
238 to the lightweight resolver's canonical format.
241 <code class="function">lwres_gnbarequest_parse()</code>
243 <code class="varname">ctx</code>
244 to convert the contents of packet
245 <code class="varname">pkt</code>
247 <span class="type">lwres_gnbarequest_t</span>
250 <code class="varname">b</code>
251 provides space to be used for storing this structure.
252 When the function succeeds, the resulting
253 <span class="type">lwres_gnbarequest_t</span>
254 is made available through
255 <code class="varname">*structp</code>.
256 <code class="function">lwres_gnbaresponse_parse()</code>
257 offers the same semantics as
258 <code class="function">lwres_gnbarequest_parse()</code>
260 <span class="type">lwres_gnbaresponse_t</span>
264 <code class="function">lwres_gnbaresponse_free()</code>
266 <code class="function">lwres_gnbarequest_free()</code>
267 release the memory in resolver context
268 <code class="varname">ctx</code>
269 that was allocated to the
270 <span class="type">lwres_gnbaresponse_t</span>
272 <span class="type">lwres_gnbarequest_t</span>
273 structures referenced via
274 <code class="varname">structp</code>.
275 Any memory associated with ancillary buffers and strings for those
276 structures is also discarded.
279 <div class="refsect1" lang="en">
280 <a name="id2526100"></a><h2>RETURN VALUES</h2>
282 The getnamebyaddr opcode functions
283 <code class="function">lwres_gnbarequest_render()</code>,
284 <code class="function">lwres_gnbaresponse_render()</code>
285 <code class="function">lwres_gnbarequest_parse()</code>
287 <code class="function">lwres_gnbaresponse_parse()</code>
289 <span class="errorcode">LWRES_R_SUCCESS</span>
292 <span class="errorcode">LWRES_R_NOMEMORY</span>
293 if memory allocation fails.
294 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
295 is returned if the available space in the buffer
296 <code class="varname">b</code>
297 is too small to accommodate the packet header or the
298 <span class="type">lwres_gnbarequest_t</span>
300 <span class="type">lwres_gnbaresponse_t</span>
302 <code class="function">lwres_gnbarequest_parse()</code>
304 <code class="function">lwres_gnbaresponse_parse()</code>
306 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
307 if the buffer is not empty after decoding the received packet.
308 These functions will return
309 <span class="errorcode">LWRES_R_FAILURE</span>
311 <em class="structfield"><code>pktflags</code></em>
312 in the packet header structure
313 <span class="type">lwres_lwpacket_t</span>
314 indicate that the packet is not a response to an earlier query.
317 <div class="refsect1" lang="en">
318 <a name="id2526165"></a><h2>SEE ALSO</h2>
320 <span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.