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

   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>
  64 lwres_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>
  73 lwres_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>
  82 lwres_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>
  91 lwres_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>
 100 void
 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>
 107 void
 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>
 151 typedef struct {
 152         lwres_uint16_t  datalength;
 153         unsigned char   *data;
 154 } lwres_nooprequest_t;
 155 </programlisting>
 156     </para>
 157     <para><programlisting>
 158 typedef 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 -->