lwres_noop.docbook revision 938440694b33cd752e9e4b71a526368b4811c177
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson [<!ENTITY mdash "—">]>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews - Permission to use, copy, modify, and/or distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User - copyright notice and this permission notice appear in all copies.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt - PERFORMANCE OF THIS SOFTWARE.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refname>lwres_noopresponse_parse</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refname>lwres_noopresponse_free</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refname>lwres_nooprequest_free</refname>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver no-op message handling</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcsynopsisinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#include <lwres/lwres.h></funcsynopsisinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_nooprequest_render</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_noopresponse_render</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_nooprequest_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_noopresponse_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_free</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews<function>lwres_nooprequest_free</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</funcsynopsis>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These are low-level routines for creating and parsing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lightweight resolver no-op request and response messages.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The no-op message is analogous to a <command>ping</command>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein a packet is sent to the resolver daemon and is simply echoed back.
821350367e2c7313c02eb275e8e05d5193b47cfdJeremy C. Reed The opcode is intended to allow a client to determine if the server is
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein operational or not.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein There are four main functions for the no-op opcode.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein One render function converts a no-op request structure —
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein to the lighweight resolver's canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein It is complemented by a parse function that converts a packet in this
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format to a no-op request structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Another render function converts the no-op response structure —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson to the canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is complemented by a parse function which converts a packet in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format to a no-op response structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These structures are defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson They are shown below.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson#define LWRES_OPCODE_NOOP 0x00000000U
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t datalength;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson unsigned char *data;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_nooprequest_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintypedef struct {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t datalength;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unsigned char *data;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein} lwres_noopresponse_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein Although the structures have different types, they are identical.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein This is because the no-op opcode simply echos whatever data was sent:
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein the response is therefore identical to the request.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_nooprequest_render()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein uses resolver context <parameter>ctx</parameter> to convert
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein no-op request structure <parameter>req</parameter> to canonical
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein format. The packet header structure <parameter>pkt</parameter>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is initialised and transferred to buffer
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson <parameter>*req</parameter> are then appended to the buffer in
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_noopresponse_render()</function> performs the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein same task, except it converts a no-op response structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_noopresponse_t</type> to the lightweight resolver's
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_nooprequest_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein uses context <parameter>ctx</parameter> to convert the contents
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_nooprequest_t</type> structure. Buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <parameter>b</parameter> provides space to be used for storing
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson this structure. When the function succeeds, the resulting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_nooprequest_t</type> is made available through
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_noopresponse_parse()</function> offers the same
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein semantics as <function>lwres_nooprequest_parse()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein except it yields a <type>lwres_noopresponse_t</type> structure.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson <para><function>lwres_noopresponse_free()</function>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt and <function>lwres_nooprequest_free()</function> release the
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt memory in resolver context <parameter>ctx</parameter> that was
30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1Mark Andrews allocated to the <type>lwres_noopresponse_t</type> or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_nooprequest_t</type> structures referenced via
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein The no-op opcode functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_nooprequest_render()</function>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_noopresponse_render()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if memory allocation fails.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is returned if the available space in the buffer
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein is too small to accommodate the packet header or the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein if the buffer is not empty after decoding the received packet.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein These functions will return
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein in the packet header structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein indicate that the packet is not a response to an earlier query.