PageRenderTime 43ms CodeModel.GetById 27ms app.highlight 11ms RepoModel.GetById 1ms app.codeStats 1ms

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

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