diff --git a/include/re_dns.h b/include/re_dns.h index e03a2d2..ad25c75 100644 --- a/include/re_dns.h +++ b/include/re_dns.h @@ -11,6 +11,7 @@ enum { }; +/** DNS Opcodes */ enum { DNS_OPCODE_QUERY = 0, DNS_OPCODE_IQUERY = 1, @@ -19,6 +20,7 @@ enum { }; +/** DNS Response codes */ enum { DNS_RCODE_OK = 0, DNS_RCODE_FMT_ERR = 1, @@ -30,6 +32,7 @@ enum { }; +/** DNS Resource Record types */ enum { DNS_TYPE_A = 0x0001, DNS_TYPE_NS = 0x0002, @@ -46,12 +49,14 @@ enum { }; +/** DNS Classes */ enum { DNS_CLASS_IN = 0x0001, DNS_QCLASS_ANY = 0x00ff }; +/** Defines a DNS Header */ struct dnshdr { uint16_t id; bool qr; @@ -69,6 +74,7 @@ struct dnshdr { }; +/** Defines a DNS Resource Record (RR) */ struct dnsrr { struct le le; struct le le_priv; @@ -125,9 +131,28 @@ struct dnsrr { struct hash; +/** + * Defines the DNS Query handler + * + * @param err 0 if success, otherwise errorcode + * @param hdr DNS Header + * @param ansl List of Answer records + * @param authl List of Authoritive records + * @param addl List of Additional records + * @param arg Handler argument + */ typedef void(dns_query_h)(int err, const struct dnshdr *hdr, struct list *ansl, struct list *authl, struct list *addl, void *arg); + +/** + * Defines the DNS Resource Record list handler + * + * @param rr DNS Resource Record + * @param arg Handler argument + * + * @return True to stop traversing, False to continue + */ typedef bool(dns_rrlist_h)(struct dnsrr *rr, void *arg); int dns_hdr_encode(struct mbuf *mb, const struct dnshdr *hdr); @@ -164,6 +189,7 @@ struct sa; struct dnsc; struct dns_query; +/** DNS Client configuration */ struct dnsc_conf { uint32_t query_hash_size; uint32_t tcp_hash_size; diff --git a/mk/Doxyfile b/mk/Doxyfile index f8f5702..08d7ace 100644 --- a/mk/Doxyfile +++ b/mk/Doxyfile @@ -90,7 +90,6 @@ RECURSIVE = YES EXCLUDE = test.c \ include/re_bitv.h \ src/md5/md5.h src/md5/md5.c \ - src/dns include/re_dns.h \ src/stun include/re_stun.h EXCLUDE_SYMLINKS = NO @@ -229,7 +228,7 @@ DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png DOT_PATH = DOTFILE_DIRS = -DOT_GRAPH_MAX_NODES = 150 +DOT_GRAPH_MAX_NODES = 256 #MAX_DOT_GRAPH_WIDTH = 1024 #MAX_DOT_GRAPH_HEIGHT = 1024 #MAX_DOT_GRAPH_DEPTH = 1000 diff --git a/src/bfcp/hdr.c b/src/bfcp/hdr.c index 13c2350..8ffb071 100644 --- a/src/bfcp/hdr.c +++ b/src/bfcp/hdr.c @@ -1,5 +1,5 @@ /** - * @file hdr.c BFCP Message header + * @file bfcp/hdr.c BFCP Message header * * Copyright (C) 2010 Creytiv.com */ diff --git a/src/dns/client.c b/src/dns/client.c index 2662a28..95688c7 100644 --- a/src/dns/client.c +++ b/src/dns/client.c @@ -732,6 +732,20 @@ static int query(struct dns_query **qp, struct dnsc *dnsc, uint8_t opcode, } +/** + * Query a DNS name + * + * @param qp Pointer to allocated DNS query + * @param dnsc DNS Client + * @param name DNS name + * @param type DNS Resource Record type + * @param dnsclass DNS Class + * @param rd Recursion Desired (RD) flag + * @param qh Query handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int dnsc_query(struct dns_query **qp, struct dnsc *dnsc, const char *name, uint16_t type, uint16_t dnsclass, bool rd, dns_query_h *qh, void *arg) @@ -744,6 +758,23 @@ int dnsc_query(struct dns_query **qp, struct dnsc *dnsc, const char *name, } +/** + * Query a DNS name SRV record + * + * @param qp Pointer to allocated DNS query + * @param dnsc DNS Client + * @param name DNS name + * @param type DNS Resource Record type + * @param dnsclass DNS Class + * @param proto Protocol + * @param srvv DNS Nameservers + * @param srvc Number of DNS nameservers + * @param rd Recursion Desired (RD) flag + * @param qh Query handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int dnsc_query_srv(struct dns_query **qp, struct dnsc *dnsc, const char *name, uint16_t type, uint16_t dnsclass, int proto, const struct sa *srvv, const uint32_t *srvc, @@ -754,6 +785,23 @@ int dnsc_query_srv(struct dns_query **qp, struct dnsc *dnsc, const char *name, } +/** + * Send a DNS query with NOTIFY opcode + * + * @param qp Pointer to allocated DNS query + * @param dnsc DNS Client + * @param name DNS name + * @param type DNS Resource Record type + * @param dnsclass DNS Class + * @param ans_rr Answer Resource Record + * @param proto Protocol + * @param srvv DNS Nameservers + * @param srvc Number of DNS nameservers + * @param qh Query handler + * @param arg Handler argument + * + * @return 0 if success, otherwise errorcode + */ int dnsc_notify(struct dns_query **qp, struct dnsc *dnsc, const char *name, uint16_t type, uint16_t dnsclass, const struct dnsrr *ans_rr, int proto, const struct sa *srvv, const uint32_t *srvc, @@ -777,6 +825,16 @@ static void dnsc_destructor(void *data) } +/** + * Allocate a DNS Client + * + * @param dcpp Pointer to allocated DNS Client + * @param conf Optional DNS configuration, NULL for default + * @param srvv DNS servers + * @param srvc Number of DNS Servers + * + * @return 0 if success, otherwise errorcode + */ int dnsc_alloc(struct dnsc **dcpp, const struct dnsc_conf *conf, const struct sa *srvv, uint32_t srvc) { @@ -829,6 +887,15 @@ int dnsc_alloc(struct dnsc **dcpp, const struct dnsc_conf *conf, } +/** + * Set the DNS Servers on a DNS Client + * + * @param dnsc DNS Client + * @param srvv DNS Nameservers + * @param srvc Number of nameservers + * + * @return 0 if success, otherwise errorcode + */ int dnsc_srv_set(struct dnsc *dnsc, const struct sa *srvv, uint32_t srvc) { uint32_t i; diff --git a/src/dns/cstr.c b/src/dns/cstr.c index 20574ec..9e6c90a 100644 --- a/src/dns/cstr.c +++ b/src/dns/cstr.c @@ -12,6 +12,14 @@ #include +/** + * Encode a DNS character string into a memory buffer + * + * @param mb Memory buffer to encode into + * @param str Character string + * + * @return 0 if success, otherwise errorcode + */ int dns_cstr_encode(struct mbuf *mb, const char *str) { uint8_t len; @@ -29,6 +37,14 @@ int dns_cstr_encode(struct mbuf *mb, const char *str) } +/** + * Decode a DNS character string from a memory buffer + * + * @param mb Memory buffer to decode from + * @param str Pointer to allocated character string + * + * @return 0 if success, otherwise errorcode + */ int dns_cstr_decode(struct mbuf *mb, char **str) { uint8_t len; diff --git a/src/dns/dname.c b/src/dns/dname.c index 23a74a3..eda9ba4 100644 --- a/src/dns/dname.c +++ b/src/dns/dname.c @@ -77,6 +77,17 @@ static inline int dname_encode_pointer(struct mbuf *mb, size_t pos) } +/** + * Encode a DNS Domain name into a memory buffer + * + * @param mb Memory buffer + * @param name Domain name + * @param ht_dname Domain name hashtable + * @param start Start position + * @param comp Enable compression + * + * @return 0 if success, otherwise errorcode + */ int dns_dname_encode(struct mbuf *mb, const char *name, struct hash *ht_dname, size_t start, bool comp) { @@ -139,6 +150,15 @@ int dns_dname_encode(struct mbuf *mb, const char *name, } +/** + * Decode a DNS domain name from a memory buffer + * + * @param mb Memory buffer to decode from + * @param name Pointer to allocated string with domain name + * @param start Start position + * + * @return 0 if success, otherwise errorcode + */ int dns_dname_decode(struct mbuf *mb, char **name, size_t start) { uint32_t i = 0, loopc = 0; diff --git a/src/dns/hdr.c b/src/dns/hdr.c index 1e4ac2f..5133b33 100644 --- a/src/dns/hdr.c +++ b/src/dns/hdr.c @@ -22,6 +22,14 @@ enum { }; +/** + * Encode a DNS header + * + * @param mb Memory buffer to encode header into + * @param hdr DNS header + * + * @return 0 if success, otherwise errorcode + */ int dns_hdr_encode(struct mbuf *mb, const struct dnshdr *hdr) { uint16_t flags = 0; @@ -50,6 +58,14 @@ int dns_hdr_encode(struct mbuf *mb, const struct dnshdr *hdr) } +/** + * Decode a DNS header from a memory buffer + * + * @param mb Memory buffer to decode header from + * @param hdr DNS header (output) + * + * @return 0 if success, otherwise errorcode + */ int dns_hdr_decode(struct mbuf *mb, struct dnshdr *hdr) { uint16_t flags = 0; @@ -78,6 +94,13 @@ int dns_hdr_decode(struct mbuf *mb, struct dnshdr *hdr) } +/** + * Get the string of a DNS opcode + * + * @param opcode DNS opcode + * + * @return Opcode string + */ const char *dns_hdr_opcodename(uint8_t opcode) { switch (opcode) { @@ -91,6 +114,13 @@ const char *dns_hdr_opcodename(uint8_t opcode) } +/** + * Get the string of a DNS response code + * + * @param rcode Response code + * + * @return Response code string + */ const char *dns_hdr_rcodename(uint8_t rcode) { switch (rcode) { diff --git a/src/dns/ns.c b/src/dns/ns.c index 182c3a9..03683b5 100644 --- a/src/dns/ns.c +++ b/src/dns/ns.c @@ -81,6 +81,16 @@ static int parse_resolv_conf(char *domain, size_t dsize, } +/** + * Get the DNS domain and nameservers + * + * @param domain Returned domain name + * @param dsize Size of domain name buffer + * @param srvv Returned nameservers + * @param n Nameservers capacity, actual on return + * + * @return 0 if success, otherwise errorcode + */ int dns_srv_get(char *domain, size_t dsize, struct sa *srvv, uint32_t *n) { int err; diff --git a/src/dns/res.c b/src/dns/res.c index 27bca14..082cc3d 100644 --- a/src/dns/res.c +++ b/src/dns/res.c @@ -20,8 +20,15 @@ /** * Generic way of fetching Nameserver IP-addresses, using libresolv * + * @param domain Returned domain name + * @param dsize Size of domain name buffer + * @param nsv Returned nameservers + * @param n Nameservers capacity, actual on return + * * @note we could use res_getservers() but it is not available on Linux * @note only IPv4 is supported + * + * @return 0 if success, otherwise errorcode */ int get_resolv_dns(char *domain, size_t dsize, struct sa *nsv, uint32_t *n) { diff --git a/src/dns/rr.c b/src/dns/rr.c index c24e912..cb06d5d 100644 --- a/src/dns/rr.c +++ b/src/dns/rr.c @@ -57,12 +57,28 @@ static void rr_destructor(void *data) } +/** + * Allocate a new DNS Resource Record (RR) + * + * @return Newly allocated Resource Record, or NULL if no memory + */ struct dnsrr *dns_rr_alloc(void) { return mem_zalloc(sizeof(struct dnsrr), rr_destructor); } +/** + * Encode a DNS Resource Record + * + * @param mb Memory buffer to encode into + * @param rr DNS Resource Record + * @param ttl_offs TTL Offset + * @param ht_dname Domain name hash-table + * @param start Start position + * + * @return 0 if success, otherwise errorcode + */ int dns_rr_encode(struct mbuf *mb, const struct dnsrr *rr, int64_t ttl_offs, struct hash *ht_dname, size_t start) { @@ -159,6 +175,15 @@ int dns_rr_encode(struct mbuf *mb, const struct dnsrr *rr, int64_t ttl_offs, } +/** + * Decode a DNS Resource Record (RR) from a memory buffer + * + * @param mb Memory buffer to decode from + * @param rr Pointer to allocated Resource Record + * @param start Start position + * + * @return 0 if success, otherwise errorcode + */ int dns_rr_decode(struct mbuf *mb, struct dnsrr **rr, size_t start) { int err = 0; @@ -313,6 +338,15 @@ int dns_rr_decode(struct mbuf *mb, struct dnsrr **rr, size_t start) } +/** + * Compare two DNS Resource Records + * + * @param rr1 First Resource Record + * @param rr2 Second Resource Record + * @param rdata If true, also compares Resource Record data + * + * @return True if match, false if not match + */ bool dns_rr_cmp(const struct dnsrr *rr1, const struct dnsrr *rr2, bool rdata) { if (!rr1 || !rr2) @@ -453,6 +487,13 @@ bool dns_rr_cmp(const struct dnsrr *rr1, const struct dnsrr *rr2, bool rdata) } +/** + * Get the DNS Resource Record (RR) name + * + * @param type DNS Resource Record type + * + * @return DNS Resource Record name + */ const char *dns_rr_typename(uint16_t type) { switch (type) { @@ -474,6 +515,13 @@ const char *dns_rr_typename(uint16_t type) } +/** + * Get the DNS Resource Record (RR) class name + * + * @param dnsclass DNS Class + * + * @return DNS Class name + */ const char *dns_rr_classname(uint16_t dnsclass) { switch (dnsclass) { @@ -485,6 +533,14 @@ const char *dns_rr_classname(uint16_t dnsclass) } +/** + * Print a DNS Resource Record + * + * @param pf Print function + * @param rr DNS Resource Record + * + * @return 0 if success, otherwise errorcode + */ int dns_rr_print(struct re_printf *pf, const struct dnsrr *rr) { static const size_t w = 24; diff --git a/src/dns/rrlist.c b/src/dns/rrlist.c index 9517c58..69bf211 100644 --- a/src/dns/rrlist.c +++ b/src/dns/rrlist.c @@ -57,6 +57,12 @@ static bool std_sort_handler(struct le *le1, struct le *le2, void *arg) } +/** + * Sort a list of DNS Resource Records + * + * @param rrl DNS Resource Record list + * @param type DNS Record type + */ void dns_rrlist_sort(struct list *rrl, uint16_t type) { list_sort(rrl, std_sort_handler, &type); @@ -111,6 +117,19 @@ static struct dnsrr *rrlist_apply(struct list *rrl, const char *name, } +/** + * Apply a function handler to a list of DNS Resource Records + * + * @param rrl DNS Resource Record list + * @param name If set, filter on domain name + * @param type If not DNS_QTYPE_ANY, filter on record type + * @param dnsclass If not DNS_QCLASS_ANY, filter on DNS class + * @param recurse Cname recursion + * @param rrlh Resource record handler + * @param arg Handler argument + * + * @return Matching Resource Record or NULL + */ struct dnsrr *dns_rrlist_apply(struct list *rrl, const char *name, uint16_t type, uint16_t dnsclass, bool recurse, dns_rrlist_h *rrlh, void *arg) @@ -120,6 +139,20 @@ struct dnsrr *dns_rrlist_apply(struct list *rrl, const char *name, } +/** + * Apply a function handler to a list of DNS Resource Records (two types) + * + * @param rrl DNS Resource Record list + * @param name If set, filter on domain name + * @param type1 If not DNS_QTYPE_ANY, filter on record type + * @param type2 If not DNS_QTYPE_ANY, filter on record type + * @param dnsclass If not DNS_QCLASS_ANY, filter on DNS class + * @param recurse Cname recursion + * @param rrlh Resource record handler + * @param arg Handler argument + * + * @return Matching Resource Record or NULL + */ struct dnsrr *dns_rrlist_apply2(struct list *rrl, const char *name, uint16_t type1, uint16_t type2, uint16_t dnsclass, bool recurse, @@ -138,6 +171,17 @@ static bool find_handler(struct dnsrr *rr, void *arg) } +/** + * Find a DNS Resource Record in a list + * + * @param rrl Resource Record list + * @param name If set, filter on domain name + * @param type If not DNS_QTYPE_ANY, filter on record type + * @param dnsclass If not DNS_QCLASS_ANY, filter on DNS class + * @param recurse Cname recursion + * + * @return Matching Resource Record or NULL + */ struct dnsrr *dns_rrlist_find(struct list *rrl, const char *name, uint16_t type, uint16_t dnsclass, bool recurse) {