lwres_noop.html revision ea94d370123a5892f6c47a97f21d1b28d44bb168
cd348e325366620fe047edcc849e3c9424828599Peter Bray - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
0ca9a2c194523c517c3aafe5758e217ac88d6baaLubos Kosco - Copyright (C) 2000, 2001 Internet Software Consortium.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - Permission to use, copy, modify, and/or distribute this software for any
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - purpose with or without fee is hereby granted, provided that the above
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - copyright notice and this permission notice appear in all copies.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray - PERFORMANCE OF THIS SOFTWARE.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<!-- $Id$ -->
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<a name="id2476274"></a><div class="titlepage"></div>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<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>
cd348e325366620fe047edcc849e3c9424828599Peter Bray<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
cd348e325366620fe047edcc849e3c9424828599Peter Braylwres_result_t
cd348e325366620fe047edcc849e3c9424828599Peter Bray<b class="fsfunc">lwres_nooprequest_render</b>(</code></td>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
cd348e325366620fe047edcc849e3c9424828599Peter Braylwres_result_t
cd348e325366620fe047edcc849e3c9424828599Peter Bray<b class="fsfunc">lwres_noopresponse_render</b>(</code></td>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
cd348e325366620fe047edcc849e3c9424828599Peter Braylwres_result_t
cd348e325366620fe047edcc849e3c9424828599Peter Bray<b class="fsfunc">lwres_nooprequest_parse</b>(</code></td>
cd348e325366620fe047edcc849e3c9424828599Peter Bray<var class="pdparam">structp</var><code>)</code>;</td>
cd348e325366620fe047edcc849e3c9424828599Peter Bray<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
cd348e325366620fe047edcc849e3c9424828599Peter Braylwres_result_t
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<b class="fsfunc">lwres_noopresponse_parse</b>(</code></td>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<var class="pdparam">structp</var><code>)</code>;</td>
cd348e325366620fe047edcc849e3c9424828599Peter Bray<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
cd348e325366620fe047edcc849e3c9424828599Peter Bray<b class="fsfunc">lwres_noopresponse_free</b>(</code></td>
cd348e325366620fe047edcc849e3c9424828599Peter Bray<var class="pdparam">structp</var><code>)</code>;</td>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<b class="fsfunc">lwres_nooprequest_free</b>(</code></td>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<var class="pdparam">structp</var><code>)</code>;</td>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray These are low-level routines for creating and parsing
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray lightweight resolver no-op request and response messages.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray The no-op message is analogous to a <span><strong class="command">ping</strong></span>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray a packet is sent to the resolver daemon and is simply echoed back.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray The opcode is intended to allow a client to determine if the server is
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray operational or not.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray There are four main functions for the no-op opcode.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray One render function converts a no-op request structure —
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="type">lwres_nooprequest_t</span> —
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray to the lighweight resolver's canonical format.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray It is complemented by a parse function that converts a packet in this
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray canonical format to a no-op request structure.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray Another render function converts the no-op response structure —
cd348e325366620fe047edcc849e3c9424828599Peter Bray to the canonical format.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray This is complemented by a parse function which converts a packet in
cd348e325366620fe047edcc849e3c9424828599Peter Bray canonical format to a no-op response structure.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray These structures are defined in
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray They are shown below.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray#define LWRES_OPCODE_NOOP 0x00000000U
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Braytypedef struct {
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray lwres_uint16_t datalength;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray unsigned char *data;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray} lwres_nooprequest_t;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Braytypedef struct {
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray lwres_uint16_t datalength;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray unsigned char *data;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray} lwres_noopresponse_t;
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray Although the structures have different types, they are identical.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray This is because the no-op opcode simply echos whatever data was sent:
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray the response is therefore identical to the request.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><code class="function">lwres_nooprequest_render()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray uses resolver context <em class="parameter"><code>ctx</code></em> to convert
3aa0947feb67d3e8292d84776638be98dd97fdc3Lubos Kosco no-op request structure <em class="parameter"><code>req</code></em> to canonical
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray format. The packet header structure <em class="parameter"><code>pkt</code></em>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray is initialised and transferred to buffer
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <em class="parameter"><code>b</code></em>. The contents of
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <em class="parameter"><code>*req</code></em> are then appended to the buffer in
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray canonical format.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_noopresponse_render()</code> performs the
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray same task, except it converts a no-op response structure
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray canonical format.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><code class="function">lwres_nooprequest_parse()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray uses context <em class="parameter"><code>ctx</code></em> to convert the contents
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray of packet <em class="parameter"><code>pkt</code></em> to a
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="type">lwres_nooprequest_t</span> structure. Buffer
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <em class="parameter"><code>b</code></em> provides space to be used for storing
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray this structure. When the function succeeds, the resulting
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="type">lwres_nooprequest_t</span> is made available through
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <em class="parameter"><code>*structp</code></em>.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_noopresponse_parse()</code> offers the same
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray semantics as <code class="function">lwres_nooprequest_parse()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray except it yields a <span class="type">lwres_noopresponse_t</span> structure.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><code class="function">lwres_noopresponse_free()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray and <code class="function">lwres_nooprequest_free()</code> release the
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray memory in resolver context <em class="parameter"><code>ctx</code></em> that was
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray allocated to the <span class="type">lwres_noopresponse_t</span> or
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="type">lwres_nooprequest_t</span> structures referenced via
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray The no-op opcode functions
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_nooprequest_render()</code>,
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_noopresponse_render()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_nooprequest_parse()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_noopresponse_parse()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray if memory allocation fails.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray is returned if the available space in the buffer
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray is too small to accommodate the packet header or the
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_nooprequest_parse()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <code class="function">lwres_noopresponse_parse()</code>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray if the buffer is not empty after decoding the received packet.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray These functions will return
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray in the packet header structure
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray indicate that the packet is not a response to an earlier query.
d2a02e104622a26dd90fa88f4f17188f2039809fPeter Bray<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>