Initial vendor import of ldns-1.6.4 into contrib.
[dragonfly.git] / contrib / ldns / ldns / zone.h
1 /**
2  * zone.h
3  *
4  * zone definitions
5  *  - what is it
6  *  - get_glue function
7  *  - search etc
8  *
9  * a Net::DNS like library for C
10  *
11  * (c) NLnet Labs, 2005-2006
12  *
13  * See the file LICENSE for the license
14  */
15
16 /**
17  * \file
18  *
19  * Defines the ldns_zone structure and functions to manipulate it.
20  */
21  
22
23 #ifndef LDNS_ZONE_H
24 #define LDNS_ZONE_H
25
26 #include <ldns/common.h>
27 #include <ldns/rdata.h>
28 #include <ldns/rr.h>
29 #include <ldns/error.h>
30
31 /** 
32  * DNS Zone
33  *
34  * A list of RR's with some
35  * extra information which comes from the SOA RR
36  * Note: nothing has been done to make this efficient (yet).
37  */
38 struct ldns_struct_zone
39 {
40         /** the soa defines a zone */
41         ldns_rr         *_soa;
42         /* basicly a zone is a list of rr's */
43         ldns_rr_list    *_rrs;
44         /* we could change this to be a b-tree etc etc todo */
45 };
46 typedef struct ldns_struct_zone ldns_zone;      
47         
48 /**
49  * create a new ldns_zone structure
50  * \return a pointer to a ldns_zone structure
51  */
52 ldns_zone * ldns_zone_new(void);
53
54 /**
55  * Return the soa record of a zone
56  * \param[in] z the zone to read from
57  * \return the soa record in the zone
58  */
59 ldns_rr * ldns_zone_soa(const ldns_zone *z);
60
61 /**
62  * Returns the number of resource records in the zone, NOT counting the SOA record
63  * \param[in] z the zone to read from
64  * \return the number of rr's in the zone
65  */
66 size_t ldns_zone_rr_count(const ldns_zone *z);
67
68 /**
69  * Set the zone's soa record
70  * \param[in] z the zone to put the new soa in
71  * \param[in] soa the soa to set
72  */
73 void ldns_zone_set_soa(ldns_zone *z, ldns_rr *soa);
74
75 /**
76  * Get a list of a zone's content. Note that the SOA
77  * isn't included in this list. You need to get the 
78  * with ldns_zone_soa.
79  * \param[in] z the zone to read from
80  * \return the rrs from this zone
81  */
82 ldns_rr_list * ldns_zone_rrs(const ldns_zone *z);
83
84 /**
85  * Set the zone's contents
86  * \param[in] z the zone to put the new soa in
87  * \param[in] rrlist the rrlist to use
88  */
89 void ldns_zone_set_rrs(ldns_zone *z, ldns_rr_list *rrlist);
90
91 /**
92  * push an rrlist to a zone structure. This function use pointer
93  * copying, so the rr_list structure inside z is modified!
94  * \param[in] z the zone to add to
95  * \param[in] list the list to add
96  * \return a true on succes otherwise falsed
97  */
98 bool ldns_zone_push_rr_list(ldns_zone *z, ldns_rr_list *list);
99
100 /**
101  * push an single rr to a zone structure. This function use pointer
102  * copying, so the rr_list structure inside z is modified!
103  * \param[in] z the zone to add to
104  * \param[in] rr the rr to add
105  * \return a true on succes otherwise falsed
106  */
107 bool ldns_zone_push_rr(ldns_zone *z, ldns_rr *rr);
108
109 /**
110  * Retrieve all resource records from the zone that are glue
111  * records. The resulting list does are pointer references
112  * to the zone's data.
113  *
114  * Due to the current zone implementation (as a list of rr's), this
115  * function is extremely slow. Another (probably better) way to do this
116  * is to use an ldns_dnssec_zone structure and the mark_glue function 
117  *
118  * \param[in] z the zone to look for glue
119  * \return the rr_list with the glue
120  */
121 ldns_rr_list *ldns_zone_glue_rr_list(const ldns_zone *z);
122
123 /**
124  * Create a new zone from a file
125  * \param[out] z the new zone
126  * \param[in] *fp the filepointer to use
127  * \param[in] *origin the zones' origin
128  * \param[in] ttl default ttl to use
129  * \param[in] c default class to use (IN)
130  *
131  * \return ldns_status mesg with an error or LDNS_STATUS_OK
132  */
133 ldns_status ldns_zone_new_frm_fp(ldns_zone **z, FILE *fp, ldns_rdf *origin, uint32_t ttl, ldns_rr_class c);
134
135 /**
136  * Create a new zone from a file, keep track of the line numbering
137  * \param[out] z the new zone
138  * \param[in] *fp the filepointer to use
139  * \param[in] *origin the zones' origin
140  * \param[in] ttl default ttl to use
141  * \param[in] c default class to use (IN)
142  * \param[out] line_nr used for error msg, to get to the line number
143  *
144  * \return ldns_status mesg with an error or LDNS_STATUS_OK
145  */
146 ldns_status ldns_zone_new_frm_fp_l(ldns_zone **z, FILE *fp, ldns_rdf *origin, uint32_t ttl, ldns_rr_class c, int *line_nr);
147
148 /**
149  * Frees the allocated memory for the zone, and the rr_list structure in it
150  * \param[in] zone the zone to free
151  */
152 void ldns_zone_free(ldns_zone *zone);
153
154 /**
155  * Frees the allocated memory for the zone, the soa rr in it, 
156  * and the rr_list structure in it, including the rr's in that. etc.
157  * \param[in] zone the zone to free
158  */
159 void ldns_zone_deep_free(ldns_zone *zone);
160
161 /**
162  * Sort the rrs in a zone, with the current impl. this is slow
163  * \param[in] zone the zone to sort
164  */
165 void ldns_zone_sort(ldns_zone *zone);
166
167 #endif /* LDNS_ZONE_H */