PageRenderTime 21ms CodeModel.GetById 12ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/contrib/bind9/lib/lwres/man/lwres_gnba.html

https://bitbucket.org/freebsd/freebsd-head/
HTML | 316 lines | 299 code | 0 blank | 17 comment | 0 complexity | 6ddf738a975187f206a7cfcc918994f5 MD5 | raw file
  1<!--
  2 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  3 - Copyright (C) 2000, 2001 Internet Software Consortium.
  4 - 
  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.
  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<!-- $Id$ -->
 18<html>
 19<head>
 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">
 23</head>
 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">
 27<h2>Name</h2>
 28<p>lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free &#8212; lightweight resolver getnamebyaddress message handling</p>
 29</div>
 30<div class="refsynopsisdiv">
 31<h2>Synopsis</h2>
 32<div class="funcsynopsis">
 33<pre class="funcsynopsisinfo">
 34#include &lt;lwres/lwres.h&gt;
 35</pre>
 36<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 37<tr>
 38<td><code class="funcdef">
 39lwres_result_t
 40<b class="fsfunc">lwres_gnbarequest_render</b>
 41(</code></td>
 42<td>lwres_context_t * </td>
 43<td>
 44<var class="pdparam">ctx</var>, </td>
 45</tr>
 46<tr>
 47<td> </td>
 48<td>lwres_gnbarequest_t * </td>
 49<td>
 50<var class="pdparam">req</var>, </td>
 51</tr>
 52<tr>
 53<td> </td>
 54<td>lwres_lwpacket_t * </td>
 55<td>
 56<var class="pdparam">pkt</var>, </td>
 57</tr>
 58<tr>
 59<td> </td>
 60<td>lwres_buffer_t * </td>
 61<td>
 62<var class="pdparam">b</var><code>)</code>;</td>
 63</tr>
 64</table>
 65<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 66<tr>
 67<td><code class="funcdef">
 68lwres_result_t
 69<b class="fsfunc">lwres_gnbaresponse_render</b>
 70(</code></td>
 71<td>lwres_context_t * </td>
 72<td>
 73<var class="pdparam">ctx</var>, </td>
 74</tr>
 75<tr>
 76<td> </td>
 77<td>lwres_gnbaresponse_t * </td>
 78<td>
 79<var class="pdparam">req</var>, </td>
 80</tr>
 81<tr>
 82<td> </td>
 83<td>lwres_lwpacket_t * </td>
 84<td>
 85<var class="pdparam">pkt</var>, </td>
 86</tr>
 87<tr>
 88<td> </td>
 89<td>lwres_buffer_t * </td>
 90<td>
 91<var class="pdparam">b</var><code>)</code>;</td>
 92</tr>
 93</table>
 94<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 95<tr>
 96<td><code class="funcdef">
 97lwres_result_t
 98<b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td>
 99<td>lwres_context_t * </td>
100<td>
101<var class="pdparam">ctx</var>, </td>
102</tr>
103<tr>
104<td> </td>
105<td>lwres_buffer_t * </td>
106<td>
107<var class="pdparam">b</var>, </td>
108</tr>
109<tr>
110<td> </td>
111<td>lwres_lwpacket_t * </td>
112<td>
113<var class="pdparam">pkt</var>, </td>
114</tr>
115<tr>
116<td> </td>
117<td>lwres_gnbarequest_t ** </td>
118<td>
119<var class="pdparam">structp</var><code>)</code>;</td>
120</tr>
121</table>
122<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
123<tr>
124<td><code class="funcdef">
125lwres_result_t
126<b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td>
127<td>lwres_context_t * </td>
128<td>
129<var class="pdparam">ctx</var>, </td>
130</tr>
131<tr>
132<td> </td>
133<td>lwres_buffer_t * </td>
134<td>
135<var class="pdparam">b</var>, </td>
136</tr>
137<tr>
138<td> </td>
139<td>lwres_lwpacket_t * </td>
140<td>
141<var class="pdparam">pkt</var>, </td>
142</tr>
143<tr>
144<td> </td>
145<td>lwres_gnbaresponse_t ** </td>
146<td>
147<var class="pdparam">structp</var><code>)</code>;</td>
148</tr>
149</table>
150<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
151<tr>
152<td><code class="funcdef">
153void
154<b class="fsfunc">lwres_gnbaresponse_free</b>
155(</code></td>
156<td>lwres_context_t * </td>
157<td>
158<var class="pdparam">ctx</var>, </td>
159</tr>
160<tr>
161<td> </td>
162<td>lwres_gnbaresponse_t ** </td>
163<td>
164<var class="pdparam">structp</var><code>)</code>;</td>
165</tr>
166</table>
167<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
168<tr>
169<td><code class="funcdef">
170void
171<b class="fsfunc">lwres_gnbarequest_free</b>(</code></td>
172<td>lwres_context_t * </td>
173<td>
174<var class="pdparam">ctx</var>, </td>
175</tr>
176<tr>
177<td> </td>
178<td>lwres_gnbarequest_t ** </td>
179<td>
180<var class="pdparam">structp</var><code>)</code>;</td>
181</tr>
182</table>
183</div>
184</div>
185<div class="refsect1" lang="en">
186<a name="id2543529"></a><h2>DESCRIPTION</h2>
187<p>
188      These are low-level routines for creating and parsing
189      lightweight resolver address-to-name lookup request and
190      response messages.
191    </p>
192<p>
193      There are four main functions for the getnamebyaddr opcode.
194      One render function converts a getnamebyaddr request structure &#8212;
195      <span class="type">lwres_gnbarequest_t</span> &#8212;
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
200      &#8212;
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.
205    </p>
206<p>
207      These structures are defined in
208      <code class="filename">lwres/lwres.h</code>.
209      They are shown below.
210    </p>
211<pre class="programlisting">
212#define LWRES_OPCODE_GETNAMEBYADDR      0x00010002U
213</pre>
214<p>
215    </p>
216<pre class="programlisting">
217typedef struct {
218        lwres_uint32_t  flags;
219        lwres_addr_t    addr;
220} lwres_gnbarequest_t;
221</pre>
222<p>
223    </p>
224<pre class="programlisting">
225typedef struct {
226        lwres_uint32_t  flags;
227        lwres_uint16_t  naliases;
228        char           *realname;
229        char          **aliases;
230        lwres_uint16_t  realnamelen;
231        lwres_uint16_t *aliaslen;
232        void           *base;
233        size_t          baselen;
234} lwres_gnbaresponse_t;
235</pre>
236<p>
237    </p>
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
248      canonical format.
249    </p>
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.
261    </p>
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
269      discarded.
270    </p>
271</div>
272<div class="refsect1" lang="en">
273<a name="id2543669"></a><h2>RETURN VALUES</h2>
274<p>
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>
279      and
280      <code class="function">lwres_gnbaresponse_parse()</code>
281      all return
282      <span class="errorcode">LWRES_R_SUCCESS</span>
283      on success.
284      They return
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>
292      and
293      <span class="type">lwres_gnbaresponse_t</span>
294      structures.
295      <code class="function">lwres_gnbarequest_parse()</code>
296      and
297      <code class="function">lwres_gnbaresponse_parse()</code>
298      will return
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>
303      if
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.
308    </p>
309</div>
310<div class="refsect1" lang="en">
311<a name="id2543735"></a><h2>SEE ALSO</h2>
312<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>.
313    </p>
314</div>
315</div></body>
316</html>