dname.h 5.25 KB
 Lubos Slovak committed Nov 10, 2010 1 2 3 4 5 6 7 8 9 10 ``````/*! * \file dname.h * \author Lubos Slovak * * \brief Domain name structure and API for manipulating it. * * \addtogroup dnslib * @{ */ `````` Jan Kadlec committed Nov 26, 2010 11 12 ``````#ifndef _CUTEDNS_DNSLIB_DNAME_H_ #define _CUTEDNS_DNSLIB_DNAME_H_ `````` Lubos Slovak committed Nov 04, 2010 13 14 `````` #include `````` Lubos Slovak committed Nov 29, 2010 15 `````` `````` Lubos Slovak committed Nov 04, 2010 16 ``````#include "common.h" `````` Lubos Slovak committed Nov 09, 2010 17 18 `````` struct dnslib_node; `````` Lubos Slovak committed Nov 04, 2010 19 `````` `````` Lubos Slovak committed Nov 09, 2010 20 ``````/*----------------------------------------------------------------------------*/ `````` Lubos Slovak committed Nov 09, 2010 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 committed Nov 04, 2010 28 ``````struct dnslib_dname { `````` Lubos Slovak committed Nov 09, 2010 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 committed Nov 26, 2010 35 `````` struct dnslib_node *node; /*!< Zone node the domain name belongs to. */ `````` Lubos Slovak committed Nov 04, 2010 36 37 ``````}; `````` Lubos Slovak committed Nov 09, 2010 38 ``````typedef struct dnslib_dname dnslib_dname_t; `````` Lubos Slovak committed Nov 04, 2010 39 `````` `````` Lubos Slovak committed Nov 09, 2010 40 41 42 ``````/*----------------------------------------------------------------------------*/ /*! `````` Lubos Slovak committed Nov 09, 2010 43 44 45 `````` * \brief Creates empty dname structure (no name, no owner node). * * \return Newly allocated and initialized dname structure. `````` Lubos Slovak committed Nov 29, 2010 46 `````` * `````` Lubos Slovak committed Nov 09, 2010 47 48 49 50 51 `````` * \todo Possibly useless. */ dnslib_dname_t *dnslib_dname_new(); /*! `````` Lubos Slovak committed Nov 09, 2010 52 53 54 `````` * \brief Creates a dname structure from domain name given in presentation * format. * `````` Lubos Slovak committed Nov 30, 2010 55 56 `````` * The resulting domain name is stored in wire format, but it may not end with * root label (\0). `````` Lubos Slovak committed Nov 29, 2010 57 `````` * `````` Lubos Slovak committed Nov 09, 2010 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. `````` Lubos Slovak committed Nov 09, 2010 65 `````` */ `````` Jan Kadlec committed Nov 26, 2010 66 ``````dnslib_dname_t *dnslib_dname_new_from_str(char *name, uint size, `````` Lubos Slovak committed Nov 30, 2010 67 `````` struct dnslib_node *node); `````` Lubos Slovak committed Nov 09, 2010 68 69 `````` /*! `````` Lubos Slovak committed Nov 09, 2010 70 71 `````` * \brief Creates a dname structure from domain name given in wire format. * `````` Lubos Slovak committed Nov 29, 2010 72 `````` * \note The name is copied into the structure. `````` Lubos Slovak committed Nov 30, 2010 73 `````` * \note If the given name is not a FQDN, the result will be neither. `````` Lubos Slovak committed Nov 29, 2010 74 `````` * `````` Lubos Slovak committed Nov 09, 2010 75 76 `````` * \param name Domain name in wire format. * \param size Size of the domain name in octets. `````` Lubos Slovak committed Nov 09, 2010 77 78 `````` * \param node Zone node the domain name belongs to. Set to NULL if not * applicable. `````` Lubos Slovak committed Nov 09, 2010 79 80 81 82 `````` * * \return Newly allocated and initialized dname structure representing the * given domain name. * `````` Lubos Slovak committed Nov 30, 2010 83 `````` * \todo This function does not check if the given data is in correct wire `````` Lubos Slovak committed Nov 18, 2010 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. `````` Lubos Slovak committed Nov 09, 2010 88 `````` */ `````` Jan Kadlec committed Nov 26, 2010 89 90 ``````dnslib_dname_t *dnslib_dname_new_from_wire(uint8_t *name, uint size, struct dnslib_node *node); `````` Lubos Slovak committed Nov 09, 2010 91 92 `````` /*! `````` Lubos Slovak committed Nov 09, 2010 93 94 `````` * \brief Converts the given domain name to string representation. * `````` Lubos Slovak committed Nov 29, 2010 95 96 `````` * \note Allocates new memory, remember to free it. * `````` Lubos Slovak committed Nov 09, 2010 97 98 99 100 `````` * \param dname Domain name to be converted. * * \return 0-terminated string representing the given domain name in * presentation format. `````` Lubos Slovak committed Nov 09, 2010 101 `````` */ `````` Jan Kadlec committed Nov 26, 2010 102 ``````char *dnslib_dname_to_str(const dnslib_dname_t *dname); `````` Lubos Slovak committed Nov 09, 2010 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 committed Nov 26, 2010 111 ``````const uint8_t *dnslib_dname_name(const dnslib_dname_t *dname); `````` Lubos Slovak committed Nov 09, 2010 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 committed Nov 26, 2010 120 ``````uint dnslib_dname_size(const dnslib_dname_t *dname); `````` Lubos Slovak committed Nov 09, 2010 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 committed Nov 26, 2010 129 ``````const struct dnslib_node *dnslib_dname_node(const dnslib_dname_t *dname); `````` Lubos Slovak committed Nov 09, 2010 130 `````` `````` Lubos Slovak committed Nov 30, 2010 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); `````` Lubos Slovak committed Nov 09, 2010 141 ``````/*! `````` Lubos Slovak committed Nov 09, 2010 142 143 `````` * \brief Destroys the given domain name. * `````` Lubos Slovak committed Nov 10, 2010 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 committed Nov 29, 2010 149 150 `````` * * \param dname Domain name to be destroyed. `````` Lubos Slovak committed Nov 09, 2010 151 `````` */ `````` Jan Kadlec committed Nov 26, 2010 152 ``````void dnslib_dname_free(dnslib_dname_t **dname); `````` Lubos Slovak committed Nov 09, 2010 153 `````` `````` Lubos Slovak committed Nov 16, 2010 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 committed Nov 26, 2010 164 ``````int dnslib_dname_compare(const dnslib_dname_t *d1, const dnslib_dname_t *d2); `````` Lubos Slovak committed Nov 16, 2010 165 `````` `````` Lubos Slovak committed Nov 30, 2010 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 committed Nov 26, 2010 179 ``````#endif /* _CUTEDNS_DNSLIB_DNAME_H_ */ `````` Lubos Slovak committed Nov 10, 2010 180 181 `````` /*! @} */``````