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

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