lwres_noop.docbook revision 30eec077db2bdcb6f2a0dc388a3cdde2ede75ec1
5cd4555ad444fd391002ae32450572054369fd42Rob Austein<!ENTITY mdash "—">]>
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2004, 2005, 2007, 2014, 2015 Internet Systems Consortium, Inc. ("ISC")
a7c412f37cc73d0332887a746e81220cbf09dd00Mark Andrews - Copyright (C) 2000, 2001 Internet Software Consortium.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Permission to use, copy, modify, and/or distribute this software for any
ec5347e2c775f027573ce5648b910361aa926c01Automatic Updater - purpose with or without fee is hereby granted, provided that the above
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - copyright notice and this permission notice appear in all copies.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
dafcb997e390efa4423883dafd100c975c4095d6Mark Andrews - PERFORMANCE OF THIS SOFTWARE.
f5d30e2864e048a42c4dc1134993ae7efdb5d6c3Mark Andrews<!-- Converted by db4-upgrade version 1.0 -->
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <refentryinfo>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington </refentryinfo>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </copyright>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <refname>lwres_nooprequest_render</refname>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <refname>lwres_noopresponse_render</refname>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <refname>lwres_noopresponse_parse</refname>
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson <refpurpose>lightweight resolver no-op message handling</refpurpose>
bca7f81db58d4803fb6d8d352132445cf61eb1acMark Andrews </refnamediv>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <refsynopsisdiv>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <funcsynopsis>
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews<funcsynopsisinfo>
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews#include <lwres/lwres.h></funcsynopsisinfo>
92551304a9abff9284de5b79a48e83d781989339Mark Andrews<funcprototype>
c40265eba0c99708887d68e67901924065ba2514Brian Wellingtonlwres_result_t
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<function>lwres_nooprequest_render</function></funcdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt </funcprototype>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt<funcprototype>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Huntlwres_result_t
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt<function>lwres_noopresponse_render</function></funcdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt </funcprototype>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt<funcprototype>
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Huntlwres_result_t
85c5ed3577655f4f710f0af5ee93edd71c336055Evan Hunt<function>lwres_nooprequest_parse</function></funcdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington </funcprototype>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<funcprototype>
c40265eba0c99708887d68e67901924065ba2514Brian Wellingtonlwres_result_t
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews<function>lwres_noopresponse_parse</function></funcdef>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews </funcprototype>
0f8c9b5eed7e8714ceb7d6d3675555df9c5f6350Mark Andrews<funcprototype>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington<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>
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews </funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<funcprototype>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein<function>lwres_nooprequest_free</function></funcdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson </funcprototype>
a26ad011f382d12058478704cb5e90e6f4366d01Andreas Gustafsson</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.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews The no-op message is analogous to a <command>ping</command>
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews a packet is sent to the resolver daemon and is simply echoed back.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews The opcode is intended to allow a client to determine if the server is
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews operational or not.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews There are four main functions for the no-op opcode.
3bc4221346e5045c5679dd0d84f4f7d888a9da79Mark Andrews One render function converts a no-op request structure —
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews to the lightweight resolver's canonical format.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews It is complemented by a parse function that converts a packet in this
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews canonical format to a no-op request structure.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews Another render function converts the no-op response structure —
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews to the canonical format.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews This is complemented by a parse function which converts a packet in
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews canonical format to a no-op response structure.
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews These structures are defined in
ff6de396a93b9b73a37173059a595f3d295b57cbMark Andrews They are shown below.
92551304a9abff9284de5b79a48e83d781989339Mark Andrews#define LWRES_OPCODE_NOOP 0x00000000U
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
561a29af8c54a216e7d30b5b4f6e0d21661654ecMark Andrewstypedef struct {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t datalength;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unsigned char *data;
92551304a9abff9284de5b79a48e83d781989339Mark Andrews} lwres_nooprequest_t;
92551304a9abff9284de5b79a48e83d781989339Mark Andrews</programlisting>
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austeintypedef struct {
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein lwres_uint16_t datalength;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein unsigned char *data;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein} lwres_noopresponse_t;
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein</programlisting>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington Although the structures have different types, they are identical.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington 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
c40265eba0c99708887d68e67901924065ba2514Brian Wellington format. The packet header structure <parameter>pkt</parameter>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington is initialised and transferred to buffer
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <parameter>*req</parameter> are then appended to the buffer in
c40265eba0c99708887d68e67901924065ba2514Brian Wellington canonical format.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <function>lwres_noopresponse_render()</function> performs the
c40265eba0c99708887d68e67901924065ba2514Brian Wellington same task, except it converts a no-op response structure
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <type>lwres_noopresponse_t</type> to the lightweight resolver's
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein canonical format.
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <para><function>lwres_nooprequest_parse()</function>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington uses context <parameter>ctx</parameter> to convert the contents
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <type>lwres_nooprequest_t</type> structure. Buffer
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <parameter>b</parameter> provides space to be used for storing
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein this structure. When the function succeeds, the resulting
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_nooprequest_t</type> is made available through
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews <function>lwres_noopresponse_parse()</function> offers the same
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews semantics as <function>lwres_nooprequest_parse()</function>
6043e41fcf5dc91aa8a981c966512d73bdec31c1Mark Andrews except it yields a <type>lwres_noopresponse_t</type> structure.
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <para><function>lwres_noopresponse_free()</function>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington and <function>lwres_nooprequest_free()</function> release the
c40265eba0c99708887d68e67901924065ba2514Brian Wellington memory in resolver context <parameter>ctx</parameter> that was
c40265eba0c99708887d68e67901924065ba2514Brian Wellington allocated to the <type>lwres_noopresponse_t</type> or
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein <type>lwres_nooprequest_t</type> structures referenced via
268a4475065fe6a8cd7cc707820982cf5e98f430Rob Austein </refsection>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington <refsection><info><title>RETURN VALUES</title></info>
c40265eba0c99708887d68e67901924065ba2514Brian Wellington The no-op opcode functions