Update to ldns-1.6.7
[dragonfly.git] / contrib / ldns / ldns / dname.h
CommitLineData
825eb42b
JL
1/*
2 * dname.h
3 *
4 * dname definitions
5 *
6 * a Net::DNS like library for C
7 *
8 * (c) NLnet Labs, 2004-2006
9 *
10 * See the file LICENSE for the license
11 */
12
13/**
14 * \file dname.h
15 *
16 * dname contains function to read and manipulate domain names.
17 *
18 * Example domain names are "www.nlnetlabs.nl." and "." (the root)
19 *
20 * If a domain name ends with a dot ("."), it is called a Fully Qualified
21 * Domain Name (FQDN). In certain places (for instance when reading a zone
22 * file), an origin (which is just another domain name) non-FQDNs will be
23 * placed after the current. For instance, if i have a zone file where the
24 * origin has been set to "nl.", and my file contains the name
25 * "www.nlnetlabs", it will result in "www.nlnetlabs.nl.". Internally, dnames are
26 * always absolute (the dot is added when it is missing and there is no origin).
27 *
28 * An FQDN is also
29 * known as an absolute domain name, therefore the function to check this is
30 * called \ref ldns_dname_str_absolute
31 *
32 * Domain names are stored in \ref ldns_rdf structures, with the type
33 * \ref LDNS_RDF_TYPE_DNAME
ac996e71 34 *
825eb42b
JL
35 * This module is *NOT* about the RR type called DNAME.
36 */
37
38
39#ifndef LDNS_DNAME_H
40#define LDNS_DNAME_H
41
42#include <ldns/common.h>
43#include <ldns/rdata.h>
44
ac996e71
JL
45#ifdef __cplusplus
46extern "C" {
47#endif
48
825eb42b
JL
49#define LDNS_DNAME_NORMALIZE tolower
50
51/**
52 * concatenates two dnames together
53 * \param[in] rd1 the leftside
54 * \param[in] rd2 the rightside
55 * \return a new rdf with leftside/rightside
56 */
57ldns_rdf *ldns_dname_cat_clone(const ldns_rdf *rd1, const ldns_rdf *rd2);
58
59/**
60 * concatenates rd2 after rd1 (rd2 is copied, rd1 is modified)
61 * \param[in] rd1 the leftside
62 * \param[in] rd2 the rightside
63 * \return LDNS_STATUS_OK on success
64 */
65ldns_status ldns_dname_cat(ldns_rdf *rd1, ldns_rdf *rd2);
66
67/**
68 * Returns a clone of the given dname with the labels
69 * reversed
70 * \param[in] d the dname to reverse
71 * \return clone of the dname with the labels reversed.
72 */
73ldns_rdf *ldns_dname_reverse(const ldns_rdf *d);
74
75/**
76 * Clones the given dname from the nth label on
77 * \param[in] d The dname to clone
78 * \param[in] n the label nr to clone from, if this is 0, the complete
79 * dname is cloned
80 * \return A newly allocated *rdf structure, containing the cloned dname,
ac996e71 81 * or NULL if either d was NULL, not a dname, or if n >=
825eb42b
JL
82 * label_count
83 */
84ldns_rdf *
85ldns_dname_clone_from(const ldns_rdf *d, uint16_t n);
86
87/**
ac996e71 88 * chop one label off the left side of a dname. so
825eb42b
JL
89 * wwww.nlnetlabs.nl, becomes nlnetlabs.nl
90 * This new name is a clone and must be freed with ldns_deep_free()
91 * \param[in] d the dname to chop
92 * \return the remaining dname
93 */
94ldns_rdf *ldns_dname_left_chop(const ldns_rdf *d);
95
96/**
97 * count the number of labels inside a LDNS_RDF_DNAME type rdf.
98 * \param[in] *r the rdf
99 * \return the number of labels
ac996e71 100 */
825eb42b
JL
101uint8_t ldns_dname_label_count(const ldns_rdf *r);
102
103/**
104 * creates a new dname rdf from a string.
105 * \param[in] str string to use
106 * \return ldns_rdf* or NULL in case of an error
107 */
108ldns_rdf *ldns_dname_new_frm_str(const char *str);
109
110/**
111 * Create a new dname rdf from a string
ac996e71 112 * \param[in] s the size of the new dname
825eb42b
JL
113 * \param[in] *data pointer to the actual data
114 * \return ldns_rdf*
115 */
116ldns_rdf *ldns_dname_new(uint16_t s, void *data);
117
118/**
119 * Create a new dname rdf from data (the data is copied)
120 * \param[in] size the size of the data
121 * \param[in] *data pointer to the actual data
122 * \return ldns_rdf*
123 */
124ldns_rdf *ldns_dname_new_frm_data(uint16_t size, const void *data);
125
126/**
127 * Put a dname into canonical fmt - ie. lowercase it
128 * \param[in] rdf the dname to lowercase
129 * \return void
130 */
131void ldns_dname2canonical(const ldns_rdf *rdf);
132
133/**
134 * test wether the name sub falls under parent (i.e. is a subdomain
135 * of parent). This function will return false if the given dnames are
136 * equal.
137 * \param[in] sub the name to test
138 * \param[in] parent the parent's name
139 * \return true if sub falls under parent, otherwise false
140 */
141bool ldns_dname_is_subdomain(const ldns_rdf *sub, const ldns_rdf *parent);
142
143/**
144 * Compares the two dname rdf's according to the algorithm for ordering
145 * in RFC4034 Section 6.
146 * \param[in] dname1 First dname rdf to compare
147 * \param[in] dname2 Second dname rdf to compare
148 * \return -1 if dname1 comes before dname2, 1 if dname1 comes after dname2, and 0 if they are equal.
149 */
150int ldns_dname_compare(const ldns_rdf *dname1, const ldns_rdf *dname2);
151
152/**
153 * Checks whether the dname matches the given wildcard
154 * \param[in] dname The dname to check
155 * \param[in] wildcard The wildcard to check with
156 * \return 1 If the wildcard matches, OR if 'wildcard' is not a wildcard and
157 * the names are *exactly* the same
158 * 0 If the wildcard does not match, or if it is not a wildcard and
159 * the names are not the same
160 */
161int ldns_dname_match_wildcard(const ldns_rdf *dname, const ldns_rdf *wildcard);
162
163/**
164 * check if middle lays in the interval defined by prev and next
165 * prev <= middle < next. This is usefull for nsec checking
166 * \param[in] prev the previous dname
167 * \param[in] middle the dname to check
168 * \param[in] next the next dname
169 * return 0 on error or unknown, -1 when middle is in the interval, +1 when not
170 */
171int ldns_dname_interval(const ldns_rdf *prev, const ldns_rdf *middle, const ldns_rdf *next);
172
173/**
174 * Checks whether the given dname string is absolute (i.e. ends with a '.')
175 * \param[in] *dname_str a string representing the dname
176 * \return true or false
177 */
178bool ldns_dname_str_absolute(const char *dname_str);
179
180/**
181 * look inside the rdf and if it is an LDNS_RDF_TYPE_DNAME
182 * try and retrieve a specific label. The labels are numbered
183 * starting from 0 (left most).
184 * \param[in] rdf the rdf to look in
185 * \param[in] labelpos return the label with this number
186 * \return a ldns_rdf* with the label as name or NULL on error
187 */
188ldns_rdf * ldns_dname_label(const ldns_rdf *rdf, uint8_t labelpos);
189
ac996e71
JL
190/**
191 * Check if dname is a wildcard, starts with *.
192 * \param[in] dname: the rdf to look in
193 * \return true if a wildcard, false if not.
194 */
195int ldns_dname_is_wildcard(const ldns_rdf* dname);
196
197#ifdef __cplusplus
198}
199#endif
200
825eb42b 201#endif /* LDNS_DNAME_H */