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

https://bitbucket.org/freebsd/freebsd-head/ · HTML · 317 lines · 298 code · 2 blank · 17 comment · 0 complexity · 16a817d8e1522b11e3a5a36f8dd89134 MD5 · raw file

  1. <!--
  2. - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
  3. - Copyright (C) 2000, 2001 Internet Software Consortium.
  4. -
  5. - Permission to use, copy, modify, and/or distribute this software for any
  6. - purpose with or without fee is hereby granted, provided that the above
  7. - copyright notice and this permission notice appear in all copies.
  8. -
  9. - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. - PERFORMANCE OF THIS SOFTWARE.
  16. -->
  17. <!-- $Id$ -->
  18. <html>
  19. <head>
  20. <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21. <title>lwres_noop</title>
  22. <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23. </head>
  24. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
  25. <a name="id2476275"></a><div class="titlepage"></div>
  26. <div class="refnamediv">
  27. <h2>Name</h2>
  28. <p>lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free &#8212; lightweight resolver no-op message handling</p>
  29. </div>
  30. <div class="refsynopsisdiv">
  31. <h2>Synopsis</h2>
  32. <div class="funcsynopsis">
  33. <pre class="funcsynopsisinfo">
  34. #include &lt;lwres/lwres.h&gt;</pre>
  35. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  36. <tr>
  37. <td><code class="funcdef">
  38. lwres_result_t
  39. <b class="fsfunc">lwres_nooprequest_render</b>(</code></td>
  40. <td>lwres_context_t * </td>
  41. <td>
  42. <var class="pdparam">ctx</var>, </td>
  43. </tr>
  44. <tr>
  45. <td> </td>
  46. <td>lwres_nooprequest_t * </td>
  47. <td>
  48. <var class="pdparam">req</var>, </td>
  49. </tr>
  50. <tr>
  51. <td> </td>
  52. <td>lwres_lwpacket_t * </td>
  53. <td>
  54. <var class="pdparam">pkt</var>, </td>
  55. </tr>
  56. <tr>
  57. <td> </td>
  58. <td>lwres_buffer_t * </td>
  59. <td>
  60. <var class="pdparam">b</var><code>)</code>;</td>
  61. </tr>
  62. </table>
  63. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  64. <tr>
  65. <td><code class="funcdef">
  66. lwres_result_t
  67. <b class="fsfunc">lwres_noopresponse_render</b>(</code></td>
  68. <td>lwres_context_t * </td>
  69. <td>
  70. <var class="pdparam">ctx</var>, </td>
  71. </tr>
  72. <tr>
  73. <td> </td>
  74. <td>lwres_noopresponse_t * </td>
  75. <td>
  76. <var class="pdparam">req</var>, </td>
  77. </tr>
  78. <tr>
  79. <td> </td>
  80. <td>lwres_lwpacket_t * </td>
  81. <td>
  82. <var class="pdparam">pkt</var>, </td>
  83. </tr>
  84. <tr>
  85. <td> </td>
  86. <td>lwres_buffer_t * </td>
  87. <td>
  88. <var class="pdparam">b</var><code>)</code>;</td>
  89. </tr>
  90. </table>
  91. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  92. <tr>
  93. <td><code class="funcdef">
  94. lwres_result_t
  95. <b class="fsfunc">lwres_nooprequest_parse</b>(</code></td>
  96. <td>lwres_context_t * </td>
  97. <td>
  98. <var class="pdparam">ctx</var>, </td>
  99. </tr>
  100. <tr>
  101. <td> </td>
  102. <td>lwres_buffer_t * </td>
  103. <td>
  104. <var class="pdparam">b</var>, </td>
  105. </tr>
  106. <tr>
  107. <td> </td>
  108. <td>lwres_lwpacket_t * </td>
  109. <td>
  110. <var class="pdparam">pkt</var>, </td>
  111. </tr>
  112. <tr>
  113. <td> </td>
  114. <td>lwres_nooprequest_t ** </td>
  115. <td>
  116. <var class="pdparam">structp</var><code>)</code>;</td>
  117. </tr>
  118. </table>
  119. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  120. <tr>
  121. <td><code class="funcdef">
  122. lwres_result_t
  123. <b class="fsfunc">lwres_noopresponse_parse</b>(</code></td>
  124. <td>lwres_context_t * </td>
  125. <td>
  126. <var class="pdparam">ctx</var>, </td>
  127. </tr>
  128. <tr>
  129. <td> </td>
  130. <td>lwres_buffer_t * </td>
  131. <td>
  132. <var class="pdparam">b</var>, </td>
  133. </tr>
  134. <tr>
  135. <td> </td>
  136. <td>lwres_lwpacket_t * </td>
  137. <td>
  138. <var class="pdparam">pkt</var>, </td>
  139. </tr>
  140. <tr>
  141. <td> </td>
  142. <td>lwres_noopresponse_t ** </td>
  143. <td>
  144. <var class="pdparam">structp</var><code>)</code>;</td>
  145. </tr>
  146. </table>
  147. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  148. <tr>
  149. <td><code class="funcdef">
  150. void
  151. <b class="fsfunc">lwres_noopresponse_free</b>(</code></td>
  152. <td>lwres_context_t * </td>
  153. <td>
  154. <var class="pdparam">ctx</var>, </td>
  155. </tr>
  156. <tr>
  157. <td> </td>
  158. <td>lwres_noopresponse_t ** </td>
  159. <td>
  160. <var class="pdparam">structp</var><code>)</code>;</td>
  161. </tr>
  162. </table>
  163. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
  164. <tr>
  165. <td><code class="funcdef">
  166. void
  167. <b class="fsfunc">lwres_nooprequest_free</b>(</code></td>
  168. <td>lwres_context_t * </td>
  169. <td>
  170. <var class="pdparam">ctx</var>, </td>
  171. </tr>
  172. <tr>
  173. <td> </td>
  174. <td>lwres_nooprequest_t ** </td>
  175. <td>
  176. <var class="pdparam">structp</var><code>)</code>;</td>
  177. </tr>
  178. </table>
  179. </div>
  180. </div>
  181. <div class="refsect1" lang="en">
  182. <a name="id2543526"></a><h2>DESCRIPTION</h2>
  183. <p>
  184. These are low-level routines for creating and parsing
  185. lightweight resolver no-op request and response messages.
  186. </p>
  187. <p>
  188. The no-op message is analogous to a <span><strong class="command">ping</strong></span>
  189. packet:
  190. a packet is sent to the resolver daemon and is simply echoed back.
  191. The opcode is intended to allow a client to determine if the server is
  192. operational or not.
  193. </p>
  194. <p>
  195. There are four main functions for the no-op opcode.
  196. One render function converts a no-op request structure &#8212;
  197. <span class="type">lwres_nooprequest_t</span> &#8212;
  198. to the lighweight resolver's canonical format.
  199. It is complemented by a parse function that converts a packet in this
  200. canonical format to a no-op request structure.
  201. Another render function converts the no-op response structure &#8212;
  202. <span class="type">lwres_noopresponse_t</span>
  203. to the canonical format.
  204. This is complemented by a parse function which converts a packet in
  205. canonical format to a no-op response structure.
  206. </p>
  207. <p>
  208. These structures are defined in
  209. <code class="filename">lwres/lwres.h</code>.
  210. They are shown below.
  211. </p>
  212. <pre class="programlisting">
  213. #define LWRES_OPCODE_NOOP 0x00000000U
  214. </pre>
  215. <p>
  216. </p>
  217. <pre class="programlisting">
  218. typedef struct {
  219. lwres_uint16_t datalength;
  220. unsigned char *data;
  221. } lwres_nooprequest_t;
  222. </pre>
  223. <p>
  224. </p>
  225. <pre class="programlisting">
  226. typedef struct {
  227. lwres_uint16_t datalength;
  228. unsigned char *data;
  229. } lwres_noopresponse_t;
  230. </pre>
  231. <p>
  232. </p>
  233. <p>
  234. Although the structures have different types, they are identical.
  235. This is because the no-op opcode simply echos whatever data was sent:
  236. the response is therefore identical to the request.
  237. </p>
  238. <p><code class="function">lwres_nooprequest_render()</code>
  239. uses resolver context <em class="parameter"><code>ctx</code></em> to convert
  240. no-op request structure <em class="parameter"><code>req</code></em> to canonical
  241. format. The packet header structure <em class="parameter"><code>pkt</code></em>
  242. is initialised and transferred to buffer
  243. <em class="parameter"><code>b</code></em>. The contents of
  244. <em class="parameter"><code>*req</code></em> are then appended to the buffer in
  245. canonical format.
  246. <code class="function">lwres_noopresponse_render()</code> performs the
  247. same task, except it converts a no-op response structure
  248. <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's
  249. canonical format.
  250. </p>
  251. <p><code class="function">lwres_nooprequest_parse()</code>
  252. uses context <em class="parameter"><code>ctx</code></em> to convert the contents
  253. of packet <em class="parameter"><code>pkt</code></em> to a
  254. <span class="type">lwres_nooprequest_t</span> structure. Buffer
  255. <em class="parameter"><code>b</code></em> provides space to be used for storing
  256. this structure. When the function succeeds, the resulting
  257. <span class="type">lwres_nooprequest_t</span> is made available through
  258. <em class="parameter"><code>*structp</code></em>.
  259. <code class="function">lwres_noopresponse_parse()</code> offers the same
  260. semantics as <code class="function">lwres_nooprequest_parse()</code>
  261. except it yields a <span class="type">lwres_noopresponse_t</span> structure.
  262. </p>
  263. <p><code class="function">lwres_noopresponse_free()</code>
  264. and <code class="function">lwres_nooprequest_free()</code> release the
  265. memory in resolver context <em class="parameter"><code>ctx</code></em> that was
  266. allocated to the <span class="type">lwres_noopresponse_t</span> or
  267. <span class="type">lwres_nooprequest_t</span> structures referenced via
  268. <em class="parameter"><code>structp</code></em>.
  269. </p>
  270. </div>
  271. <div class="refsect1" lang="en">
  272. <a name="id2543676"></a><h2>RETURN VALUES</h2>
  273. <p>
  274. The no-op opcode functions
  275. <code class="function">lwres_nooprequest_render()</code>,
  276. <code class="function">lwres_noopresponse_render()</code>
  277. <code class="function">lwres_nooprequest_parse()</code>
  278. and
  279. <code class="function">lwres_noopresponse_parse()</code>
  280. all return
  281. <span class="errorcode">LWRES_R_SUCCESS</span>
  282. on success.
  283. They return
  284. <span class="errorcode">LWRES_R_NOMEMORY</span>
  285. if memory allocation fails.
  286. <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
  287. is returned if the available space in the buffer
  288. <em class="parameter"><code>b</code></em>
  289. is too small to accommodate the packet header or the
  290. <span class="type">lwres_nooprequest_t</span>
  291. and
  292. <span class="type">lwres_noopresponse_t</span>
  293. structures.
  294. <code class="function">lwres_nooprequest_parse()</code>
  295. and
  296. <code class="function">lwres_noopresponse_parse()</code>
  297. will return
  298. <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>
  299. if the buffer is not empty after decoding the received packet.
  300. These functions will return
  301. <span class="errorcode">LWRES_R_FAILURE</span>
  302. if
  303. <code class="constant">pktflags</code>
  304. in the packet header structure
  305. <span class="type">lwres_lwpacket_t</span>
  306. indicate that the packet is not a response to an earlier query.
  307. </p>
  308. </div>
  309. <div class="refsect1" lang="en">
  310. <a name="id2543742"></a><h2>SEE ALSO</h2>
  311. <p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>
  312. </p>
  313. </div>
  314. </div></body>
  315. </html>