dns: doxygen comments

This commit is contained in:
Richard Aas 2012-08-16 08:43:50 +00:00
parent e429834cec
commit 2e2460253a
11 changed files with 278 additions and 3 deletions

View file

@ -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;

View file

@ -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

View file

@ -1,5 +1,5 @@
/**
* @file hdr.c BFCP Message header
* @file bfcp/hdr.c BFCP Message header
*
* Copyright (C) 2010 Creytiv.com
*/

View file

@ -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;

View file

@ -12,6 +12,14 @@
#include <re_dns.h>
/**
* 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;

View file

@ -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;

View file

@ -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) {

View file

@ -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;

View file

@ -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)
{

View file

@ -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;

View file

@ -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)
{