lwres_noop.docbook revision 194e2dfffa6a167b8eef0ad11864026b423a1c30
19c7b1a0293498a3e36692c59646ed6e15ffc8d0Tinderbox User<!ENTITY mdash "—">]>
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - This Source Code Form is subject to the terms of the Mozilla Public
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - License, v. 2.0. If a copy of the MPL was not distributed with this
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - file, You can obtain one at http://mozilla.org/MPL/2.0/.
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<!-- Converted by db4-upgrade version 1.0 -->
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington <refentryinfo>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </refentryinfo>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refpurpose>lightweight resolver no-op message handling</refpurpose>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refnamediv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsynopsisdiv>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <funcsynopsis>
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews<funcsynopsisinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#include <lwres/lwres.h></funcsynopsisinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
94bd918b63001277f1b28ae4581645f8a835688fBob Halleylwres_result_t
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<function>lwres_nooprequest_render</function></funcdef>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt </funcprototype>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeinlwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_noopresponse_render</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <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 Austeinlwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_nooprequest_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <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 Austeinlwres_result_t
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_noopresponse_parse</function></funcdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <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>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<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>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<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 <refsection><info><title>DESCRIPTION</title></info>
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.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein 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 lightweight 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.
4eb998928b9aef0ceda42d7529980d658138698aEvan Hunt Another render function converts the no-op response structure —
4eb998928b9aef0ceda42d7529980d658138698aEvan Hunt to the canonical format.
4eb998928b9aef0ceda42d7529980d658138698aEvan Hunt 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
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein They are shown below.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein#define LWRES_OPCODE_NOOP 0x00000000U
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintypedef struct {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t datalength;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unsigned char *data;
94bd918b63001277f1b28ae4581645f8a835688fBob Halley} lwres_nooprequest_t;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt</programlisting>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunttypedef struct {
94bd918b63001277f1b28ae4581645f8a835688fBob Halley lwres_uint16_t datalength;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unsigned char *data;
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews} lwres_noopresponse_t;
94bd918b63001277f1b28ae4581645f8a835688fBob Halley</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.
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <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>
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews is initialised and transferred to buffer
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews <parameter>*req</parameter> are then appended to the buffer in
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews 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
94bd918b63001277f1b28ae4581645f8a835688fBob Halley canonical format.
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <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
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews <parameter>b</parameter> provides space to be used for storing
4eb998928b9aef0ceda42d7529980d658138698aEvan Hunt this structure. When the function succeeds, the resulting
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews <type>lwres_nooprequest_t</type> is made available through
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <function>lwres_noopresponse_parse()</function> offers the same
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein semantics as <function>lwres_nooprequest_parse()</function>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley except it yields a <type>lwres_noopresponse_t</type> structure.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_noopresponse_free()</function>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein and <function>lwres_nooprequest_free()</function> release the
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein memory in resolver context <parameter>ctx</parameter> that was
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein allocated to the <type>lwres_noopresponse_t</type> or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_nooprequest_t</type> structures referenced via
7389e8330d62a059b8923fb8ca6f933caeb559d9Mark Andrews </refsection>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <refsection><info><title>RETURN VALUES</title></info>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley The no-op opcode functions
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_nooprequest_render()</function>,
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <function>lwres_noopresponse_render()</function>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley 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
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt in the packet header structure
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein indicate that the packet is not a response to an earlier query.
94bd918b63001277f1b28ae4581645f8a835688fBob Halley </refsection>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </citerefentry>
94bd918b63001277f1b28ae4581645f8a835688fBob Halley </refsection>