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

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007, 2014, 2015 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 <html>
  18 <head>
  19 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  20 <title>lwres_noop</title>
  21 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
  22 </head>
  23 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
  24 <a name="id-1"></a><div class="titlepage"></div>
  25 <div class="refnamediv">
  26 <h2>Name</h2>
  27 <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>
  28 </div>
  29 <div class="refsynopsisdiv">
  30 <h2>Synopsis</h2>
  31 <div class="funcsynopsis">
  32 <pre class="funcsynopsisinfo">
  33 #include &lt;lwres/lwres.h&gt;</pre>
  34 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  35 <tr>
  36 <td><code class="funcdef">
  37 lwres_result_t
  38 <b class="fsfunc">lwres_nooprequest_render</b>(</code></td>
  39 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  40 </tr>
  41 <tr>
  42 <td> </td>
  43 <td>lwres_nooprequest_t *<var class="pdparam">req</var>, </td>
  44 </tr>
  45 <tr>
  46 <td> </td>
  47 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  48 </tr>
  49 <tr>
  50 <td> </td>
  51 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  52 </tr>
  53 </table>
  54 <div class="funcprototype-spacer"> </div>
  55 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  56 <tr>
  57 <td><code class="funcdef">
  58 lwres_result_t
  59 <b class="fsfunc">lwres_noopresponse_render</b>(</code></td>
  60 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  61 </tr>
  62 <tr>
  63 <td> </td>
  64 <td>lwres_noopresponse_t *<var class="pdparam">req</var>, </td>
  65 </tr>
  66 <tr>
  67 <td> </td>
  68 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  69 </tr>
  70 <tr>
  71 <td> </td>
  72 <td>lwres_buffer_t *<var class="pdparam">b</var><code>)</code>;</td>
  73 </tr>
  74 </table>
  75 <div class="funcprototype-spacer"> </div>
  76 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  77 <tr>
  78 <td><code class="funcdef">
  79 lwres_result_t
  80 <b class="fsfunc">lwres_nooprequest_parse</b>(</code></td>
  81 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
  82 </tr>
  83 <tr>
  84 <td> </td>
  85 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
  86 </tr>
  87 <tr>
  88 <td> </td>
  89 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
  90 </tr>
  91 <tr>
  92 <td> </td>
  93 <td>lwres_nooprequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
  94 </tr>
  95 </table>
  96 <div class="funcprototype-spacer"> </div>
  97 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
  98 <tr>
  99 <td><code class="funcdef">
 100 lwres_result_t
 101 <b class="fsfunc">lwres_noopresponse_parse</b>(</code></td>
 102 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 103 </tr>
 104 <tr>
 105 <td> </td>
 106 <td>lwres_buffer_t *<var class="pdparam">b</var>, </td>
 107 </tr>
 108 <tr>
 109 <td> </td>
 110 <td>lwres_lwpacket_t *<var class="pdparam">pkt</var>, </td>
 111 </tr>
 112 <tr>
 113 <td> </td>
 114 <td>lwres_noopresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
 115 </tr>
 116 </table>
 117 <div class="funcprototype-spacer"> </div>
 118 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 119 <tr>
 120 <td><code class="funcdef">
 121 void
 122 <b class="fsfunc">lwres_noopresponse_free</b>(</code></td>
 123 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 124 </tr>
 125 <tr>
 126 <td> </td>
 127 <td>lwres_noopresponse_t **<var class="pdparam">structp</var><code>)</code>;</td>
 128 </tr>
 129 </table>
 130 <div class="funcprototype-spacer"> </div>
 131 <table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;">
 132 <tr>
 133 <td><code class="funcdef">
 134 void
 135 <b class="fsfunc">lwres_nooprequest_free</b>(</code></td>
 136 <td>lwres_context_t *<var class="pdparam">ctx</var>, </td>
 137 </tr>
 138 <tr>
 139 <td> </td>
 140 <td>lwres_nooprequest_t **<var class="pdparam">structp</var><code>)</code>;</td>
 141 </tr>
 142 </table>
 143 <div class="funcprototype-spacer"> </div>
 144 </div>
 145 </div>
 146 <div class="refsection">
 147 <a name="id-1.7"></a><h2>DESCRIPTION</h2>
 148 <p>
 149       These are low-level routines for creating and parsing
 150       lightweight resolver no-op request and response messages.
 151     </p>
 152 <p>
 153       The no-op message is analogous to a <span class="command"><strong>ping</strong></span>
 154       packet:
 155       a packet is sent to the resolver daemon and is simply echoed back.
 156       The opcode is intended to allow a client to determine if the server is
 157       operational or not.
 158     </p>
 159 <p>
 160       There are four main functions for the no-op opcode.
 161       One render function converts a no-op request structure &#8212;
 162       <span class="type">lwres_nooprequest_t</span> &#8212;
 163       to the lightweight resolver's canonical format.
 164       It is complemented by a parse function that converts a packet in this
 165       canonical format to a no-op request structure.
 166       Another render function converts the no-op response structure &#8212;
 167       <span class="type">lwres_noopresponse_t</span>
 168       to the canonical format.
 169       This is complemented by a parse function which converts a packet in
 170       canonical format to a no-op response structure.
 171     </p>
 172 <p>
 173       These structures are defined in
 174       <code class="filename">lwres/lwres.h</code>.
 175
 176       They are shown below.
 177     </p>
 178 <pre class="programlisting">
 179 #define LWRES_OPCODE_NOOP       0x00000000U
 180 </pre>
 181 <p>
 182     </p>
 183 <pre class="programlisting">
 184 typedef struct {
 185         lwres_uint16_t  datalength;
 186         unsigned char   *data;
 187 } lwres_nooprequest_t;
 188 </pre>
 189 <p>
 190     </p>
 191 <pre class="programlisting">
 192 typedef struct {
 193         lwres_uint16_t  datalength;
 194         unsigned char   *data;
 195 } lwres_noopresponse_t;
 196 </pre>
 197 <p>
 198     </p>
 199 <p>
 200       Although the structures have different types, they are identical.
 201       This is because the no-op opcode simply echos whatever data was sent:
 202       the response is therefore identical to the request.
 203     </p>
 204 <p><code class="function">lwres_nooprequest_render()</code>
 205       uses resolver context <em class="parameter"><code>ctx</code></em> to convert
 206       no-op request structure <em class="parameter"><code>req</code></em> to canonical
 207       format.  The packet header structure <em class="parameter"><code>pkt</code></em>
 208       is initialised and transferred to buffer
 209       <em class="parameter"><code>b</code></em>.  The contents of
 210       <em class="parameter"><code>*req</code></em> are then appended to the buffer in
 211       canonical format.
 212       <code class="function">lwres_noopresponse_render()</code> performs the
 213       same task, except it converts a no-op response structure
 214       <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's
 215       canonical format.
 216     </p>
 217 <p><code class="function">lwres_nooprequest_parse()</code>
 218       uses context <em class="parameter"><code>ctx</code></em> to convert the contents
 219       of packet <em class="parameter"><code>pkt</code></em> to a
 220       <span class="type">lwres_nooprequest_t</span> structure.  Buffer
 221       <em class="parameter"><code>b</code></em> provides space to be used for storing
 222       this structure.  When the function succeeds, the resulting
 223       <span class="type">lwres_nooprequest_t</span> is made available through
 224       <em class="parameter"><code>*structp</code></em>.
 225       <code class="function">lwres_noopresponse_parse()</code> offers the same
 226       semantics as <code class="function">lwres_nooprequest_parse()</code>
 227       except it yields a <span class="type">lwres_noopresponse_t</span> structure.
 228     </p>
 229 <p><code class="function">lwres_noopresponse_free()</code>
 230       and <code class="function">lwres_nooprequest_free()</code> release the
 231       memory in resolver context <em class="parameter"><code>ctx</code></em> that was
 232       allocated to the <span class="type">lwres_noopresponse_t</span> or
 233       <span class="type">lwres_nooprequest_t</span> structures referenced via
 234       <em class="parameter"><code>structp</code></em>.
 235     </p>
 236 </div>
 237 <div class="refsection">
 238 <a name="id-1.8"></a><h2>RETURN VALUES</h2>
 239 <p>
 240       The no-op opcode functions
 241       <code class="function">lwres_nooprequest_render()</code>,
 242
 243       <code class="function">lwres_noopresponse_render()</code>
 244       <code class="function">lwres_nooprequest_parse()</code>
 245       and
 246       <code class="function">lwres_noopresponse_parse()</code>
 247       all return
 248       <span class="errorcode">LWRES_R_SUCCESS</span>
 249       on success.
 250       They return
 251       <span class="errorcode">LWRES_R_NOMEMORY</span>
 252       if memory allocation fails.
 253       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 254       is returned if the available space in the buffer
 255       <em class="parameter"><code>b</code></em>
 256       is too small to accommodate the packet header or the
 257       <span class="type">lwres_nooprequest_t</span>
 258       and
 259       <span class="type">lwres_noopresponse_t</span>
 260       structures.
 261       <code class="function">lwres_nooprequest_parse()</code>
 262       and
 263       <code class="function">lwres_noopresponse_parse()</code>
 264       will return
 265       <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
 266       if the buffer is not empty after decoding the received packet.
 267       These functions will return
 268       <span class="errorcode">LWRES_R_FAILURE</span>
 269       if
 270       <code class="constant">pktflags</code>
 271       in the packet header structure
 272       <span class="type">lwres_lwpacket_t</span>
 273       indicate that the packet is not a response to an earlier query.
 274     </p>
 275 </div>
 276 <div class="refsection">
 277 <a name="id-1.9"></a><h2>SEE ALSO</h2>
 278 <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>
 279     </p>
 280 </div>
 281 </div></body>
 282 </html>