lwres_noop.html revision 794b79e6bbc3f5db1ea6ae154d739b9f1ef1a375
90e303b114e56db5809fdd19805243457fa43cd9Olafur Gudmundsson - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
90e303b114e56db5809fdd19805243457fa43cd9Olafur Gudmundsson - Copyright (C) 2000, 2001 Internet Software Consortium.
adbb11147cd5d97d140485fa37e85e66e15cf594Mark Andrews - Permission to use, copy, modify, and/or distribute this software for any
adbb11147cd5d97d140485fa37e85e66e15cf594Mark Andrews - purpose with or without fee is hereby granted, provided that the above
9ab461a6ffed2ae2fe0380c30b69052db7473405Mark Andrews - copyright notice and this permission notice appear in all copies.
77467267d97c781f3f3d050e229a874831e59c3dMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
77467267d97c781f3f3d050e229a874831e59c3dMark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
77467267d97c781f3f3d050e229a874831e59c3dMark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
13ba983cc86bc7d80d5f66ba09002f7d510a6631Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13ba983cc86bc7d80d5f66ba09002f7d510a6631Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
3036da01090c0d1e11cddc26af16630d6d9c1f39Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
84d8c0166ddc63ad5ce64e7d354553de38b9aabdAndreas Gustafsson - PERFORMANCE OF THIS SOFTWARE.
66291de2060a1569de3fe9c5f0c1225448868f7aMark Andrews<!-- $Id$ -->
84d8c0166ddc63ad5ce64e7d354553de38b9aabdAndreas Gustafsson<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
58d943711575376b05b3b3b303922a8a9d7ce9c1Mark Andrews<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
9cec4ca6cac428a46c6d64197c64831dcc02f506Andreas Gustafsson<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
9cec4ca6cac428a46c6d64197c64831dcc02f506Andreas Gustafsson<a name="id2476274"></a><div class="titlepage"></div>
23fb770906bf1fd98210f16ad660078274242963Mark Andrews<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>
8e40433e347bc487cd70f02487fc7ce947a2422aMark Andrews<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
880723fb130841459d45695b387651cacd6c9bb8Mark Andrewslwres_result_t
880723fb130841459d45695b387651cacd6c9bb8Mark Andrews<b class="fsfunc">lwres_nooprequest_render</b>(</code></td>
242bba8991b030b7764f0bdca3922d75c34ea51eAndreas Gustafsson<var class="pdparam">b</var><code>)</code>;</td>
242bba8991b030b7764f0bdca3922d75c34ea51eAndreas Gustafsson<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
02bdc23f8e3ca0f710e0a40daa15941ab1db6bb2Mark Andrews<b class="fsfunc">lwres_noopresponse_render</b>(</code></td>
3638017bd3cb8e30874f708a125d1541b680b25eBrian Wellington<var class="pdparam">b</var><code>)</code>;</td>
8771fbe4a2cee7bebd785a486824833d741c7315Brian Wellington<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
f59d47928ed33d1546e8f982370086429f727e85Andreas Gustafsson<b class="fsfunc">lwres_nooprequest_parse</b>(</code></td>
ee80f4506479e189ca1320eb87ac89188c5a7848Mark Andrews<var class="pdparam">structp</var><code>)</code>;</td>
d9d6d2f77fe54831dec9cde8ca03ae1f825599f9Andreas Gustafsson<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
eb2c518a3871932e86268e7c6ddae2b2a00d72fdMark Andrewslwres_result_t
4072dfb9b865c82c24a72e734d54da51a20dfc1eMark Andrews<b class="fsfunc">lwres_noopresponse_parse</b>(</code></td>
31f6e44dcaad33d66d607e3a919d4aa59cdbaec5Andreas Gustafsson<var class="pdparam">structp</var><code>)</code>;</td>
af36ecc41ae6bd73553aacd006ae55474e193b07Andreas Gustafsson<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
0b07b9482c00060d1ddd551a5dcb8cecbe2c1f65Mark Andrews<b class="fsfunc">lwres_noopresponse_free</b>(</code></td>
138cc7f283889367b11840ff77a9ea08e17a9daeAndreas Gustafsson<var class="pdparam">structp</var><code>)</code>;</td>
58930ca9802e772afe9f5ccb30f236d201cf60e0Danny Mayer<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
e3e94dd137c5f9d3d5c5179863f674b27aa0cc02Andreas Gustafsson<b class="fsfunc">lwres_nooprequest_free</b>(</code></td>
3e42bdfdc901b6b921b02028bd51ca2af8e84adcMark Andrews<var class="pdparam">structp</var><code>)</code>;</td>
b20eef7ab022dd984e2e9c12f6a7edf35661d3b0Mark Andrews These are low-level routines for creating and parsing
b20eef7ab022dd984e2e9c12f6a7edf35661d3b0Mark Andrews lightweight resolver no-op request and response messages.
bad3251d3f7ffccdec39ccfe04d94308985fb36eAndreas Gustafsson The no-op message is analogous to a <span><strong class="command">ping</strong></span>
80dd46d7aab16c42a8c1acf6156c95406a9f20a4Mark Andrews a packet is sent to the resolver daemon and is simply echoed back.
9eec883bf871ee2235009e889440f986c98908b8Andreas Gustafsson The opcode is intended to allow a client to determine if the server is
993572b2495561c57b556621dd9fe493e8c6dd1bDanny Mayer operational or not.
78bf1ca89505820ed7b03be4bf0c0b53b557f3cdAndreas Gustafsson There are four main functions for the no-op opcode.
78bf1ca89505820ed7b03be4bf0c0b53b557f3cdAndreas Gustafsson One render function converts a no-op request structure —
088eaf3878580eebbbd2b020411532af278aae5aAndreas Gustafsson <span class="type">lwres_nooprequest_t</span> —
6b13908f7030e09fb4573f3c2f8d7a5edc70e0b5Mark Andrews to the lighweight resolver's canonical format.
afeabf9f707ca71192041c1132d9f07d7bd83132Mark Andrews It is complemented by a parse function that converts a packet in this
3842a051baf34ffc4e428cd6f2d4a641e548e6f6Mark Andrews canonical format to a no-op request structure.
3842a051baf34ffc4e428cd6f2d4a641e548e6f6Mark Andrews Another render function converts the no-op response structure —
46ba6046bcb3b534346de13a4ff5c1513e72936bAndreas Gustafsson <span class="type">lwres_noopresponse_t</span>
46ba6046bcb3b534346de13a4ff5c1513e72936bAndreas Gustafsson to the canonical format.
46ba6046bcb3b534346de13a4ff5c1513e72936bAndreas Gustafsson This is complemented by a parse function which converts a packet in
a89d1aea0cce6a28a3751cd508db67e38d307a5eDanny Mayer canonical format to a no-op response structure.
04f158ce9a12746eb216892b2bf8259749db254eAndreas Gustafsson These structures are defined in
04f158ce9a12746eb216892b2bf8259749db254eAndreas Gustafsson <code class="filename">lwres/lwres.h</code>.
62c1fe7b450916acdaf4a3fe65a9b691d5d32f3fBrian Wellington They are shown below.
712bf9b0cc4ed34f4bf33b437f8b0e45853b93ceMark Andrews#define LWRES_OPCODE_NOOP 0x00000000U
72499be79fbb68140bd31e0e4ded18a70a5b523bMark Andrewstypedef struct {
90c5477ca11a94b0e7d8071181d69544e1ab9be9Mark Andrews lwres_uint16_t datalength;
90c5477ca11a94b0e7d8071181d69544e1ab9be9Mark Andrews unsigned char *data;
90c5477ca11a94b0e7d8071181d69544e1ab9be9Mark Andrews} lwres_nooprequest_t;
6fb633bc3fddba07fc9460ffd245b7ee2d459285Mark Andrewstypedef struct {
6fb633bc3fddba07fc9460ffd245b7ee2d459285Mark Andrews lwres_uint16_t datalength;
6fb633bc3fddba07fc9460ffd245b7ee2d459285Mark Andrews unsigned char *data;
ca033e166ca9f9dc7bf010065a93af668a09fd44Mark Andrews} lwres_noopresponse_t;
c8bedec446212b07511ded85ba04a9a3d5965ba8Mark Andrews Although the structures have different types, they are identical.
7a104af70fb3071e7949c4e0e585af18ab362db5Mark Andrews This is because the no-op opcode simply echos whatever data was sent:
7a104af70fb3071e7949c4e0e585af18ab362db5Mark Andrews the response is therefore identical to the request.
7a104af70fb3071e7949c4e0e585af18ab362db5Mark Andrews<p><code class="function">lwres_nooprequest_render()</code>
923de3bb9cf4d619de206544975986a22b18196fMark Andrews uses resolver context <em class="parameter"><code>ctx</code></em> to convert
923de3bb9cf4d619de206544975986a22b18196fMark Andrews no-op request structure <em class="parameter"><code>req</code></em> to canonical
2359261a252b339f3cef046cefa10ee1e1d4564dMark Andrews format. The packet header structure <em class="parameter"><code>pkt</code></em>
2359261a252b339f3cef046cefa10ee1e1d4564dMark Andrews is initialised and transferred to buffer
769cd7d5dd677434c3dfa27cbfdd8cb76296fcdcMark Andrews <em class="parameter"><code>b</code></em>. The contents of
769cd7d5dd677434c3dfa27cbfdd8cb76296fcdcMark Andrews <em class="parameter"><code>*req</code></em> are then appended to the buffer in
769cd7d5dd677434c3dfa27cbfdd8cb76296fcdcMark Andrews canonical format.
6bad645917a026dfa4662dd0a3a78b9efc3f4c36Mark Andrews <code class="function">lwres_noopresponse_render()</code> performs the
6bad645917a026dfa4662dd0a3a78b9efc3f4c36Mark Andrews same task, except it converts a no-op response structure
11931cc68d6c8139f507a724e7ca9814eed8b552Mark Andrews <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's
11931cc68d6c8139f507a724e7ca9814eed8b552Mark Andrews canonical format.
64e9b7eafb798c75e9a40948cf05d8847da59d9dAndreas Gustafsson<p><code class="function">lwres_nooprequest_parse()</code>
11931cc68d6c8139f507a724e7ca9814eed8b552Mark Andrews uses context <em class="parameter"><code>ctx</code></em> to convert the contents
11931cc68d6c8139f507a724e7ca9814eed8b552Mark Andrews of packet <em class="parameter"><code>pkt</code></em> to a
d91d025deffd075db2507d44fab04b79920b3e91Mark Andrews <span class="type">lwres_nooprequest_t</span> structure. Buffer
d91d025deffd075db2507d44fab04b79920b3e91Mark Andrews <em class="parameter"><code>b</code></em> provides space to be used for storing
d91d025deffd075db2507d44fab04b79920b3e91Mark Andrews this structure. When the function succeeds, the resulting
985b4f1c8653c6dfaa46652c412838850c0ffb1cMark Andrews <span class="type">lwres_nooprequest_t</span> is made available through
985b4f1c8653c6dfaa46652c412838850c0ffb1cMark Andrews <em class="parameter"><code>*structp</code></em>.
c8d9ff1fe871a0e9d5834240c5872a26166cc240Andreas Gustafsson <code class="function">lwres_noopresponse_parse()</code> offers the same
1d556695ef3c7918ba5061d7d846122d60f5f6c5Mark Andrews semantics as <code class="function">lwres_nooprequest_parse()</code>
e9ca87459a20f5e6721b9bd0b28c95fc3d6b843cMark Andrews except it yields a <span class="type">lwres_noopresponse_t</span> structure.
ca690f98020f75758bc26f4b5ef1ccf0472a27c3Mark Andrews<p><code class="function">lwres_noopresponse_free()</code>
ca690f98020f75758bc26f4b5ef1ccf0472a27c3Mark Andrews and <code class="function">lwres_nooprequest_free()</code> release the
ca690f98020f75758bc26f4b5ef1ccf0472a27c3Mark Andrews memory in resolver context <em class="parameter"><code>ctx</code></em> that was
137a1f98e3862577ae9ccbb6b735ef63a51c456eMark Andrews allocated to the <span class="type">lwres_noopresponse_t</span> or
137a1f98e3862577ae9ccbb6b735ef63a51c456eMark Andrews <span class="type">lwres_nooprequest_t</span> structures referenced via
5cd7e9d4db393c314dd1a761c52d2cb3a4da9b72Andreas Gustafsson <em class="parameter"><code>structp</code></em>.
cc8e8b59d6780889739657226a95e23ca1ecadb1Andreas Gustafsson<a name="id2543675"></a><h2>RETURN VALUES</h2>
1418d7292da7ebaba1ba389d60192023c0170245Andreas Gustafsson The no-op opcode functions
cc8e8b59d6780889739657226a95e23ca1ecadb1Andreas Gustafsson <code class="function">lwres_nooprequest_render()</code>,
65775fe205e8ac935313c42062c75460e0bc1514Andreas Gustafsson <code class="function">lwres_noopresponse_render()</code>
65775fe205e8ac935313c42062c75460e0bc1514Andreas Gustafsson <code class="function">lwres_nooprequest_parse()</code>
17b687ef360ba8c07201dc6511a3c975cc1bb2a8Andreas Gustafsson <code class="function">lwres_noopresponse_parse()</code>
17b687ef360ba8c07201dc6511a3c975cc1bb2a8Andreas Gustafsson <span class="errorcode">LWRES_R_SUCCESS</span>
998358fa900393378c70ad598c2b2e67385089d4Mark Andrews <span class="errorcode">LWRES_R_NOMEMORY</span>
2053e8c26cd69600132632fbee247601ce8c9e8cAndreas Gustafsson if memory allocation fails.
998358fa900393378c70ad598c2b2e67385089d4Mark Andrews <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
bc508906db43dda7eab0988348dd0ae3f3023a9bMark Andrews is returned if the available space in the buffer
bc508906db43dda7eab0988348dd0ae3f3023a9bMark Andrews is too small to accommodate the packet header or the
b352902413608d0eb310c4bb45412fa45734afbcAndreas Gustafsson <span class="type">lwres_nooprequest_t</span>
b352902413608d0eb310c4bb45412fa45734afbcAndreas Gustafsson <span class="type">lwres_noopresponse_t</span>
b352902413608d0eb310c4bb45412fa45734afbcAndreas Gustafsson <code class="function">lwres_nooprequest_parse()</code>
72e8c079c4c6dc66d565cf89ebf6feb5fa2dea33Mark Andrews <code class="function">lwres_noopresponse_parse()</code>
72e8c079c4c6dc66d565cf89ebf6feb5fa2dea33Mark Andrews <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
c8ab83c08e5227b5146295a9ef4a96d61b066b67Andreas Gustafsson if the buffer is not empty after decoding the received packet.
c8ab83c08e5227b5146295a9ef4a96d61b066b67Andreas Gustafsson These functions will return
c8ab83c08e5227b5146295a9ef4a96d61b066b67Andreas Gustafsson <span class="errorcode">LWRES_R_FAILURE</span>
4e57d3ff7d92abdef4b0b6aebc23a9dfae2ba040Andreas Gustafsson in the packet header structure
1c398fd83c444d61904d23431d3994139919b68eAndreas Gustafsson <span class="type">lwres_lwpacket_t</span>
be9932698bf35d0f34e65b5ffbb81bedddd76636Mark Andrews indicate that the packet is not a response to an earlier query.
3d38596530c389610494e6a6ba70d9f5dc9717c5Andreas Gustafsson<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>