PageRenderTime 33ms CodeModel.GetById 24ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

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

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 256 lines | 245 code | 11 blank | 0 comment | 0 complexity | f3b0160ae348886e8a70e13c2d322432 MD5 | raw file
  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, 2012  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<!-- $Id$ -->
 22<refentry>
 23
 24  <refentryinfo>
 25    <date>Jun 30, 2000</date>
 26  </refentryinfo>
 27
 28  <refmeta>
 29    <refentrytitle>lwres_noop</refentrytitle>
 30    <manvolnum>3</manvolnum>
 31    <refmiscinfo>BIND9</refmiscinfo>
 32  </refmeta>
 33
 34  <docinfo>
 35    <copyright>
 36      <year>2004</year>
 37      <year>2005</year>
 38      <year>2007</year>
 39      <year>2012</year>
 40      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
 41    </copyright>
 42    <copyright>
 43      <year>2000</year>
 44      <year>2001</year>
 45      <holder>Internet Software Consortium.</holder>
 46    </copyright>
 47  </docinfo>
 48
 49  <refnamediv>
 50    <refname>lwres_nooprequest_render</refname>
 51    <refname>lwres_noopresponse_render</refname>
 52    <refname>lwres_nooprequest_parse</refname>
 53    <refname>lwres_noopresponse_parse</refname>
 54    <refname>lwres_noopresponse_free</refname>
 55    <refname>lwres_nooprequest_free</refname>
 56    <refpurpose>lightweight resolver no-op message handling</refpurpose>
 57  </refnamediv>
 58  <refsynopsisdiv>
 59    <funcsynopsis>
 60<funcsynopsisinfo>
 61#include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
 62<funcprototype>
 63        <funcdef>
 64lwres_result_t
 65<function>lwres_nooprequest_render</function></funcdef>
 66        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 67        <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
 68        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 69        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 70        </funcprototype>
 71<funcprototype>
 72        <funcdef>
 73lwres_result_t
 74<function>lwres_noopresponse_render</function></funcdef>
 75        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 76        <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
 77        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 78        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 79        </funcprototype>
 80<funcprototype>
 81        <funcdef>
 82lwres_result_t
 83<function>lwres_nooprequest_parse</function></funcdef>
 84        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 85        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 86        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 87        <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
 88        </funcprototype>
 89<funcprototype>
 90        <funcdef>
 91lwres_result_t
 92<function>lwres_noopresponse_parse</function></funcdef>
 93        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
 94        <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
 95        <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
 96        <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
 97        </funcprototype>
 98<funcprototype>
 99        <funcdef>
100void
101<function>lwres_noopresponse_free</function></funcdef>
102        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
103        <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
104        </funcprototype>
105<funcprototype>
106        <funcdef>
107void
108<function>lwres_nooprequest_free</function></funcdef>
109        <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
110        <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
111      </funcprototype>
112</funcsynopsis>
113  </refsynopsisdiv>
114  <refsect1>
115    <title>DESCRIPTION</title>
116    <para>
117      These are low-level routines for creating and parsing
118      lightweight resolver no-op request and response messages.
119    </para>
120    <para>
121      The no-op message is analogous to a <command>ping</command>
122      packet:
123      a packet is sent to the resolver daemon and is simply echoed back.
124      The opcode is intended to allow a client to determine if the server is
125      operational or not.
126    </para>
127    <para>
128      There are four main functions for the no-op opcode.
129      One render function converts a no-op request structure &mdash;
130      <type>lwres_nooprequest_t</type> &mdash;
131      to the lighweight resolver's canonical format.
132      It is complemented by a parse function that converts a packet in this
133      canonical format to a no-op request structure.
134      Another render function converts the no-op response structure &mdash;
135      <type>lwres_noopresponse_t</type>
136      to the canonical format.
137      This is complemented by a parse function which converts a packet in
138      canonical format to a no-op response structure.
139    </para>
140    <para>
141      These structures are defined in
142      <filename>lwres/lwres.h</filename>.
143
144      They are shown below.
145    </para>
146    <para><programlisting>
147#define LWRES_OPCODE_NOOP       0x00000000U
148</programlisting>
149    </para>
150    <para><programlisting>
151typedef struct {
152        lwres_uint16_t  datalength;
153        unsigned char   *data;
154} lwres_nooprequest_t;
155</programlisting>
156    </para>
157    <para><programlisting>
158typedef struct {
159        lwres_uint16_t  datalength;
160        unsigned char   *data;
161} lwres_noopresponse_t;
162</programlisting>
163    </para>
164    <para>
165      Although the structures have different types, they are identical.
166      This is because the no-op opcode simply echos whatever data was sent:
167      the response is therefore identical to the request.
168    </para>
169
170    <para><function>lwres_nooprequest_render()</function>
171      uses resolver context <parameter>ctx</parameter> to convert
172      no-op request structure <parameter>req</parameter> to canonical
173      format.  The packet header structure <parameter>pkt</parameter>
174      is initialised and transferred to buffer
175      <parameter>b</parameter>.  The contents of
176      <parameter>*req</parameter> are then appended to the buffer in
177      canonical format.
178      <function>lwres_noopresponse_render()</function> performs the
179      same task, except it converts a no-op response structure
180      <type>lwres_noopresponse_t</type> to the lightweight resolver's
181      canonical format.
182    </para>
183
184    <para><function>lwres_nooprequest_parse()</function>
185      uses context <parameter>ctx</parameter> to convert the contents
186      of packet <parameter>pkt</parameter> to a
187      <type>lwres_nooprequest_t</type> structure.  Buffer
188      <parameter>b</parameter> provides space to be used for storing
189      this structure.  When the function succeeds, the resulting
190      <type>lwres_nooprequest_t</type> is made available through
191      <parameter>*structp</parameter>.
192      <function>lwres_noopresponse_parse()</function> offers the same
193      semantics as <function>lwres_nooprequest_parse()</function>
194      except it yields a <type>lwres_noopresponse_t</type> structure.
195    </para>
196
197    <para><function>lwres_noopresponse_free()</function>
198      and <function>lwres_nooprequest_free()</function> release the
199      memory in resolver context <parameter>ctx</parameter> that was
200      allocated to the <type>lwres_noopresponse_t</type> or
201      <type>lwres_nooprequest_t</type> structures referenced via
202      <parameter>structp</parameter>.
203    </para>
204
205  </refsect1>
206  <refsect1>
207    <title>RETURN VALUES</title>
208    <para>
209      The no-op opcode functions
210      <function>lwres_nooprequest_render()</function>,
211
212      <function>lwres_noopresponse_render()</function>
213      <function>lwres_nooprequest_parse()</function>
214      and
215      <function>lwres_noopresponse_parse()</function>
216      all return
217      <errorcode>LWRES_R_SUCCESS</errorcode>
218      on success.
219      They return
220      <errorcode>LWRES_R_NOMEMORY</errorcode>
221      if memory allocation fails.
222      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
223      is returned if the available space in the buffer
224      <parameter>b</parameter>
225      is too small to accommodate the packet header or the
226      <type>lwres_nooprequest_t</type>
227      and
228      <type>lwres_noopresponse_t</type>
229      structures.
230      <function>lwres_nooprequest_parse()</function>
231      and
232      <function>lwres_noopresponse_parse()</function>
233      will return
234      <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
235      if the buffer is not empty after decoding the received packet.
236      These functions will return
237      <errorcode>LWRES_R_FAILURE</errorcode>
238      if
239      <constant>pktflags</constant>
240      in the packet header structure
241      <type>lwres_lwpacket_t</type>
242      indicate that the packet is not a response to an earlier query.
243    </para>
244  </refsect1>
245  <refsect1>
246    <title>SEE ALSO</title>
247    <para><citerefentry>
248        <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
249      </citerefentry>
250    </para>
251  </refsect1>
252</refentry><!--
253 - Local variables:
254 - mode: sgml
255 - End:
256-->