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

https://bitbucket.org/freebsd/freebsd-head/ · HTML · 235 lines · 217 code · 1 blank · 17 comment · 0 complexity · ed5551e0224a8d573d5fc8074c0e95c1 MD5 · raw file 

    

  1. <!--
    2. 

  2.  - Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc. ("ISC")
    3. 

  3.  - Copyright (C) 2000, 2001 Internet Software Consortium.
    4. 

  4.  - 
    5. 

  5.  - Permission to use, copy, modify, and/or distribute this software for any
    6. 

  6.  - purpose with or without fee is hereby granted, provided that the above
    7. 

  7.  - copyright notice and this permission notice appear in all copies.
    8. 

  8.  - 
    9. 

  9.  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
    10. 

  10.  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
    11. 

  11.  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
    12. 

  12.  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
    13. 

  13.  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
    14. 

  14.  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
    15. 

  15.  - PERFORMANCE OF THIS SOFTWARE.
    16. 

  16. -->
    17. 

  17. <!-- $Id$ -->
    18. 

  18. <html>
    19. 

  19. <head>
    20. 

  20. <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    21. 

  21. <title>lwres_packet</title>
    22. 

  22. <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
    23. 

  23. </head>
    24. 

  24. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
    25. 

  25. <a name="id2476275"></a><div class="titlepage"></div>
    26. 

  26. <div class="refnamediv">
    27. 

  27. <h2>Name</h2>
    28. 

  28. <p>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader &#8212; lightweight resolver packet handling functions</p>
    29. 

  29. </div>
    30. 

  30. <div class="refsynopsisdiv">
    31. 

  31. <h2>Synopsis</h2>
    32. 

  32. <div class="funcsynopsis">
    33. 

  33. <pre class="funcsynopsisinfo">#include &lt;lwres/lwpacket.h&gt;</pre>
    34. 

  34. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
    35. 

  35. <tr>
    36. 

  36. <td><code class="funcdef">
    37. 

  37. lwres_result_t
    38. 

  38. <b class="fsfunc">lwres_lwpacket_renderheader</b>(</code></td>
    39. 

  39. <td>lwres_buffer_t * </td>
    40. 

  40. <td>
    41. 

  41. <var class="pdparam">b</var>, </td>
    42. 

  42. </tr>
    43. 

  43. <tr>
    44. 

  44. <td> </td>
    45. 

  45. <td>lwres_lwpacket_t * </td>
    46. 

  46. <td>
    47. 

  47. <var class="pdparam">pkt</var><code>)</code>;</td>
    48. 

  48. </tr>
    49. 

  49. </table>
    50. 

  50. <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
    51. 

  51. <tr>
    52. 

  52. <td><code class="funcdef">
    53. 

  53. lwres_result_t
    54. 

  54. <b class="fsfunc">lwres_lwpacket_parseheader</b>(</code></td>
    55. 

  55. <td>lwres_buffer_t * </td>
    56. 

  56. <td>
    57. 

  57. <var class="pdparam">b</var>, </td>
    58. 

  58. </tr>
    59. 

  59. <tr>
    60. 

  60. <td> </td>
    61. 

  61. <td>lwres_lwpacket_t * </td>
    62. 

  62. <td>
    63. 

  63. <var class="pdparam">pkt</var><code>)</code>;</td>
    64. 

  64. </tr>
    65. 

  65. </table>
    66. 

  66. </div>
    67. 

  67. </div>
    68. 

  68. <div class="refsect1" lang="en">
    69. 

  69. <a name="id2543394"></a><h2>DESCRIPTION</h2>
    70. 

  70. <p>
    71. 

  71.       These functions rely on a
    72. 

  72.       <span class="type">struct lwres_lwpacket</span>
    73. 

  73.       which is defined in
    74. 

  74.       <code class="filename">lwres/lwpacket.h</code>.
    75. 

  75.     </p>
    76. 

  76. <pre class="programlisting">
    77. 

  77. typedef struct lwres_lwpacket lwres_lwpacket_t;
    78. 

  78.       </pre>
    79. 

  79. <p>
    80. 

  80.     </p>
    81. 

  81. <pre class="programlisting">
    82. 

  82. struct lwres_lwpacket {
    83. 

  83.         lwres_uint32_t          length;
    84. 

  84.         lwres_uint16_t          version;
    85. 

  85.         lwres_uint16_t          pktflags;
    86. 

  86.         lwres_uint32_t          serial;
    87. 

  87.         lwres_uint32_t          opcode;
    88. 

  88.         lwres_uint32_t          result;
    89. 

  89.         lwres_uint32_t          recvlength;
    90. 

  90.         lwres_uint16_t          authtype;
    91. 

  91.         lwres_uint16_t          authlength;
    92. 

  92. };
    93. 

  93. </pre>
    94. 

  94. <p>
    95. 

  95.     </p>
    96. 

  96. <p>
    97. 

  97.       The elements of this structure are:
    98. 

  98.       </p>
    99. 

  99. <div class="variablelist"><dl>
    100. 

  100. <dt><span class="term"><code class="constant">length</code></span></dt>
    101. 

  101. <dd><p>
    102. 

  102.               the overall packet length, including the entire packet header.
    103. 

  103.               This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
    104. 

  104.               calls.
    105. 

  105.             </p></dd>
    106. 

  106. <dt><span class="term"><code class="constant">version</code></span></dt>
    107. 

  107. <dd><p>
    108. 

  108.               the header format. There is currently only one format,
    109. 

  109.               <span class="type">LWRES_LWPACKETVERSION_0</span>.
    110. 

  110. 

  111.               This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
    112. 

  112.               calls.
    113. 

  113.             </p></dd>
    114. 

  114. <dt><span class="term"><code class="constant">pktflags</code></span></dt>
    115. 

  115. <dd><p>
    116. 

  116.               library-defined flags for this packet: for instance whether the
    117. 

  117.               packet
    118. 

  118.               is a request or a reply. Flag values can be set, but not defined
    119. 

  119.               by
    120. 

  120.               the caller.
    121. 

  121.               This field is filled in by the application wit the exception of
    122. 

  122.               the
    123. 

  123.               LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in
    124. 

  124.               the
    125. 

  125.               lwres_gabn_*() and lwres_gnba_*() calls.
    126. 

  126.             </p></dd>
    127. 

  127. <dt><span class="term"><code class="constant">serial</code></span></dt>
    128. 

  128. <dd><p>
    129. 

  129.               is set by the requestor and is returned in all replies. If two
    130. 

  130.               or more
    131. 

  131.               packets from the same source have the same serial number and are
    132. 

  132.               from
    133. 

  133.               the same source, they are assumed to be duplicates and the
    134. 

  134.               latter ones
    135. 

  135.               may be dropped.
    136. 

  136.               This field must be set by the application.
    137. 

  137.             </p></dd>
    138. 

  138. <dt><span class="term"><code class="constant">opcode</code></span></dt>
    139. 

  139. <dd><p>
    140. 

  140.               indicates the operation.
    141. 

  141.               Opcodes between 0x00000000 and 0x03ffffff are
    142. 

  142.               reserved for use by the lightweight resolver library. Opcodes
    143. 

  143.               between
    144. 

  144.               0x04000000 and 0xffffffff are application defined.
    145. 

  145.               This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
    146. 

  146.               calls.
    147. 

  147.             </p></dd>
    148. 

  148. <dt><span class="term"><code class="constant">result</code></span></dt>
    149. 

  149. <dd><p>
    150. 

  150.               is only valid for replies.
    151. 

  151.               Results between 0x04000000 and 0xffffffff are application
    152. 

  152.               defined.
    153. 

  153.               Results between 0x00000000 and 0x03ffffff are reserved for
    154. 

  154.               library use.
    155. 

  155.               This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
    156. 

  156.               calls.
    157. 

  157.             </p></dd>
    158. 

  158. <dt><span class="term"><code class="constant">recvlength</code></span></dt>
    159. 

  159. <dd><p>
    160. 

  160.               is the maximum buffer size that the receiver can handle on
    161. 

  161.               requests
    162. 

  162.               and the size of the buffer needed to satisfy a request when the
    163. 

  163.               buffer
    164. 

  164.               is too large for replies.
    165. 

  165.               This field is supplied by the application.
    166. 

  166.             </p></dd>
    167. 

  167. <dt><span class="term"><code class="constant">authtype</code></span></dt>
    168. 

  168. <dd><p>
    169. 

  169.               defines the packet level authentication that is used.
    170. 

  170.               Authorisation types between 0x1000 and 0xffff are application
    171. 

  171.               defined
    172. 

  172.               and types between 0x0000 and 0x0fff are reserved for library
    173. 

  173.               use.
    174. 

  174.               Currently these are not used and must be zero.
    175. 

  175.             </p></dd>
    176. 

  176. <dt><span class="term"><code class="constant">authlen</code></span></dt>
    177. 

  177. <dd><p>
    178. 

  178.               gives the length of the authentication data.
    179. 

  179.               Since packet authentication is currently not used, this must be
    180. 

  180.               zero.
    181. 

  181.             </p></dd>
    182. 

  182. </dl></div>
    183. 

  183. <p>
    184. 

  184.     </p>
    185. 

  185. <p>
    186. 

  186.       The following opcodes are currently defined:
    187. 

  187.       </p>
    188. 

  188. <div class="variablelist"><dl>
    189. 

  189. <dt><span class="term"><code class="constant">NOOP</code></span></dt>
    190. 

  190. <dd><p>
    191. 

  191.               Success is always returned and the packet contents are echoed.
    192. 

  192.               The lwres_noop_*() functions should be used for this type.
    193. 

  193.             </p></dd>
    194. 

  194. <dt><span class="term"><code class="constant">GETADDRSBYNAME</code></span></dt>
    195. 

  195. <dd><p>
    196. 

  196.               returns all known addresses for a given name.
    197. 

  197.               The lwres_gabn_*() functions should be used for this type.
    198. 

  198.             </p></dd>
    199. 

  199. <dt><span class="term"><code class="constant">GETNAMEBYADDR</code></span></dt>
    200. 

  200. <dd><p>
    201. 

  201.               return the hostname for the given address.
    202. 

  202.               The lwres_gnba_*() functions should be used for this type.
    203. 

  203.             </p></dd>
    204. 

  204. </dl></div>
    205. 

  205. <p>
    206. 

  206.     </p>
    207. 

  207. <p><code class="function">lwres_lwpacket_renderheader()</code>
    208. 

  208.       transfers the contents of lightweight resolver packet structure
    209. 

  209.       <span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in
    210. 

  210.       network byte order to the lightweight resolver buffer,
    211. 

  211.       <em class="parameter"><code>*b</code></em>.
    212. 

  212.     </p>
    213. 

  213. <p><code class="function">lwres_lwpacket_parseheader()</code>
    214. 

  214.       performs the converse operation.  It transfers data in network
    215. 

  215.       byte order from buffer <em class="parameter"><code>*b</code></em> to resolver
    216. 

  216.       packet <em class="parameter"><code>*pkt</code></em>.  The contents of the buffer
    217. 

  217.       <em class="parameter"><code>b</code></em> should correspond to a
    218. 

  218.       <span class="type">lwres_lwpacket_t</span>.
    219. 

  219.     </p>
    220. 

  220. </div>
    221. 

  221. <div class="refsect1" lang="en">
    222. 

  222. <a name="id2543710"></a><h2>RETURN VALUES</h2>
    223. 

  223. <p>
    224. 

  224.       Successful calls to
    225. 

  225.       <code class="function">lwres_lwpacket_renderheader()</code> and
    226. 

  226.       <code class="function">lwres_lwpacket_parseheader()</code> return
    227. 

  227.       <span class="errorcode">LWRES_R_SUCCESS</span>.  If there is insufficient
    228. 

  228.       space to copy data between the buffer <em class="parameter"><code>*b</code></em> and
    229. 

  229.       lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both
    230. 

  230.       functions
    231. 

  231.       return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>.
    232. 

  232.     </p>
    233. 

  233. </div>
    234. 

  234. </div></body>
    235. 

  235. </html>
    236.