/contrib/bind9/lib/lwres/include/lwres/lwbuffer.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 406 lines · 56 code · 35 blank · 315 comment · 3 complexity · de4fd9bbc41badc0d78922a975179928 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007 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: lwbuffer.h,v 1.22 2007/06/19 23:47:23 tbox Exp $ */
  18. /*! \file lwres/lwbuffer.h
  19. *
  20. * A buffer is a region of memory, together with a set of related subregions.
  21. * Buffers are used for parsing and I/O operations.
  22. *
  23. * The 'used region' and the 'available' region are disjoint, and their
  24. * union is the buffer's region. The used region extends from the beginning
  25. * of the buffer region to the last used byte. The available region
  26. * extends from one byte greater than the last used byte to the end of the
  27. * buffer's region. The size of the used region can be changed using various
  28. * buffer commands. Initially, the used region is empty.
  29. *
  30. * The used region is further subdivided into two disjoint regions: the
  31. * 'consumed region' and the 'remaining region'. The union of these two
  32. * regions is the used region. The consumed region extends from the beginning
  33. * of the used region to the byte before the 'current' offset (if any). The
  34. * 'remaining' region the current pointer to the end of the used
  35. * region. The size of the consumed region can be changed using various
  36. * buffer commands. Initially, the consumed region is empty.
  37. *
  38. * The 'active region' is an (optional) subregion of the remaining region.
  39. * It extends from the current offset to an offset in the remaining region
  40. * that is selected with lwres_buffer_setactive(). Initially, the active
  41. * region is empty. If the current offset advances beyond the chosen offset,
  42. * the active region will also be empty.
  43. *
  44. * \verbatim
  45. * /----- used region -----\/-- available --\
  46. * +----------------------------------------+
  47. * | consumed | remaining | |
  48. * +----------------------------------------+
  49. * a b c d e
  50. *
  51. * a == base of buffer.
  52. * b == current pointer. Can be anywhere between a and d.
  53. * c == active pointer. Meaningful between b and d.
  54. * d == used pointer.
  55. * e == length of buffer.
  56. *
  57. * a-e == entire (length) of buffer.
  58. * a-d == used region.
  59. * a-b == consumed region.
  60. * b-d == remaining region.
  61. * b-c == optional active region.
  62. * \endverbatim
  63. *
  64. * The following invariants are maintained by all routines:
  65. *
  66. *\verbatim
  67. * length > 0
  68. *
  69. * base is a valid pointer to length bytes of memory
  70. *
  71. * 0 <= used <= length
  72. *
  73. * 0 <= current <= used
  74. *
  75. * 0 <= active <= used
  76. * (although active < current implies empty active region)
  77. *\endverbatim
  78. *
  79. * \li MP:
  80. * Buffers have no synchronization. Clients must ensure exclusive
  81. * access.
  82. *
  83. * \li Reliability:
  84. * No anticipated impact.
  85. *
  86. * \li Resources:
  87. * Memory: 1 pointer + 6 unsigned integers per buffer.
  88. *
  89. * \li Security:
  90. * No anticipated impact.
  91. *
  92. * \li Standards:
  93. * None.
  94. */
  95. #ifndef LWRES_LWBUFFER_H
  96. #define LWRES_LWBUFFER_H 1
  97. /***
  98. *** Imports
  99. ***/
  100. #include <lwres/lang.h>
  101. #include <lwres/int.h>
  102. LWRES_LANG_BEGINDECLS
  103. /***
  104. *** Magic numbers
  105. ***/
  106. #define LWRES_BUFFER_MAGIC 0x4275663fU /* Buf?. */
  107. #define LWRES_BUFFER_VALID(b) ((b) != NULL && \
  108. (b)->magic == LWRES_BUFFER_MAGIC)
  109. /*!
  110. * The following macros MUST be used only on valid buffers. It is the
  111. * caller's responsibility to ensure this by using the LWRES_BUFFER_VALID
  112. * check above, or by calling another lwres_buffer_*() function (rather than
  113. * another macro.)
  114. */
  115. /*!
  116. * Get the length of the used region of buffer "b"
  117. */
  118. #define LWRES_BUFFER_USEDCOUNT(b) ((b)->used)
  119. /*!
  120. * Get the length of the available region of buffer "b"
  121. */
  122. #define LWRES_BUFFER_AVAILABLECOUNT(b) ((b)->length - (b)->used)
  123. #define LWRES_BUFFER_REMAINING(b) ((b)->used - (b)->current)
  124. /*!
  125. * Note that the buffer structure is public. This is principally so buffer
  126. * operations can be implemented using macros. Applications are strongly
  127. * discouraged from directly manipulating the structure.
  128. */
  129. typedef struct lwres_buffer lwres_buffer_t;
  130. /*!
  131. * Buffer data structure
  132. */
  133. struct lwres_buffer {
  134. unsigned int magic;
  135. unsigned char *base;
  136. /* The following integers are byte offsets from 'base'. */
  137. unsigned int length;
  138. unsigned int used;
  139. unsigned int current;
  140. unsigned int active;
  141. };
  142. /***
  143. *** Functions
  144. ***/
  145. void
  146. lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length);
  147. /**<
  148. * Make 'b' refer to the 'length'-byte region starting at base.
  149. *
  150. * Requires:
  151. *
  152. * 'length' > 0
  153. *
  154. * 'base' is a pointer to a sequence of 'length' bytes.
  155. *
  156. */
  157. void
  158. lwres_buffer_invalidate(lwres_buffer_t *b);
  159. /**<
  160. * Make 'b' an invalid buffer.
  161. *
  162. * Requires:
  163. * 'b' is a valid buffer.
  164. *
  165. * Ensures:
  166. * If assertion checking is enabled, future attempts to use 'b' without
  167. * calling lwres_buffer_init() on it will cause an assertion failure.
  168. */
  169. void
  170. lwres_buffer_add(lwres_buffer_t *b, unsigned int n);
  171. /**<
  172. * Increase the 'used' region of 'b' by 'n' bytes.
  173. *
  174. * Requires:
  175. *
  176. * 'b' is a valid buffer
  177. *
  178. * used + n <= length
  179. *
  180. */
  181. void
  182. lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n);
  183. /**<
  184. * Decrease the 'used' region of 'b' by 'n' bytes.
  185. *
  186. * Requires:
  187. *
  188. * 'b' is a valid buffer
  189. *
  190. * used >= n
  191. *
  192. */
  193. void
  194. lwres_buffer_clear(lwres_buffer_t *b);
  195. /**<
  196. * Make the used region empty.
  197. *
  198. * Requires:
  199. *
  200. * 'b' is a valid buffer
  201. *
  202. * Ensures:
  203. *
  204. * used = 0
  205. *
  206. */
  207. void
  208. lwres_buffer_first(lwres_buffer_t *b);
  209. /**<
  210. * Make the consumed region empty.
  211. *
  212. * Requires:
  213. *
  214. * 'b' is a valid buffer
  215. *
  216. * Ensures:
  217. *
  218. * current == 0
  219. *
  220. */
  221. void
  222. lwres_buffer_forward(lwres_buffer_t *b, unsigned int n);
  223. /**<
  224. * Increase the 'consumed' region of 'b' by 'n' bytes.
  225. *
  226. * Requires:
  227. *
  228. * 'b' is a valid buffer
  229. *
  230. * current + n <= used
  231. *
  232. */
  233. void
  234. lwres_buffer_back(lwres_buffer_t *b, unsigned int n);
  235. /**<
  236. * Decrease the 'consumed' region of 'b' by 'n' bytes.
  237. *
  238. * Requires:
  239. *
  240. * 'b' is a valid buffer
  241. *
  242. * n <= current
  243. *
  244. */
  245. lwres_uint8_t
  246. lwres_buffer_getuint8(lwres_buffer_t *b);
  247. /**<
  248. * Read an unsigned 8-bit integer from 'b' and return it.
  249. *
  250. * Requires:
  251. *
  252. * 'b' is a valid buffer.
  253. *
  254. * The length of the available region of 'b' is at least 1.
  255. *
  256. * Ensures:
  257. *
  258. * The current pointer in 'b' is advanced by 1.
  259. *
  260. * Returns:
  261. *
  262. * A 8-bit unsigned integer.
  263. */
  264. void
  265. lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val);
  266. /**<
  267. * Store an unsigned 8-bit integer from 'val' into 'b'.
  268. *
  269. * Requires:
  270. * 'b' is a valid buffer.
  271. *
  272. * The length of the unused region of 'b' is at least 1.
  273. *
  274. * Ensures:
  275. * The used pointer in 'b' is advanced by 1.
  276. */
  277. lwres_uint16_t
  278. lwres_buffer_getuint16(lwres_buffer_t *b);
  279. /**<
  280. * Read an unsigned 16-bit integer in network byte order from 'b', convert
  281. * it to host byte order, and return it.
  282. *
  283. * Requires:
  284. *
  285. * 'b' is a valid buffer.
  286. *
  287. * The length of the available region of 'b' is at least 2.
  288. *
  289. * Ensures:
  290. *
  291. * The current pointer in 'b' is advanced by 2.
  292. *
  293. * Returns:
  294. *
  295. * A 16-bit unsigned integer.
  296. */
  297. void
  298. lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val);
  299. /**<
  300. * Store an unsigned 16-bit integer in host byte order from 'val'
  301. * into 'b' in network byte order.
  302. *
  303. * Requires:
  304. * 'b' is a valid buffer.
  305. *
  306. * The length of the unused region of 'b' is at least 2.
  307. *
  308. * Ensures:
  309. * The used pointer in 'b' is advanced by 2.
  310. */
  311. lwres_uint32_t
  312. lwres_buffer_getuint32(lwres_buffer_t *b);
  313. /**<
  314. * Read an unsigned 32-bit integer in network byte order from 'b', convert
  315. * it to host byte order, and return it.
  316. *
  317. * Requires:
  318. *
  319. * 'b' is a valid buffer.
  320. *
  321. * The length of the available region of 'b' is at least 2.
  322. *
  323. * Ensures:
  324. *
  325. * The current pointer in 'b' is advanced by 2.
  326. *
  327. * Returns:
  328. *
  329. * A 32-bit unsigned integer.
  330. */
  331. void
  332. lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val);
  333. /**<
  334. * Store an unsigned 32-bit integer in host byte order from 'val'
  335. * into 'b' in network byte order.
  336. *
  337. * Requires:
  338. * 'b' is a valid buffer.
  339. *
  340. * The length of the unused region of 'b' is at least 4.
  341. *
  342. * Ensures:
  343. * The used pointer in 'b' is advanced by 4.
  344. */
  345. void
  346. lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base,
  347. unsigned int length);
  348. /**<
  349. * Copy 'length' bytes of memory at 'base' into 'b'.
  350. *
  351. * Requires:
  352. * 'b' is a valid buffer.
  353. *
  354. * 'base' points to 'length' bytes of valid memory.
  355. *
  356. */
  357. void
  358. lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base,
  359. unsigned int length);
  360. /**<
  361. * Copy 'length' bytes of memory from 'b' into 'base'.
  362. *
  363. * Requires:
  364. * 'b' is a valid buffer.
  365. *
  366. * 'base' points to at least 'length' bytes of valid memory.
  367. *
  368. * 'b' have at least 'length' bytes remaining.
  369. */
  370. LWRES_LANG_ENDDECLS
  371. #endif /* LWRES_LWBUFFER_H */