/contrib/bind9/lib/lwres/man/lwres_noop.docbook

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 256 lines · 245 code · 11 blank · 0 comment · 0 complexity · f3b0160ae348886e8a70e13c2d322432 MD5 · raw file

  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 "&#8212;">]>
  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. <!-- $Id$ -->
  21. <refentry>
  22. <refentryinfo>
  23. <date>Jun 30, 2000</date>
  24. </refentryinfo>
  25. <refmeta>
  26. <refentrytitle>lwres_noop</refentrytitle>
  27. <manvolnum>3</manvolnum>
  28. <refmiscinfo>BIND9</refmiscinfo>
  29. </refmeta>
  30. <docinfo>
  31. <copyright>
  32. <year>2004</year>
  33. <year>2005</year>
  34. <year>2007</year>
  35. <year>2012</year>
  36. <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  37. </copyright>
  38. <copyright>
  39. <year>2000</year>
  40. <year>2001</year>
  41. <holder>Internet Software Consortium.</holder>
  42. </copyright>
  43. </docinfo>
  44. <refnamediv>
  45. <refname>lwres_nooprequest_render</refname>
  46. <refname>lwres_noopresponse_render</refname>
  47. <refname>lwres_nooprequest_parse</refname>
  48. <refname>lwres_noopresponse_parse</refname>
  49. <refname>lwres_noopresponse_free</refname>
  50. <refname>lwres_nooprequest_free</refname>
  51. <refpurpose>lightweight resolver no-op message handling</refpurpose>
  52. </refnamediv>
  53. <refsynopsisdiv>
  54. <funcsynopsis>
  55. <funcsynopsisinfo>
  56. #include &lt;lwres/lwres.h&gt;</funcsynopsisinfo>
  57. <funcprototype>
  58. <funcdef>
  59. lwres_result_t
  60. <function>lwres_nooprequest_render</function></funcdef>
  61. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  62. <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef>
  63. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  64. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  65. </funcprototype>
  66. <funcprototype>
  67. <funcdef>
  68. lwres_result_t
  69. <function>lwres_noopresponse_render</function></funcdef>
  70. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  71. <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef>
  72. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  73. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  74. </funcprototype>
  75. <funcprototype>
  76. <funcdef>
  77. lwres_result_t
  78. <function>lwres_nooprequest_parse</function></funcdef>
  79. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  80. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  81. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  82. <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
  83. </funcprototype>
  84. <funcprototype>
  85. <funcdef>
  86. lwres_result_t
  87. <function>lwres_noopresponse_parse</function></funcdef>
  88. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  89. <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
  90. <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
  91. <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
  92. </funcprototype>
  93. <funcprototype>
  94. <funcdef>
  95. void
  96. <function>lwres_noopresponse_free</function></funcdef>
  97. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  98. <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef>
  99. </funcprototype>
  100. <funcprototype>
  101. <funcdef>
  102. void
  103. <function>lwres_nooprequest_free</function></funcdef>
  104. <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
  105. <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef>
  106. </funcprototype>
  107. </funcsynopsis>
  108. </refsynopsisdiv>
  109. <refsect1>
  110. <title>DESCRIPTION</title>
  111. <para>
  112. These are low-level routines for creating and parsing
  113. lightweight resolver no-op request and response messages.
  114. </para>
  115. <para>
  116. The no-op message is analogous to a <command>ping</command>
  117. packet:
  118. a packet is sent to the resolver daemon and is simply echoed back.
  119. The opcode is intended to allow a client to determine if the server is
  120. operational or not.
  121. </para>
  122. <para>
  123. There are four main functions for the no-op opcode.
  124. One render function converts a no-op request structure &mdash;
  125. <type>lwres_nooprequest_t</type> &mdash;
  126. to the lighweight resolver's canonical format.
  127. It is complemented by a parse function that converts a packet in this
  128. canonical format to a no-op request structure.
  129. Another render function converts the no-op response structure &mdash;
  130. <type>lwres_noopresponse_t</type>
  131. to the canonical format.
  132. This is complemented by a parse function which converts a packet in
  133. canonical format to a no-op response structure.
  134. </para>
  135. <para>
  136. These structures are defined in
  137. <filename>lwres/lwres.h</filename>.
  138. They are shown below.
  139. </para>
  140. <para><programlisting>
  141. #define LWRES_OPCODE_NOOP 0x00000000U
  142. </programlisting>
  143. </para>
  144. <para><programlisting>
  145. typedef struct {
  146. lwres_uint16_t datalength;
  147. unsigned char *data;
  148. } lwres_nooprequest_t;
  149. </programlisting>
  150. </para>
  151. <para><programlisting>
  152. typedef struct {
  153. lwres_uint16_t datalength;
  154. unsigned char *data;
  155. } lwres_noopresponse_t;
  156. </programlisting>
  157. </para>
  158. <para>
  159. Although the structures have different types, they are identical.
  160. This is because the no-op opcode simply echos whatever data was sent:
  161. the response is therefore identical to the request.
  162. </para>
  163. <para><function>lwres_nooprequest_render()</function>
  164. uses resolver context <parameter>ctx</parameter> to convert
  165. no-op request structure <parameter>req</parameter> to canonical
  166. format. The packet header structure <parameter>pkt</parameter>
  167. is initialised and transferred to buffer
  168. <parameter>b</parameter>. The contents of
  169. <parameter>*req</parameter> are then appended to the buffer in
  170. canonical format.
  171. <function>lwres_noopresponse_render()</function> performs the
  172. same task, except it converts a no-op response structure
  173. <type>lwres_noopresponse_t</type> to the lightweight resolver's
  174. canonical format.
  175. </para>
  176. <para><function>lwres_nooprequest_parse()</function>
  177. uses context <parameter>ctx</parameter> to convert the contents
  178. of packet <parameter>pkt</parameter> to a
  179. <type>lwres_nooprequest_t</type> structure. Buffer
  180. <parameter>b</parameter> provides space to be used for storing
  181. this structure. When the function succeeds, the resulting
  182. <type>lwres_nooprequest_t</type> is made available through
  183. <parameter>*structp</parameter>.
  184. <function>lwres_noopresponse_parse()</function> offers the same
  185. semantics as <function>lwres_nooprequest_parse()</function>
  186. except it yields a <type>lwres_noopresponse_t</type> structure.
  187. </para>
  188. <para><function>lwres_noopresponse_free()</function>
  189. and <function>lwres_nooprequest_free()</function> release the
  190. memory in resolver context <parameter>ctx</parameter> that was
  191. allocated to the <type>lwres_noopresponse_t</type> or
  192. <type>lwres_nooprequest_t</type> structures referenced via
  193. <parameter>structp</parameter>.
  194. </para>
  195. </refsect1>
  196. <refsect1>
  197. <title>RETURN VALUES</title>
  198. <para>
  199. The no-op opcode functions
  200. <function>lwres_nooprequest_render()</function>,
  201. <function>lwres_noopresponse_render()</function>
  202. <function>lwres_nooprequest_parse()</function>
  203. and
  204. <function>lwres_noopresponse_parse()</function>
  205. all return
  206. <errorcode>LWRES_R_SUCCESS</errorcode>
  207. on success.
  208. They return
  209. <errorcode>LWRES_R_NOMEMORY</errorcode>
  210. if memory allocation fails.
  211. <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
  212. is returned if the available space in the buffer
  213. <parameter>b</parameter>
  214. is too small to accommodate the packet header or the
  215. <type>lwres_nooprequest_t</type>
  216. and
  217. <type>lwres_noopresponse_t</type>
  218. structures.
  219. <function>lwres_nooprequest_parse()</function>
  220. and
  221. <function>lwres_noopresponse_parse()</function>
  222. will return
  223. <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
  224. if the buffer is not empty after decoding the received packet.
  225. These functions will return
  226. <errorcode>LWRES_R_FAILURE</errorcode>
  227. if
  228. <constant>pktflags</constant>
  229. in the packet header structure
  230. <type>lwres_lwpacket_t</type>
  231. indicate that the packet is not a response to an earlier query.
  232. </para>
  233. </refsect1>
  234. <refsect1>
  235. <title>SEE ALSO</title>
  236. <para><citerefentry>
  237. <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum>
  238. </citerefentry>
  239. </para>
  240. </refsect1>
  241. </refentry><!--
  242. - Local variables:
  243. - mode: sgml
  244. - End:
  245. -->