lwres_noop.html revision 4a14ce5ba00ab7bc55c99ffdcf59c7a4ab902721
c63ebf815c8a874525cf18670ad74847f7fc7b26Christian Maeder - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder - Copyright (C) 2000, 2001 Internet Software Consortium.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder - Permission to use, copy, modify, and/or distribute this software for any
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - purpose with or without fee is hereby granted, provided that the above
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - copyright notice and this permission notice appear in all copies.
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
f4a2a20e49f41b2afa657e5e64d9e349c7faa091Christian Maeder - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder - PERFORMANCE OF THIS SOFTWARE.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder<!-- $Id: lwres_noop.html,v 1.26 2009/07/11 01:12:46 tbox Exp $ -->
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
a737caf82de97c1907027c03e4b4509eb492b4b8Christian Maeder<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
68d10d143f29fcff3c637ba24f90e983995ceae6Christian Maeder<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
96646aed2ae087b942ae23f15bbe729a8f7c43d3Christian Maeder<a name="id2476275"></a><div class="titlepage"></div>
9dac90ec2be2a72e03893095461960d483fe2fc2Christian Maeder<p>lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free — lightweight resolver no-op message handling</p>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettichlwres_result_t
b1f59a4ea7c96f4c03a4d7cfcb9c5e66871cfbbbChristian Maeder<b class="fsfunc">lwres_nooprequest_render</b>(</code></td>
7cc09dd93962a2155c34d209d1d4cd7d7b838264Christian Maeder<var class="pdparam">b</var><code>)</code>;</td>
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
f4a2a20e49f41b2afa657e5e64d9e349c7faa091Christian Maederlwres_result_t
f4a2a20e49f41b2afa657e5e64d9e349c7faa091Christian Maeder<b class="fsfunc">lwres_noopresponse_render</b>(</code></td>
797ccd67cb8ae127be097cd43448801b673e3b69Christian Maeder<var class="pdparam">b</var><code>)</code>;</td>
498aa48bdb931ab50990d3b74318a5db2312186cChristian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maederlwres_result_t
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder<b class="fsfunc">lwres_nooprequest_parse</b>(</code></td>
51d769d55d88dfa88bdf54bee78d8fa85a2deba8Christian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
bc8cbf12aa172bf5673b92a9e7a0151d4aa4c315Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
2d130d212db7208777ca896a7ecad619a8944971Christian Maederlwres_result_t
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder<b class="fsfunc">lwres_noopresponse_parse</b>(</code></td>
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
0be0db405c49906bd7057255069bf6df53395ac9Klaus Luettich<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<b class="fsfunc">lwres_noopresponse_free</b>(</code></td>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder<b class="fsfunc">lwres_nooprequest_free</b>(</code></td>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder<var class="pdparam">structp</var><code>)</code>;</td>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder<a name="id2543522"></a><h2>DESCRIPTION</h2>
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder These are low-level routines for creating and parsing
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder lightweight resolver no-op request and response messages.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder The no-op message is analogous to a <span><strong class="command">ping</strong></span>
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder a packet is sent to the resolver daemon and is simply echoed back.
c9a7e6af169a2adfb92f42331cd578065ed83a2bChristian Maeder The opcode is intended to allow a client to determine if the server is
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder operational or not.
42b12fba6830ada5057949f825fc27edf5574e5fChristian Maeder There are four main functions for the no-op opcode.
42b12fba6830ada5057949f825fc27edf5574e5fChristian Maeder One render function converts a no-op request structure —
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <span class="type">lwres_nooprequest_t</span> —
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder to the lighweight resolver's canonical format.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder It is complemented by a parse function that converts a packet in this
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder canonical format to a no-op request structure.
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder Another render function converts the no-op response structure —
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <span class="type">lwres_noopresponse_t</span>
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder to the canonical format.
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder This is complemented by a parse function which converts a packet in
93f5b72fdb9ee734caa750b43dd79bbb590dcd73Christian Maeder canonical format to a no-op response structure.
a6db617ca58eb6a0587b6366e913107dfecb71b5Heng Jiang These structures are defined in
5b818f10e11fc79def1fdd5c8a080d64a6438d87Christian Maeder They are shown below.
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder#define LWRES_OPCODE_NOOP 0x00000000U
8b0f493ae42bad8b94918cc0957f1af57096cda4Felix Reckerstypedef struct {
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder lwres_uint16_t datalength;
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder unsigned char *data;
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder} lwres_nooprequest_t;
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maedertypedef struct {
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder lwres_uint16_t datalength;
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder unsigned char *data;
383aa66e5142365fe9b1f88b18c1da5b27cc8c04Christian Maeder} lwres_noopresponse_t;
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder Although the structures have different types, they are identical.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder This is because the no-op opcode simply echos whatever data was sent:
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder the response is therefore identical to the request.
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder<p><code class="function">lwres_nooprequest_render()</code>
f9e0b18852b238ddb649d341194e05d7200d1bbeChristian Maeder uses resolver context <em class="parameter"><code>ctx</code></em> to convert
f9e0b18852b238ddb649d341194e05d7200d1bbeChristian Maeder no-op request structure <em class="parameter"><code>req</code></em> to canonical
f9e0b18852b238ddb649d341194e05d7200d1bbeChristian Maeder format. The packet header structure <em class="parameter"><code>pkt</code></em>
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder is initialised and transferred to buffer
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <em class="parameter"><code>b</code></em>. The contents of
819e29dba060687cf391e444e0f6ff88c1908cc3Christian Maeder <em class="parameter"><code>*req</code></em> are then appended to the buffer in
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder canonical format.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <code class="function">lwres_noopresponse_render()</code> performs the
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder same task, except it converts a no-op response structure
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder canonical format.
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder<p><code class="function">lwres_nooprequest_parse()</code>
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder uses context <em class="parameter"><code>ctx</code></em> to convert the contents
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder of packet <em class="parameter"><code>pkt</code></em> to a
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="type">lwres_nooprequest_t</span> structure. Buffer
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <em class="parameter"><code>b</code></em> provides space to be used for storing
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder this structure. When the function succeeds, the resulting
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder <span class="type">lwres_nooprequest_t</span> is made available through
ac34194a668399bb8ef238da77c3a09e93fb253bChristian Maeder <em class="parameter"><code>*structp</code></em>.
ac34194a668399bb8ef238da77c3a09e93fb253bChristian Maeder <code class="function">lwres_noopresponse_parse()</code> offers the same
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder semantics as <code class="function">lwres_nooprequest_parse()</code>
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder except it yields a <span class="type">lwres_noopresponse_t</span> structure.
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder<p><code class="function">lwres_noopresponse_free()</code>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder and <code class="function">lwres_nooprequest_free()</code> release the
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder memory in resolver context <em class="parameter"><code>ctx</code></em> that was
986d3f255182539098a97ac86da9eeee5b7a72e3Christian Maeder allocated to the <span class="type">lwres_noopresponse_t</span> or
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <span class="type">lwres_nooprequest_t</span> structures referenced via
4561227a776bdf0ab679b19fb92f1eaaed8786f7Christian Maeder <em class="parameter"><code>structp</code></em>.
8c812cd83569e973f10cf69a342424ceabc07af9Christian Maeder<a name="id2543672"></a><h2>RETURN VALUES</h2>
8c812cd83569e973f10cf69a342424ceabc07af9Christian Maeder The no-op opcode functions
05a206508bc898f87fe6ab6e069814df3c29d303Dominik Luecke <code class="function">lwres_nooprequest_render()</code>,
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <code class="function">lwres_noopresponse_render()</code>
d54cd08a4cfa26256c38d8ed12c343adbfe1a0e3Christian Maeder <code class="function">lwres_nooprequest_parse()</code>
d54cd08a4cfa26256c38d8ed12c343adbfe1a0e3Christian Maeder <code class="function">lwres_noopresponse_parse()</code>
b1f59a4ea7c96f4c03a4d7cfcb9c5e66871cfbbbChristian Maeder <span class="errorcode">LWRES_R_SUCCESS</span>
0b349288edfa50fdf38fda1a14e1562d03f92574Christian Maeder <span class="errorcode">LWRES_R_NOMEMORY</span>
55a09617886a31d9a9cb04a583bc4d4ef91b6c71Liam O'Reilly if memory allocation fails.
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
1b3a2f98d1cd01fc9e0591f69507e20526727559Dominik Luecke is returned if the available space in the buffer
247cc88aa55d0a7b6831767cd593ea885c6747a0Christian Maeder is too small to accommodate the packet header or the
e39a1626bee36d6ad13a2c0014a80ef179a65bcbChristian Maeder <span class="type">lwres_nooprequest_t</span>
ea3bff3e547a1ac714d4db39c5efef95e02b2e7dChristian Maeder <span class="type">lwres_noopresponse_t</span>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <code class="function">lwres_nooprequest_parse()</code>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <code class="function">lwres_noopresponse_parse()</code>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder if the buffer is not empty after decoding the received packet.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder These functions will return
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder <span class="errorcode">LWRES_R_FAILURE</span>
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder in the packet header structure
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder indicate that the packet is not a response to an earlier query.
456238178f89e5a3de2988ee6c8af924297d52d9Christian Maeder<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>