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/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.
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.71.1">
24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
25 <a name="id2476274"></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>
71 <td>lwres_context_t * </td>
73 <var class="pdparam">ctx</var>, </td>
77 <td>lwres_gnbaresponse_t * </td>
79 <var class="pdparam">req</var>, </td>
83 <td>lwres_lwpacket_t * </td>
85 <var class="pdparam">pkt</var>, </td>
89 <td>lwres_buffer_t * </td>
91 <var class="pdparam">b</var><code>)</code>;</td>
94 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
96 <td><code class="funcdef">
98 <b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
99 <td>lwres_context_t * </td>
101 <var class="pdparam">ctx</var>, </td>
105 <td>lwres_buffer_t * </td>
107 <var class="pdparam">b</var>, </td>
111 <td>lwres_lwpacket_t * </td>
113 <var class="pdparam">pkt</var>, </td>
117 <td>lwres_gnbarequest_t ** </td>
119 <var class="pdparam">structp</var><code>)</code>;</td>
122 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
124 <td><code class="funcdef">
126 <b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
127 <td>lwres_context_t * </td>
129 <var class="pdparam">ctx</var>, </td>
133 <td>lwres_buffer_t * </td>
135 <var class="pdparam">b</var>, </td>
139 <td>lwres_lwpacket_t * </td>
141 <var class="pdparam">pkt</var>, </td>
145 <td>lwres_gnbaresponse_t ** </td>
147 <var class="pdparam">structp</var><code>)</code>;</td>
150 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
152 <td><code class="funcdef">
154 <b class="fsfunc">lwres_gnbaresponse_free</b>
156 <td>lwres_context_t * </td>
158 <var class="pdparam">ctx</var>, </td>
162 <td>lwres_gnbaresponse_t ** </td>
164 <var class="pdparam">structp</var><code>)</code>;</td>
167 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
169 <td><code class="funcdef">
171 <b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
172 <td>lwres_context_t * </td>
174 <var class="pdparam">ctx</var>, </td>
178 <td>lwres_gnbarequest_t ** </td>
180 <var class="pdparam">structp</var><code>)</code>;</td>
185 <div class="refsect1" lang="en">
186 <a name="id2543527"></a><h2>DESCRIPTION</h2>
188 These are low-level routines for creating and parsing
189 lightweight resolver address-to-name lookup request and
193 There are four main functions for the getnamebyaddr opcode.
194 One render function converts a getnamebyaddr request structure —
195 <span class="type">lwres_gnbarequest_t</span> —
196 to the lightweight resolver's canonical format.
197 It is complemented by a parse function that converts a packet in this
198 canonical format to a getnamebyaddr request structure.
199 Another render function converts the getnamebyaddr response structure
201 <span class="type">lwres_gnbaresponse_t</span>
202 to the canonical format.
203 This is complemented by a parse function which converts a packet in
204 canonical format to a getnamebyaddr response structure.
207 These structures are defined in
208 <code class="filename">lwres/lwres.h</code>.
209 They are shown below.
211 <pre class="programlisting">
212 #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
216 <pre class="programlisting">
218 lwres_uint32_t flags;
220 } lwres_gnbarequest_t;
224 <pre class="programlisting">
226 lwres_uint32_t flags;
227 lwres_uint16_t naliases;
230 lwres_uint16_t realnamelen;
231 lwres_uint16_t *aliaslen;
234 } lwres_gnbaresponse_t;
238 <p><code class="function">lwres_gnbarequest_render()</code>
239 uses resolver context <code class="varname">ctx</code> to convert
240 getnamebyaddr request structure <code class="varname">req</code> to
241 canonical format. The packet header structure
242 <code class="varname">pkt</code> is initialised and transferred to buffer
243 <code class="varname">b</code>. The contents of <code class="varname">*req</code>
244 are then appended to the buffer in canonical format.
245 <code class="function">lwres_gnbaresponse_render()</code> performs the
246 same task, except it converts a getnamebyaddr response structure
247 <span class="type">lwres_gnbaresponse_t</span> to the lightweight resolver's
250 <p><code class="function">lwres_gnbarequest_parse()</code>
251 uses context <code class="varname">ctx</code> to convert the contents of
252 packet <code class="varname">pkt</code> to a
253 <span class="type">lwres_gnbarequest_t</span> structure. Buffer
254 <code class="varname">b</code> provides space to be used for storing this
255 structure. When the function succeeds, the resulting
256 <span class="type">lwres_gnbarequest_t</span> is made available through
257 <code class="varname">*structp</code>.
258 <code class="function">lwres_gnbaresponse_parse()</code> offers the same
259 semantics as <code class="function">lwres_gnbarequest_parse()</code>
260 except it yields a <span class="type">lwres_gnbaresponse_t</span> structure.
262 <p><code class="function">lwres_gnbaresponse_free()</code>
263 and <code class="function">lwres_gnbarequest_free()</code> release the
264 memory in resolver context <code class="varname">ctx</code> that was
265 allocated to the <span class="type">lwres_gnbaresponse_t</span> or
266 <span class="type">lwres_gnbarequest_t</span> structures referenced via
267 <code class="varname">structp</code>. Any memory associated with
268 ancillary buffers and strings for those structures is also
272 <div class="refsect1" lang="en">
273 <a name="id2543667"></a><h2>RETURN VALUES</h2>
275 The getnamebyaddr opcode functions
276 <code class="function">lwres_gnbarequest_render()</code>,
277 <code class="function">lwres_gnbaresponse_render()</code>
278 <code class="function">lwres_gnbarequest_parse()</code>
280 <code class="function">lwres_gnbaresponse_parse()</code>
282 <span class="errorcode">LWRES_R_SUCCESS</span>
285 <span class="errorcode">LWRES_R_NOMEMORY</span>
286 if memory allocation fails.
287 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
288 is returned if the available space in the buffer
289 <code class="varname">b</code>
290 is too small to accommodate the packet header or the
291 <span class="type">lwres_gnbarequest_t</span>
293 <span class="type">lwres_gnbaresponse_t</span>
295 <code class="function">lwres_gnbarequest_parse()</code>
297 <code class="function">lwres_gnbaresponse_parse()</code>
299 <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
300 if the buffer is not empty after decoding the received packet.
301 These functions will return
302 <span class="errorcode">LWRES_R_FAILURE</span>
304 <em class="structfield"><code>pktflags</code></em>
305 in the packet header structure
306 <span class="type">lwres_lwpacket_t</span>
307 indicate that the packet is not a response to an earlier query.
310 <div class="refsect1" lang="en">
311 <a name="id2543733"></a><h2>SEE ALSO</h2>
312 <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.