dname.h 5.25 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
/*!
 * \file dname.h
 * \author Lubos Slovak <lubos.slovak@nic.cz>
 *
 * \brief Domain name structure and API for manipulating it.
 *
 * \addtogroup dnslib
 * @{
 */

Jan Kadlec's avatar
Jan Kadlec committed
11 12
#ifndef _CUTEDNS_DNSLIB_DNAME_H_
#define _CUTEDNS_DNSLIB_DNAME_H_
Lubos Slovak's avatar
Lubos Slovak committed
13 14

#include <stdint.h>
Lubos Slovak's avatar
Lubos Slovak committed
15

Lubos Slovak's avatar
Lubos Slovak committed
16
#include "common.h"
17 18

struct dnslib_node;
Lubos Slovak's avatar
Lubos Slovak committed
19

20
/*----------------------------------------------------------------------------*/
21 22 23 24 25 26 27
/*!
 * \brief Structure for representing a domain name.
 *
 * Stores the domain name in wire format.
 *
 * \todo Consider restricting to FQDN only (see dnslib_dname_new_from_str()).
 */
Lubos Slovak's avatar
Lubos Slovak committed
28
struct dnslib_dname {
29 30 31 32 33 34
	uint8_t *name;	/*!< Wire format of the domain name. */
	/*!
	 * \brief Size of the domain name in octets.
	 * \todo Is this needed? Every dname should end with \0 or pointer.
	 */
	uint size;
Jan Kadlec's avatar
Jan Kadlec committed
35
	struct dnslib_node *node; /*!< Zone node the domain name belongs to. */
Lubos Slovak's avatar
Lubos Slovak committed
36 37
};

38
typedef struct dnslib_dname dnslib_dname_t;
Lubos Slovak's avatar
Lubos Slovak committed
39

40 41 42
/*----------------------------------------------------------------------------*/

/*!
43 44 45
 * \brief Creates empty dname structure (no name, no owner node).
 *
 * \return Newly allocated and initialized dname structure.
Lubos Slovak's avatar
Lubos Slovak committed
46
 *
47 48 49 50 51
 * \todo Possibly useless.
 */
dnslib_dname_t *dnslib_dname_new();

/*!
52 53 54
 * \brief Creates a dname structure from domain name given in presentation
 *        format.
 *
55 56
 * The resulting domain name is stored in wire format, but it may not end with
 * root label (\0).
Lubos Slovak's avatar
Lubos Slovak committed
57
 *
58 59 60 61 62 63 64
 * \param name Domain name in presentation format (labels separated by dots).
 * \param size Size of the domain name (count of characters with all dots).
 * \param node Zone node the domain name belongs to. Set to NULL if not
 *             applicable.
 *
 * \return Newly allocated and initialized dname structure representing the
 *         given domain name.
65
 */
Jan Kadlec's avatar
Jan Kadlec committed
66
dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size,
67
                                          struct dnslib_node *node);
68 69

/*!
70 71
 * \brief Creates a dname structure from domain name given in wire format.
 *
Lubos Slovak's avatar
Lubos Slovak committed
72
 * \note The name is copied into the structure.
73
 * \note If the given name is not a FQDN, the result will be neither.
Lubos Slovak's avatar
Lubos Slovak committed
74
 *
75 76
 * \param name Domain name in wire format.
 * \param size Size of the domain name in octets.
77 78
 * \param node Zone node the domain name belongs to. Set to NULL if not
 *             applicable.
79 80 81 82
 *
 * \return Newly allocated and initialized dname structure representing the
 *         given domain name.
 *
83
 * \todo This function does not check if the given data is in correct wire
84 85 86 87
 *       format at all. It thus creates a invalid domain name, which if passed
 *       e.g. to dnslib_dname_to_str() may result in crash. Decide whether it
 *       is OK to retain this and check the data in other functions before
 *       calling this one, or if it should verify the given data.
88
 */
Jan Kadlec's avatar
Jan Kadlec committed
89 90
dnslib_dname_t *dnslib_dname_new_from_wire(uint8_t *name, uint size,
                struct dnslib_node *node);
91 92

/*!
93 94
 * \brief Converts the given domain name to string representation.
 *
Lubos Slovak's avatar
Lubos Slovak committed
95 96
 * \note Allocates new memory, remember to free it.
 *
97 98 99 100
 * \param dname Domain name to be converted.
 *
 * \return 0-terminated string representing the given domain name in
 *         presentation format.
101
 */
Jan Kadlec's avatar
Jan Kadlec committed
102
char *dnslib_dname_to_str(const dnslib_dname_t *dname);
103 104 105 106 107 108 109 110

/*!
 * \brief Returns the domain name in wire format.
 *
 * \param dname Domain name.
 *
 * \return Wire format of the domain name.
 */
Jan Kadlec's avatar
Jan Kadlec committed
111
const uint8_t *dnslib_dname_name(const dnslib_dname_t *dname);
112 113 114 115 116 117 118 119

/*!
 * \brief Returns size of the given domain name.
 *
 * \param dname Domain name to get the size of.
 *
 * \return Size of the domain name in wire format in octets.
 */
Jan Kadlec's avatar
Jan Kadlec committed
120
uint dnslib_dname_size(const dnslib_dname_t *dname);
121 122 123 124 125 126 127 128

/*!
 * \brief Returns the zone node the domain name belongs to.
 *
 * \param dname Domain name to get the zone node of.
 *
 * \return Zone node the domain name belongs to or NULL if none.
 */
Jan Kadlec's avatar
Jan Kadlec committed
129
const struct dnslib_node *dnslib_dname_node(const dnslib_dname_t *dname);
130

131 132 133 134 135 136 137 138 139 140
/*!
 * \brief Checks if the given domain name is a fully-qualified domain name.
 *
 * \param dname Domain name to check.
 *
 * \retval 0 if \a dname is not a FQDN.
 * \retval <> if \a dname is a FQDN.
 */
int dnslib_dname_is_fqdn(const dnslib_dname_t *dname);

141
/*!
142 143
 * \brief Destroys the given domain name.
 *
144 145 146 147 148
 * Frees also the data within the struct. This is somewhat different behaviour
 * than that of RDATA and RRSet structures which do not deallocate their
 * contents.
 *
 * Sets the given pointer to NULL.
Lubos Slovak's avatar
Lubos Slovak committed
149 150
 *
 * \param dname Domain name to be destroyed.
151
 */
Jan Kadlec's avatar
Jan Kadlec committed
152
void dnslib_dname_free(dnslib_dname_t **dname);
153

154 155 156 157 158 159 160 161 162 163
/*!
 * \brief Compares two domain names.
 *
 * \param d1 First domain name.
 * \param d2 Second domain name.
 *
 * \retval -1 if \a d1 goes before \a d2 in canonical order.
 * \retval 1 if \a d1 goes after \a d2 in canonical order.
 * \retval 0 if the domain names are identical.
 */
Jan Kadlec's avatar
Jan Kadlec committed
164
int dnslib_dname_compare(const dnslib_dname_t *d1, const dnslib_dname_t *d2);
165

166 167 168 169 170 171 172 173 174 175 176 177 178
/*!
 * \brief Concatenates two domain names.
 *
 * \note Member \a node is ignored, i.e. preserved.
 *
 * \param d1 First domain name (will be modified).
 * \param d2 Second domain name (will not be modified).
 *
 * \return The concatenated domain name (i.e. modified \a d1) or NULL if
 *         the operation is not valid (e.g. \a d1 is a FQDN).
 */
dnslib_dname_t *dnslib_dname_cat(dnslib_dname_t *d1, const dnslib_dname_t *d2);

Jan Kadlec's avatar
Jan Kadlec committed
179
#endif /* _CUTEDNS_DNSLIB_DNAME_H_ */
180 181

/*! @} */