/contrib/bind9/lib/dns/include/dns/dbiterator.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 297 lines · 51 code · 23 blank · 223 comment · 0 complexity · ebb17eb3dc4567cc438ccc3dd22d7654 MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 1999-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: dbiterator.h,v 1.25 2007/06/19 23:47:16 tbox Exp $ */
  18. #ifndef DNS_DBITERATOR_H
  19. #define DNS_DBITERATOR_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/dbiterator.h
  24. * \brief
  25. * The DNS DB Iterator interface allows iteration of all of the nodes in a
  26. * database.
  27. *
  28. * The dns_dbiterator_t type is like a "virtual class". To actually use
  29. * it, an implementation of the class is required. This implementation is
  30. * supplied by the database.
  31. *
  32. * It is the client's responsibility to call dns_db_detachnode() on all
  33. * nodes returned.
  34. *
  35. * XXX <more> XXX
  36. *
  37. * MP:
  38. *\li The iterator itself is not locked. The caller must ensure
  39. * synchronization.
  40. *
  41. *\li The iterator methods ensure appropriate database locking.
  42. *
  43. * Reliability:
  44. *\li No anticipated impact.
  45. *
  46. * Resources:
  47. *\li TBS
  48. *
  49. * Security:
  50. *\li No anticipated impact.
  51. *
  52. * Standards:
  53. *\li None.
  54. */
  55. /*****
  56. ***** Imports
  57. *****/
  58. #include <isc/lang.h>
  59. #include <isc/magic.h>
  60. #include <dns/types.h>
  61. ISC_LANG_BEGINDECLS
  62. /*****
  63. ***** Types
  64. *****/
  65. typedef struct dns_dbiteratormethods {
  66. void (*destroy)(dns_dbiterator_t **iteratorp);
  67. isc_result_t (*first)(dns_dbiterator_t *iterator);
  68. isc_result_t (*last)(dns_dbiterator_t *iterator);
  69. isc_result_t (*seek)(dns_dbiterator_t *iterator, dns_name_t *name);
  70. isc_result_t (*prev)(dns_dbiterator_t *iterator);
  71. isc_result_t (*next)(dns_dbiterator_t *iterator);
  72. isc_result_t (*current)(dns_dbiterator_t *iterator,
  73. dns_dbnode_t **nodep, dns_name_t *name);
  74. isc_result_t (*pause)(dns_dbiterator_t *iterator);
  75. isc_result_t (*origin)(dns_dbiterator_t *iterator,
  76. dns_name_t *name);
  77. } dns_dbiteratormethods_t;
  78. #define DNS_DBITERATOR_MAGIC ISC_MAGIC('D','N','S','I')
  79. #define DNS_DBITERATOR_VALID(dbi) ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC)
  80. /*%
  81. * This structure is actually just the common prefix of a DNS db
  82. * implementation's version of a dns_dbiterator_t.
  83. *
  84. * Clients may use the 'db' field of this structure. Except for that field,
  85. * direct use of this structure by clients is forbidden. DB implementations
  86. * may change the structure. 'magic' must be DNS_DBITERATOR_MAGIC for any of
  87. * the dns_dbiterator routines to work. DB iterator implementations must
  88. * maintain all DB iterator invariants.
  89. */
  90. struct dns_dbiterator {
  91. /* Unlocked. */
  92. unsigned int magic;
  93. dns_dbiteratormethods_t * methods;
  94. dns_db_t * db;
  95. isc_boolean_t relative_names;
  96. isc_boolean_t cleaning;
  97. };
  98. void
  99. dns_dbiterator_destroy(dns_dbiterator_t **iteratorp);
  100. /*%<
  101. * Destroy '*iteratorp'.
  102. *
  103. * Requires:
  104. *
  105. *\li '*iteratorp' is a valid iterator.
  106. *
  107. * Ensures:
  108. *
  109. *\li All resources used by the iterator are freed.
  110. *
  111. *\li *iteratorp == NULL.
  112. */
  113. isc_result_t
  114. dns_dbiterator_first(dns_dbiterator_t *iterator);
  115. /*%<
  116. * Move the node cursor to the first node in the database (if any).
  117. *
  118. * Requires:
  119. *\li 'iterator' is a valid iterator.
  120. *
  121. * Returns:
  122. *\li #ISC_R_SUCCESS
  123. *\li #ISC_R_NOMORE There are no nodes in the database.
  124. *
  125. *\li Other results are possible, depending on the DB implementation.
  126. */
  127. isc_result_t
  128. dns_dbiterator_last(dns_dbiterator_t *iterator);
  129. /*%<
  130. * Move the node cursor to the last node in the database (if any).
  131. *
  132. * Requires:
  133. *\li 'iterator' is a valid iterator.
  134. *
  135. * Returns:
  136. *\li #ISC_R_SUCCESS
  137. *\li #ISC_R_NOMORE There are no nodes in the database.
  138. *
  139. *\li Other results are possible, depending on the DB implementation.
  140. */
  141. isc_result_t
  142. dns_dbiterator_seek(dns_dbiterator_t *iterator, dns_name_t *name);
  143. /*%<
  144. * Move the node cursor to the node with name 'name'.
  145. *
  146. * Requires:
  147. *\li 'iterator' is a valid iterator.
  148. *
  149. *\li 'name' is a valid name.
  150. *
  151. * Returns:
  152. *\li #ISC_R_SUCCESS
  153. *\li #ISC_R_NOTFOUND
  154. *
  155. *\li Other results are possible, depending on the DB implementation.
  156. */
  157. isc_result_t
  158. dns_dbiterator_prev(dns_dbiterator_t *iterator);
  159. /*%<
  160. * Move the node cursor to the previous node in the database (if any).
  161. *
  162. * Requires:
  163. *\li 'iterator' is a valid iterator.
  164. *
  165. * Returns:
  166. *\li #ISC_R_SUCCESS
  167. *\li #ISC_R_NOMORE There are no more nodes in the
  168. * database.
  169. *
  170. *\li Other results are possible, depending on the DB implementation.
  171. */
  172. isc_result_t
  173. dns_dbiterator_next(dns_dbiterator_t *iterator);
  174. /*%<
  175. * Move the node cursor to the next node in the database (if any).
  176. *
  177. * Requires:
  178. *\li 'iterator' is a valid iterator.
  179. *
  180. * Returns:
  181. *\li #ISC_R_SUCCESS
  182. *\li #ISC_R_NOMORE There are no more nodes in the
  183. * database.
  184. *
  185. *\li Other results are possible, depending on the DB implementation.
  186. */
  187. isc_result_t
  188. dns_dbiterator_current(dns_dbiterator_t *iterator, dns_dbnode_t **nodep,
  189. dns_name_t *name);
  190. /*%<
  191. * Return the current node.
  192. *
  193. * Notes:
  194. *\li If 'name' is not NULL, it will be set to the name of the node.
  195. *
  196. * Requires:
  197. *\li 'iterator' is a valid iterator.
  198. *
  199. *\li nodep != NULL && *nodep == NULL
  200. *
  201. *\li The node cursor of 'iterator' is at a valid location (i.e. the
  202. * result of last call to a cursor movement command was ISC_R_SUCCESS).
  203. *
  204. *\li 'name' is NULL, or is a valid name with a dedicated buffer.
  205. *
  206. * Returns:
  207. *
  208. *\li #ISC_R_SUCCESS
  209. *\li #DNS_R_NEWORIGIN If this iterator was created with
  210. * 'relative_names' set to ISC_TRUE,
  211. * then #DNS_R_NEWORIGIN will be returned
  212. * when the origin the names are
  213. * relative to changes. This result
  214. * can occur only when 'name' is not
  215. * NULL. This is also a successful
  216. * result.
  217. *
  218. *\li Other results are possible, depending on the DB implementation.
  219. */
  220. isc_result_t
  221. dns_dbiterator_pause(dns_dbiterator_t *iterator);
  222. /*%<
  223. * Pause iteration.
  224. *
  225. * Calling a cursor movement method or dns_dbiterator_current() may cause
  226. * database locks to be acquired. Rather than reacquire these locks every
  227. * time one of these routines is called, the locks may simply be held.
  228. * Calling dns_dbiterator_pause() releases any such locks. Iterator clients
  229. * should call this routine any time they are not going to execute another
  230. * iterator method in the immediate future.
  231. *
  232. * Requires:
  233. *\li 'iterator' is a valid iterator.
  234. *
  235. * Ensures:
  236. *\li Any database locks being held for efficiency of iterator access are
  237. * released.
  238. *
  239. * Returns:
  240. *\li #ISC_R_SUCCESS
  241. *
  242. *\li Other results are possible, depending on the DB implementation.
  243. */
  244. isc_result_t
  245. dns_dbiterator_origin(dns_dbiterator_t *iterator, dns_name_t *name);
  246. /*%<
  247. * Return the origin to which returned node names are relative.
  248. *
  249. * Requires:
  250. *
  251. *\li 'iterator' is a valid relative_names iterator.
  252. *
  253. *\li 'name' is a valid name with a dedicated buffer.
  254. *
  255. * Returns:
  256. *
  257. *\li #ISC_R_SUCCESS
  258. *\li #ISC_R_NOSPACE
  259. *
  260. *\li Other results are possible, depending on the DB implementation.
  261. */
  262. void
  263. dns_dbiterator_setcleanmode(dns_dbiterator_t *iterator, isc_boolean_t mode);
  264. /*%<
  265. * Indicate that the given iterator is/is not cleaning the DB.
  266. *
  267. * Notes:
  268. *\li When 'mode' is ISC_TRUE,
  269. *
  270. * Requires:
  271. *\li 'iterator' is a valid iterator.
  272. */
  273. ISC_LANG_ENDDECLS
  274. #endif /* DNS_DBITERATOR_H */