/contrib/bind9/lib/lwres/man/lwres_noop.docbook
Unknown | 256 lines | 245 code | 11 blank | 0 comment | 0 complexity | f3b0160ae348886e8a70e13c2d322432 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 2 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 3 [<!ENTITY mdash "—">]> 4<!-- 5 - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC") 6 - Copyright (C) 2000, 2001 Internet Software Consortium. 7 - 8 - Permission to use, copy, modify, and/or distribute this software for any 9 - purpose with or without fee is hereby granted, provided that the above 10 - copyright notice and this permission notice appear in all copies. 11 - 12 - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13 - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14 - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15 - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16 - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17 - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18 - PERFORMANCE OF THIS SOFTWARE. 19--> 20 21<!-- $Id$ --> 22<refentry> 23 24 <refentryinfo> 25 <date>Jun 30, 2000</date> 26 </refentryinfo> 27 28 <refmeta> 29 <refentrytitle>lwres_noop</refentrytitle> 30 <manvolnum>3</manvolnum> 31 <refmiscinfo>BIND9</refmiscinfo> 32 </refmeta> 33 34 <docinfo> 35 <copyright> 36 <year>2004</year> 37 <year>2005</year> 38 <year>2007</year> 39 <year>2012</year> 40 <holder>Internet Systems Consortium, Inc. ("ISC")</holder> 41 </copyright> 42 <copyright> 43 <year>2000</year> 44 <year>2001</year> 45 <holder>Internet Software Consortium.</holder> 46 </copyright> 47 </docinfo> 48 49 <refnamediv> 50 <refname>lwres_nooprequest_render</refname> 51 <refname>lwres_noopresponse_render</refname> 52 <refname>lwres_nooprequest_parse</refname> 53 <refname>lwres_noopresponse_parse</refname> 54 <refname>lwres_noopresponse_free</refname> 55 <refname>lwres_nooprequest_free</refname> 56 <refpurpose>lightweight resolver no-op message handling</refpurpose> 57 </refnamediv> 58 <refsynopsisdiv> 59 <funcsynopsis> 60<funcsynopsisinfo> 61#include <lwres/lwres.h></funcsynopsisinfo> 62<funcprototype> 63 <funcdef> 64lwres_result_t 65<function>lwres_nooprequest_render</function></funcdef> 66 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 67 <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef> 68 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 69 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 70 </funcprototype> 71<funcprototype> 72 <funcdef> 73lwres_result_t 74<function>lwres_noopresponse_render</function></funcdef> 75 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 76 <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef> 77 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 78 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 79 </funcprototype> 80<funcprototype> 81 <funcdef> 82lwres_result_t 83<function>lwres_nooprequest_parse</function></funcdef> 84 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 85 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 86 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 87 <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef> 88 </funcprototype> 89<funcprototype> 90 <funcdef> 91lwres_result_t 92<function>lwres_noopresponse_parse</function></funcdef> 93 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 94 <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> 95 <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> 96 <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef> 97 </funcprototype> 98<funcprototype> 99 <funcdef> 100void 101<function>lwres_noopresponse_free</function></funcdef> 102 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 103 <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef> 104 </funcprototype> 105<funcprototype> 106 <funcdef> 107void 108<function>lwres_nooprequest_free</function></funcdef> 109 <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> 110 <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef> 111 </funcprototype> 112</funcsynopsis> 113 </refsynopsisdiv> 114 <refsect1> 115 <title>DESCRIPTION</title> 116 <para> 117 These are low-level routines for creating and parsing 118 lightweight resolver no-op request and response messages. 119 </para> 120 <para> 121 The no-op message is analogous to a <command>ping</command> 122 packet: 123 a packet is sent to the resolver daemon and is simply echoed back. 124 The opcode is intended to allow a client to determine if the server is 125 operational or not. 126 </para> 127 <para> 128 There are four main functions for the no-op opcode. 129 One render function converts a no-op request structure — 130 <type>lwres_nooprequest_t</type> — 131 to the lighweight resolver's canonical format. 132 It is complemented by a parse function that converts a packet in this 133 canonical format to a no-op request structure. 134 Another render function converts the no-op response structure — 135 <type>lwres_noopresponse_t</type> 136 to the canonical format. 137 This is complemented by a parse function which converts a packet in 138 canonical format to a no-op response structure. 139 </para> 140 <para> 141 These structures are defined in 142 <filename>lwres/lwres.h</filename>. 143 144 They are shown below. 145 </para> 146 <para><programlisting> 147#define LWRES_OPCODE_NOOP 0x00000000U 148</programlisting> 149 </para> 150 <para><programlisting> 151typedef struct { 152 lwres_uint16_t datalength; 153 unsigned char *data; 154} lwres_nooprequest_t; 155</programlisting> 156 </para> 157 <para><programlisting> 158typedef struct { 159 lwres_uint16_t datalength; 160 unsigned char *data; 161} lwres_noopresponse_t; 162</programlisting> 163 </para> 164 <para> 165 Although the structures have different types, they are identical. 166 This is because the no-op opcode simply echos whatever data was sent: 167 the response is therefore identical to the request. 168 </para> 169 170 <para><function>lwres_nooprequest_render()</function> 171 uses resolver context <parameter>ctx</parameter> to convert 172 no-op request structure <parameter>req</parameter> to canonical 173 format. The packet header structure <parameter>pkt</parameter> 174 is initialised and transferred to buffer 175 <parameter>b</parameter>. The contents of 176 <parameter>*req</parameter> are then appended to the buffer in 177 canonical format. 178 <function>lwres_noopresponse_render()</function> performs the 179 same task, except it converts a no-op response structure 180 <type>lwres_noopresponse_t</type> to the lightweight resolver's 181 canonical format. 182 </para> 183 184 <para><function>lwres_nooprequest_parse()</function> 185 uses context <parameter>ctx</parameter> to convert the contents 186 of packet <parameter>pkt</parameter> to a 187 <type>lwres_nooprequest_t</type> structure. Buffer 188 <parameter>b</parameter> provides space to be used for storing 189 this structure. When the function succeeds, the resulting 190 <type>lwres_nooprequest_t</type> is made available through 191 <parameter>*structp</parameter>. 192 <function>lwres_noopresponse_parse()</function> offers the same 193 semantics as <function>lwres_nooprequest_parse()</function> 194 except it yields a <type>lwres_noopresponse_t</type> structure. 195 </para> 196 197 <para><function>lwres_noopresponse_free()</function> 198 and <function>lwres_nooprequest_free()</function> release the 199 memory in resolver context <parameter>ctx</parameter> that was 200 allocated to the <type>lwres_noopresponse_t</type> or 201 <type>lwres_nooprequest_t</type> structures referenced via 202 <parameter>structp</parameter>. 203 </para> 204 205 </refsect1> 206 <refsect1> 207 <title>RETURN VALUES</title> 208 <para> 209 The no-op opcode functions 210 <function>lwres_nooprequest_render()</function>, 211 212 <function>lwres_noopresponse_render()</function> 213 <function>lwres_nooprequest_parse()</function> 214 and 215 <function>lwres_noopresponse_parse()</function> 216 all return 217 <errorcode>LWRES_R_SUCCESS</errorcode> 218 on success. 219 They return 220 <errorcode>LWRES_R_NOMEMORY</errorcode> 221 if memory allocation fails. 222 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> 223 is returned if the available space in the buffer 224 <parameter>b</parameter> 225 is too small to accommodate the packet header or the 226 <type>lwres_nooprequest_t</type> 227 and 228 <type>lwres_noopresponse_t</type> 229 structures. 230 <function>lwres_nooprequest_parse()</function> 231 and 232 <function>lwres_noopresponse_parse()</function> 233 will return 234 <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> 235 if the buffer is not empty after decoding the received packet. 236 These functions will return 237 <errorcode>LWRES_R_FAILURE</errorcode> 238 if 239 <constant>pktflags</constant> 240 in the packet header structure 241 <type>lwres_lwpacket_t</type> 242 indicate that the packet is not a response to an earlier query. 243 </para> 244 </refsect1> 245 <refsect1> 246 <title>SEE ALSO</title> 247 <para><citerefentry> 248 <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum> 249 </citerefentry> 250 </para> 251 </refsect1> 252</refentry><!-- 253 - Local variables: 254 - mode: sgml 255 - End: 256-->