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

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