home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / dns / rdatasetiter.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  4.3 KB  |  171 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 1999-2001  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and 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.  
  18. /* $Id: rdatasetiter.h,v 1.15.18.2 2005/04/29 00:16:19 marka Exp $ */
  19.  
  20. #ifndef DNS_RDATASETITER_H
  21. #define DNS_RDATASETITER_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  * \brief
  29.  * The DNS Rdataset Iterator interface allows iteration of all of the
  30.  * rdatasets at a node.
  31.  *
  32.  * The dns_rdatasetiter_t type is like a "virtual class".  To actually use
  33.  * it, an implementation of the class is required.  This implementation is
  34.  * supplied by the database.
  35.  *
  36.  * It is the client's responsibility to call dns_rdataset_disassociate()
  37.  * on all rdatasets returned.
  38.  *
  39.  * XXX more XXX
  40.  *
  41.  * MP:
  42.  *\li    The iterator itself is not locked.  The caller must ensure
  43.  *    synchronization.
  44.  *
  45.  *\li    The iterator methods ensure appropriate database locking.
  46.  *
  47.  * Reliability:
  48.  *\li    No anticipated impact.
  49.  *
  50.  * Resources:
  51.  *\li    TBS
  52.  *
  53.  * Security:
  54.  *\li    No anticipated impact.
  55.  *
  56.  * Standards:
  57.  *\li    None.
  58.  */
  59.  
  60. /*****
  61.  ***** Imports
  62.  *****/
  63.  
  64. #include <isc/lang.h>
  65. #include <isc/magic.h>
  66. #include <isc/stdtime.h>
  67.  
  68. #include <dns/types.h>
  69.  
  70. ISC_LANG_BEGINDECLS
  71.  
  72. /*****
  73.  ***** Types
  74.  *****/
  75.  
  76. typedef struct dns_rdatasetitermethods {
  77.     void        (*destroy)(dns_rdatasetiter_t **iteratorp);
  78.     isc_result_t    (*first)(dns_rdatasetiter_t *iterator);
  79.     isc_result_t    (*next)(dns_rdatasetiter_t *iterator);
  80.     void        (*current)(dns_rdatasetiter_t *iterator,
  81.                    dns_rdataset_t *rdataset);
  82. } dns_rdatasetitermethods_t;
  83.  
  84. #define DNS_RDATASETITER_MAGIC         ISC_MAGIC('D','N','S','i')
  85. #define DNS_RDATASETITER_VALID(i)    ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC)
  86.  
  87. /*%
  88.  * This structure is actually just the common prefix of a DNS db
  89.  * implementation's version of a dns_rdatasetiter_t.
  90.  * \brief
  91.  * Direct use of this structure by clients is forbidden.  DB implementations
  92.  * may change the structure.  'magic' must be #DNS_RDATASETITER_MAGIC for
  93.  * any of the dns_rdatasetiter routines to work.  DB implementations must
  94.  * maintain all DB rdataset iterator invariants.
  95.  */
  96. struct dns_rdatasetiter {
  97.     /* Unlocked. */
  98.     unsigned int            magic;
  99.     dns_rdatasetitermethods_t *    methods;
  100.     dns_db_t *            db;
  101.     dns_dbnode_t *            node;
  102.     dns_dbversion_t *        version;
  103.     isc_stdtime_t            now;
  104. };
  105.  
  106. void
  107. dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp);
  108. /*%<
  109.  * Destroy '*iteratorp'.
  110.  *
  111.  * Requires:
  112.  *
  113.  *\li    '*iteratorp' is a valid iterator.
  114.  *
  115.  * Ensures:
  116.  *
  117.  *\li    All resources used by the iterator are freed.
  118.  *
  119.  *\li    *iteratorp == NULL.
  120.  */
  121.  
  122. isc_result_t
  123. dns_rdatasetiter_first(dns_rdatasetiter_t *iterator);
  124. /*%<
  125.  * Move the rdataset cursor to the first rdataset at the node (if any).
  126.  *
  127.  * Requires:
  128.  *\li    'iterator' is a valid iterator.
  129.  *
  130.  * Returns:
  131.  *\li    ISC_R_SUCCESS
  132.  *\li    ISC_R_NOMORE            There are no rdatasets at the node.
  133.  *
  134.  *\li    Other results are possible, depending on the DB implementation.
  135.  */
  136.  
  137. isc_result_t
  138. dns_rdatasetiter_next(dns_rdatasetiter_t *iterator);
  139. /*%<
  140.  * Move the rdataset cursor to the next rdataset at the node (if any).
  141.  *
  142.  * Requires:
  143.  *\li    'iterator' is a valid iterator.
  144.  *
  145.  * Returns:
  146.  *\li    ISC_R_SUCCESS
  147.  *\li    ISC_R_NOMORE            There are no more rdatasets at the
  148.  *                    node.
  149.  *
  150.  *\li    Other results are possible, depending on the DB implementation.
  151.  */
  152.  
  153. void
  154. dns_rdatasetiter_current(dns_rdatasetiter_t *iterator,
  155.              dns_rdataset_t *rdataset);
  156. /*%<
  157.  * Return the current rdataset.
  158.  *
  159.  * Requires:
  160.  *\li    'iterator' is a valid iterator.
  161.  *
  162.  *\li    'rdataset' is a valid, disassociated rdataset.
  163.  *
  164.  *\li    The rdataset cursor of 'iterator' is at a valid location (i.e. the
  165.  *    result of last call to a cursor movement command was #ISC_R_SUCCESS).
  166.  */
  167.  
  168. ISC_LANG_ENDDECLS
  169.  
  170. #endif /* DNS_RDATASETITER_H */
  171.