PageRenderTime 32ms CodeModel.GetById 11ms app.highlight 14ms RepoModel.GetById 2ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
HTML | 324 lines | 304 code | 3 blank | 17 comment | 0 complexity | 6a51675abdb0c0fde5c7b5dd65a44877 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_gabn</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_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free &#8212; lightweight resolver getaddrbyname message handling</p>
 29</div>
 30<div class="refsynopsisdiv">
 31<h2>Synopsis</h2>
 32<div class="funcsynopsis">
 33<pre class="funcsynopsisinfo">#include &lt;lwres/lwres.h&gt;</pre>
 34<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 35<tr>
 36<td><code class="funcdef">
 37lwres_result_t
 38<b class="fsfunc">lwres_gabnrequest_render</b>(</code></td>
 39<td>lwres_context_t * </td>
 40<td>
 41<var class="pdparam">ctx</var>, </td>
 42</tr>
 43<tr>
 44<td> </td>
 45<td>lwres_gabnrequest_t * </td>
 46<td>
 47<var class="pdparam">req</var>, </td>
 48</tr>
 49<tr>
 50<td> </td>
 51<td>lwres_lwpacket_t * </td>
 52<td>
 53<var class="pdparam">pkt</var>, </td>
 54</tr>
 55<tr>
 56<td> </td>
 57<td>lwres_buffer_t * </td>
 58<td>
 59<var class="pdparam">b</var><code>)</code>;</td>
 60</tr>
 61</table>
 62<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 63<tr>
 64<td><code class="funcdef">
 65lwres_result_t
 66<b class="fsfunc">lwres_gabnresponse_render</b>(</code></td>
 67<td>lwres_context_t * </td>
 68<td>
 69<var class="pdparam">ctx</var>, </td>
 70</tr>
 71<tr>
 72<td> </td>
 73<td>lwres_gabnresponse_t * </td>
 74<td>
 75<var class="pdparam">req</var>, </td>
 76</tr>
 77<tr>
 78<td> </td>
 79<td>lwres_lwpacket_t * </td>
 80<td>
 81<var class="pdparam">pkt</var>, </td>
 82</tr>
 83<tr>
 84<td> </td>
 85<td>lwres_buffer_t * </td>
 86<td>
 87<var class="pdparam">b</var><code>)</code>;</td>
 88</tr>
 89</table>
 90<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
 91<tr>
 92<td><code class="funcdef">
 93lwres_result_t
 94<b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td>
 95<td>lwres_context_t * </td>
 96<td>
 97<var class="pdparam">ctx</var>, </td>
 98</tr>
 99<tr>
100<td> </td>
101<td>lwres_buffer_t * </td>
102<td>
103<var class="pdparam">b</var>, </td>
104</tr>
105<tr>
106<td> </td>
107<td>lwres_lwpacket_t * </td>
108<td>
109<var class="pdparam">pkt</var>, </td>
110</tr>
111<tr>
112<td> </td>
113<td>lwres_gabnrequest_t ** </td>
114<td>
115<var class="pdparam">structp</var><code>)</code>;</td>
116</tr>
117</table>
118<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
119<tr>
120<td><code class="funcdef">
121lwres_result_t
122<b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td>
123<td>lwres_context_t * </td>
124<td>
125<var class="pdparam">ctx</var>, </td>
126</tr>
127<tr>
128<td> </td>
129<td>lwres_buffer_t * </td>
130<td>
131<var class="pdparam">b</var>, </td>
132</tr>
133<tr>
134<td> </td>
135<td>lwres_lwpacket_t * </td>
136<td>
137<var class="pdparam">pkt</var>, </td>
138</tr>
139<tr>
140<td> </td>
141<td>lwres_gabnresponse_t ** </td>
142<td>
143<var class="pdparam">structp</var><code>)</code>;</td>
144</tr>
145</table>
146<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
147<tr>
148<td><code class="funcdef">
149void
150<b class="fsfunc">lwres_gabnresponse_free</b>(</code></td>
151<td>lwres_context_t * </td>
152<td>
153<var class="pdparam">ctx</var>, </td>
154</tr>
155<tr>
156<td> </td>
157<td>lwres_gabnresponse_t ** </td>
158<td>
159<var class="pdparam">structp</var><code>)</code>;</td>
160</tr>
161</table>
162<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
163<tr>
164<td><code class="funcdef">
165void
166<b class="fsfunc">lwres_gabnrequest_free</b>(</code></td>
167<td>lwres_context_t * </td>
168<td>
169<var class="pdparam">ctx</var>, </td>
170</tr>
171<tr>
172<td> </td>
173<td>lwres_gabnrequest_t ** </td>
174<td>
175<var class="pdparam">structp</var><code>)</code>;</td>
176</tr>
177</table>
178</div>
179</div>
180<div class="refsect1" lang="en">
181<a name="id2543526"></a><h2>DESCRIPTION</h2>
182<p>
183      These are low-level routines for creating and parsing
184      lightweight resolver name-to-address lookup request and
185      response messages.
186    </p>
187<p>
188      There are four main functions for the getaddrbyname opcode.
189      One render function converts a getaddrbyname request structure &#8212;
190      <span class="type">lwres_gabnrequest_t</span> &#8212;
191      to the lighweight resolver's canonical format.
192      It is complemented by a parse function that converts a packet in this
193      canonical format to a getaddrbyname request structure.
194      Another render function converts the getaddrbyname response structure
195      &#8212; <span class="type">lwres_gabnresponse_t</span> &#8212;
196      to the canonical format.
197      This is complemented by a parse function which converts a packet in
198      canonical format to a getaddrbyname response structure.
199    </p>
200<p>
201      These structures are defined in
202      <code class="filename">&lt;lwres/lwres.h&gt;</code>.
203      They are shown below.
204    </p>
205<pre class="programlisting">
206#define LWRES_OPCODE_GETADDRSBYNAME     0x00010001U
207</pre>
208<p>
209    </p>
210<pre class="programlisting">
211typedef struct lwres_addr lwres_addr_t;
212typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
213</pre>
214<p>
215    </p>
216<pre class="programlisting">
217typedef struct {
218        lwres_uint32_t  flags;
219        lwres_uint32_t  addrtypes;
220        lwres_uint16_t  namelen;
221        char           *name;
222} lwres_gabnrequest_t;
223</pre>
224<p>
225    </p>
226<pre class="programlisting">
227typedef struct {
228        lwres_uint32_t          flags;
229        lwres_uint16_t          naliases;
230        lwres_uint16_t          naddrs;
231        char                   *realname;
232        char                  **aliases;
233        lwres_uint16_t          realnamelen;
234        lwres_uint16_t         *aliaslen;
235        lwres_addrlist_t        addrs;
236        void                   *base;
237        size_t                  baselen;
238} lwres_gabnresponse_t;
239</pre>
240<p>
241    </p>
242<p><code class="function">lwres_gabnrequest_render()</code>
243      uses resolver context <em class="parameter"><code>ctx</code></em> to convert
244      getaddrbyname request structure <em class="parameter"><code>req</code></em> to
245      canonical format.  The packet header structure
246      <em class="parameter"><code>pkt</code></em> is initialised and transferred to
247      buffer <em class="parameter"><code>b</code></em>.
248
249      The contents of <em class="parameter"><code>*req</code></em> are then appended to
250      the buffer in canonical format.
251      <code class="function">lwres_gabnresponse_render()</code> performs the
252      same task, except it converts a getaddrbyname response structure
253      <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's
254      canonical format.
255    </p>
256<p><code class="function">lwres_gabnrequest_parse()</code>
257      uses context <em class="parameter"><code>ctx</code></em> to convert the contents
258      of packet <em class="parameter"><code>pkt</code></em> to a
259      <span class="type">lwres_gabnrequest_t</span> structure.  Buffer
260      <em class="parameter"><code>b</code></em> provides space to be used for storing
261      this structure.  When the function succeeds, the resulting
262      <span class="type">lwres_gabnrequest_t</span> is made available through
263      <em class="parameter"><code>*structp</code></em>.
264
265      <code class="function">lwres_gabnresponse_parse()</code> offers the same
266      semantics as <code class="function">lwres_gabnrequest_parse()</code>
267      except it yields a <span class="type">lwres_gabnresponse_t</span> structure.
268    </p>
269<p><code class="function">lwres_gabnresponse_free()</code>
270      and <code class="function">lwres_gabnrequest_free()</code> release the
271      memory in resolver context <em class="parameter"><code>ctx</code></em> that was
272      allocated to the <span class="type">lwres_gabnresponse_t</span> or
273      <span class="type">lwres_gabnrequest_t</span> structures referenced via
274      <em class="parameter"><code>structp</code></em>.
275
276      Any memory associated with ancillary buffers and strings for
277      those structures is also discarded.
278    </p>
279</div>
280<div class="refsect1" lang="en">
281<a name="id2543671"></a><h2>RETURN VALUES</h2>
282<p>
283      The getaddrbyname opcode functions
284      <code class="function">lwres_gabnrequest_render()</code>,
285      <code class="function">lwres_gabnresponse_render()</code>
286      <code class="function">lwres_gabnrequest_parse()</code>
287      and
288      <code class="function">lwres_gabnresponse_parse()</code>
289      all return
290      <span class="errorcode">LWRES_R_SUCCESS</span>
291      on success.
292      They return
293      <span class="errorcode">LWRES_R_NOMEMORY</span>
294      if memory allocation fails.
295      <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
296      is returned if the available space in the buffer
297      <em class="parameter"><code>b</code></em>
298      is too small to accommodate the packet header or the
299      <span class="type">lwres_gabnrequest_t</span>
300      and
301      <span class="type">lwres_gabnresponse_t</span>
302      structures.
303      <code class="function">lwres_gabnrequest_parse()</code>
304      and
305      <code class="function">lwres_gabnresponse_parse()</code>
306      will return
307      <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
308      if the buffer is not empty after decoding the received packet.
309      These functions will return
310      <span class="errorcode">LWRES_R_FAILURE</span>
311      if
312      <em class="structfield"><code>pktflags</code></em>
313      in the packet header structure
314      <span class="type">lwres_lwpacket_t</span>
315      indicate that the packet is not a response to an earlier query.
316    </p>
317</div>
318<div class="refsect1" lang="en">
319<a name="id2543737"></a><h2>SEE ALSO</h2>
320<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>
321    </p>
322</div>
323</div></body>
324</html>