lwres_noop.docbook revision 86b0285d7e65601645db4090d62ee6cb63abad6c
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington - Copyright (C) 2001 Internet Software Consortium.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - Permission to use, copy, modify, and distribute this software for any
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - purpose with or without fee is hereby granted, provided that the above
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - copyright notice and this permission notice appear in all copies.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<!-- $Id: lwres_noop.docbook,v 1.4 2001/06/18 22:07:00 gson Exp $ -->
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refentryinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_nooprequest_render</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_noopresponse_render</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_nooprequest_parse</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_noopresponse_parse</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refname>lwres_noopresponse_free</refname>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refpurpose>lightweight resolver no-op message handling</refpurpose>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson#include <lwres/lwres.h></funcsynopsisinfo>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_render</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_nooprequest_t *req</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_render</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_noopresponse_t *req</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_nooprequest_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_parse</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_lwpacket_t *pkt</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_noopresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_free</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_noopresponse_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_free</function></funcdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<paramdef>lwres_nooprequest_t **structp</paramdef>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcprototype>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</funcsynopsis>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</refsynopsisdiv>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese are low-level routines for creating and parsing
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonlightweight resolver no-op request and response messages.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe no-op message is analogous to a <command>ping</command> packet:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssona packet is sent to the resolver daemon and is simply echoed back.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe opcode is intended to allow a client to determine if the server is
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonoperational or not.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThere are four main functions for the no-op opcode.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonOne render function converts a no-op request structure —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the lighweight resolver's canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonIt is complemented by a parse function that converts a packet in this
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncanonical format to a no-op request structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAnother render function converts the no-op response structure —
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis is complemented by a parse function which converts a packet in
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssoncanonical format to a no-op response structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese structures are defined in
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThey are shown below.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<programlisting>
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson#define LWRES_OPCODE_NOOP 0x00000000U
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t datalength;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson unsigned char *data;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_nooprequest_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson lwres_uint16_t datalength;
8eea877894ea5bcf5cdd9ca124a8601ad421d753Andreas Gustafsson unsigned char *data;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_noopresponse_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</programlisting>
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonAlthough the structures have different types, they are identical.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThis is because the no-op opcode simply echos whatever data was sent:
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthe response is therefore identical to the request.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_nooprequest_render()</function> uses resolver
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssoncontext <parameter>ctx</parameter> to convert no-op request structure
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>req</parameter> to canonical format. The packet header
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonstructure <parameter>pkt</parameter> is initialised and transferred to
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonbuffer <parameter>b</parameter>. The contents of
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>*req</parameter> are then appended to the buffer in
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssoncanonical format. <function>lwres_noopresponse_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms the same task, except it converts a no-op response structure
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>lwres_noopresponse_t</type> to the lightweight resolver's
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssoncanonical format.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_nooprequest_parse()</function> uses context
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>ctx</parameter> to convert the contents of packet
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<parameter>pkt</parameter> to a <type>lwres_nooprequest_t</type>
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonstructure. Buffer <parameter>b</parameter> provides space to be used
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonfor storing this structure. When the function succeeds, the resulting
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>lwres_nooprequest_t</type> is made available through
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_noopresponse_parse()</function> offers the same
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonsemantics as <function>lwres_nooprequest_parse()</function> except it
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonyields a <type>lwres_noopresponse_t</type> structure.
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_noopresponse_free()</function> and
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<function>lwres_nooprequest_free()</function> release the memory in
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonresolver context <parameter>ctx</parameter> that was allocated to the
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafsson<type>lwres_noopresponse_t</type> or <type>lwres_nooprequest_t</type>
86b0285d7e65601645db4090d62ee6cb63abad6cAndreas Gustafssonstructures referenced via <parameter>structp</parameter>.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe no-op opcode functions
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_render()</function>,
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif memory allocation fails.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis returned if the available space in the buffer
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis too small to accommodate the packet header or the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonif the buffer is not empty after decoding the received packet.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThese functions will return
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonin the packet header structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonindicate that the packet is not a response to an earlier query.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson</citerefentry>