lwres_noop.docbook revision d4ef65050feac78554addf6e16a06c6e2e0bd331
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.
d4ef65050feac78554addf6e16a06c6e2e0bd331Brian Wellington<!-- $Id: lwres_noop.docbook,v 1.2 2001/04/10 21:52:03 bwelling 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>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson#define LWRES_OPCODE_NOOP 0x00000000U
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t datalength;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson unsigned char *data;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson} lwres_nooprequest_t;
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssontypedef struct {
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson lwres_uint16_t datalength;
ddccd5811feff696ba460dabfb666ce61040f545Andreas 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.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonuses resolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto convert no-op request structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe packet header structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis initialised and transferred to
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonThe contents of
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonare then appended to the buffer in canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_render()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonperforms the same task, except it converts a no-op response structure
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto the lightweight resolver's canonical format.
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonto convert the contents of packet
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonprovides space to be used for storing this structure.
ddccd5811feff696ba460dabfb666ce61040f545Andreas GustafssonWhen the function succeeds, the resulting
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonis made available through
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonoffers the same semantics as
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_parse()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonexcept it yields a
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_noopresponse_free()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafsson<function>lwres_nooprequest_free()</function>
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonrelease the memory in resolver context
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonthat was allocated to the
ddccd5811feff696ba460dabfb666ce61040f545Andreas Gustafssonstructures referenced via
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>