1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3	       [<!ENTITY mdash "&#8212;">]>
4<!--
5 - Copyright (C) 2004, 2005, 2007, 2014  Internet Systems Consortium, Inc. ("ISC")
6 - Copyright (C) 2000, 2001  Internet Software Consortium.
7 -
8 - Permission to use, copy, modify, and/or distribute this software for any
9 - purpose with or without fee is hereby granted, provided that the above
10 - copyright notice and this permission notice appear in all copies.
11 -
12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14 - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
18 - PERFORMANCE OF THIS SOFTWARE.
19-->
20
21<refentry>
22
23  <refentryinfo>
24    <date>June 18, 2007</date>
25  </refentryinfo>
26
27  <refmeta>
28    <refentrytitle>lwres_gnba</refentrytitle>
29    <manvolnum>3</manvolnum>
30    <refmiscinfo>BIND9</refmiscinfo>
31  </refmeta>
32
33  <docinfo>
34    <copyright>
35      <year>2004</year>
36      <year>2005</year>
37      <year>2007</year>
38      <year>2014</year>
39      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
40    </copyright>
41    <copyright>
42      <year>2000</year>
43      <year>2001</year>
44      <holder>Internet Software Consortium.</holder>
45    </copyright>
46  </docinfo>
47
48  <refnamediv>
49    <refname>lwres_gnbarequest_render</refname>
50    <refname>lwres_gnbaresponse_render</refname>
51    <refname>lwres_gnbarequest_parse</refname>
52    <refname>lwres_gnbaresponse_parse</refname>
53    <refname>lwres_gnbaresponse_free</refname>
54    <refname>lwres_gnbarequest_free</refname>
55    <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
56  </refnamediv>
57
58  <refsynopsisdiv>
59
60    <funcsynopsis>
61<funcsynopsisinfo>
62#include &lt;lwres/lwres.h&gt;
63</funcsynopsisinfo>
64
65<funcprototype>
66        <funcdef>
67lwres_result_t
68<function>lwres_gnbarequest_render</function>
69</funcdef>
70        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
71        <paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
72        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
73        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
74        </funcprototype>
75
76<funcprototype>
77        <funcdef>
78lwres_result_t
79<function>lwres_gnbaresponse_render</function>
80</funcdef>
81        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
82        <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef>
83        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
84        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
85        </funcprototype>
86<funcprototype>
87        <funcdef>
88lwres_result_t
89<function>lwres_gnbarequest_parse</function></funcdef>
90        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
91        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
92        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
93        <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
94        </funcprototype>
95<funcprototype>
96        <funcdef>
97lwres_result_t
98<function>lwres_gnbaresponse_parse</function></funcdef>
99        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
100        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
101        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
102        <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
103        </funcprototype>
104
105<funcprototype>
106        <funcdef>
107void
108<function>lwres_gnbaresponse_free</function>
109</funcdef>
110        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
111        <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef>
112        </funcprototype>
113<funcprototype>
114        <funcdef>
115void
116<function>lwres_gnbarequest_free</function></funcdef>
117        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
118        <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef>
119      </funcprototype>
120</funcsynopsis>
121
122  </refsynopsisdiv>
123
124  <refsect1>
125    <title>DESCRIPTION</title>
126    <para>
127      These are low-level routines for creating and parsing
128      lightweight resolver address-to-name lookup request and
129      response messages.
130    </para>
131    <para>
132      There are four main functions for the getnamebyaddr opcode.
133      One render function converts a getnamebyaddr request structure &mdash;
134      <type>lwres_gnbarequest_t</type> &mdash;
135      to the lightweight resolver's canonical format.
136      It is complemented by a parse function that converts a packet in this
137      canonical format to a getnamebyaddr request structure.
138      Another render function converts the getnamebyaddr response structure
139      &mdash;
140      <type>lwres_gnbaresponse_t</type>
141      to the canonical format.
142      This is complemented by a parse function which converts a packet in
143      canonical format to a getnamebyaddr response structure.
144    </para>
145    <para>
146      These structures are defined in
147      <filename>lwres/lwres.h</filename>.
148      They are shown below.
149    </para>
150    <para><programlisting>
151#define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
152</programlisting>
153    </para>
154    <para><programlisting>
155typedef struct {
156        lwres_uint32_t  flags;
157        lwres_addr_t    addr;
158} lwres_gnbarequest_t;
159</programlisting>
160    </para>
161    <para><programlisting>
162typedef struct {
163        lwres_uint32_t  flags;
164        lwres_uint16_t  naliases;
165        char           *realname;
166        char          **aliases;
167        lwres_uint16_t  realnamelen;
168        lwres_uint16_t *aliaslen;
169        void           *base;
170        size_t          baselen;
171} lwres_gnbaresponse_t;
172</programlisting>
173    </para>
174
175    <para><function>lwres_gnbarequest_render()</function>
176      uses resolver context <varname>ctx</varname> to convert
177      getnamebyaddr request structure <varname>req</varname> to
178      canonical format.  The packet header structure
179      <varname>pkt</varname> is initialised and transferred to buffer
180      <varname>b</varname>.  The contents of <varname>*req</varname>
181      are then appended to the buffer in canonical format.
182      <function>lwres_gnbaresponse_render()</function> performs the
183      same task, except it converts a getnamebyaddr response structure
184      <type>lwres_gnbaresponse_t</type> to the lightweight resolver's
185      canonical format.
186    </para>
187
188    <para><function>lwres_gnbarequest_parse()</function>
189      uses context <varname>ctx</varname> to convert the contents of
190      packet <varname>pkt</varname> to a
191      <type>lwres_gnbarequest_t</type> structure.  Buffer
192      <varname>b</varname> provides space to be used for storing this
193      structure.  When the function succeeds, the resulting
194      <type>lwres_gnbarequest_t</type> is made available through
195      <varname>*structp</varname>.
196      <function>lwres_gnbaresponse_parse()</function> offers the same
197      semantics as <function>lwres_gnbarequest_parse()</function>
198      except it yields a <type>lwres_gnbaresponse_t</type> structure.
199    </para>
200
201    <para><function>lwres_gnbaresponse_free()</function>
202      and <function>lwres_gnbarequest_free()</function> release the
203      memory in resolver context <varname>ctx</varname> that was
204      allocated to the <type>lwres_gnbaresponse_t</type> or
205      <type>lwres_gnbarequest_t</type> structures referenced via
206      <varname>structp</varname>.  Any memory associated with
207      ancillary buffers and strings for those structures is also
208      discarded.
209    </para>
210  </refsect1>
211
212  <refsect1>
213    <title>RETURN VALUES</title>
214    <para>
215      The getnamebyaddr opcode functions
216      <function>lwres_gnbarequest_render()</function>,
217      <function>lwres_gnbaresponse_render()</function>
218      <function>lwres_gnbarequest_parse()</function>
219      and
220      <function>lwres_gnbaresponse_parse()</function>
221      all return
222      <errorcode>LWRES_R_SUCCESS</errorcode>
223      on success.
224      They return
225      <errorcode>LWRES_R_NOMEMORY</errorcode>
226      if memory allocation fails.
227      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
228      is returned if the available space in the buffer
229      <varname>b</varname>
230      is too small to accommodate the packet header or the
231      <type>lwres_gnbarequest_t</type>
232      and
233      <type>lwres_gnbaresponse_t</type>
234      structures.
235      <function>lwres_gnbarequest_parse()</function>
236      and
237      <function>lwres_gnbaresponse_parse()</function>
238      will return
239      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
240      if the buffer is not empty after decoding the received packet.
241      These functions will return
242      <errorcode>LWRES_R_FAILURE</errorcode>
243      if
244      <structfield>pktflags</structfield>
245      in the packet header structure
246      <type>lwres_lwpacket_t</type>
247      indicate that the packet is not a response to an earlier query.
248    </para>
249  </refsect1>
250  <refsect1>
251    <title>SEE ALSO</title>
252    <para><citerefentry>
253        <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
254      </citerefentry>.
255    </para>
256  </refsect1>
257</refentry><!--
258 - Local variables:
259 - mode: sgml
260 - End:
261-->
262