dns_resolver.h File Reference

DNS Resolver API. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_dns_resolver
	DNS resolver implementation. More...

Functions
int	ast_dns_resolver_add_record (struct ast_dns_query *query, int rr_type, int rr_class, int ttl, const char *data, const size_t size)
	Add a DNS record to the result of a DNS query. More...
void	ast_dns_resolver_completed (struct ast_dns_query *query)
	Mark a DNS query as having been completed. More...
void *	ast_dns_resolver_get_data (const struct ast_dns_query *query)
	Retrieve resolver specific data. More...
int	ast_dns_resolver_register (struct ast_dns_resolver *resolver)
	Register a DNS resolver. More...
int	ast_dns_resolver_set_data (struct ast_dns_query *query, void *data)
	Set resolver specific data on a query. More...
int	ast_dns_resolver_set_result (struct ast_dns_query *query, unsigned int secure, unsigned int bogus, unsigned int rcode, const char *canonical, const char *answer, size_t answer_size)
	Set result information for a DNS query. More...
void	ast_dns_resolver_unregister (struct ast_dns_resolver *resolver)
	Unregister a DNS resolver. More...

Detailed Description

DNS Resolver API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file dns_resolver.h.

Function Documentation

ast_dns_resolver_add_record()

int ast_dns_resolver_add_record	(	struct ast_dns_query *	query,
		int	rr_type,
		int	rr_class,
		int	ttl,
		const char *	data,
		const size_t	size
	)

Add a DNS record to the result of a DNS query.

Parameters

query	The DNS query
rr_type	Resource record type
rr_class	Resource record class
ttl	TTL of the record
data	The raw DNS record
size	The size of the raw DNS record

Return values

0	success
-1	failure

Definition at line 535 of file dns_core.c.

References allocate_dns_record(), ast_debug, AST_LIST_INSERT_TAIL, ast_dns_record::data_len, ast_dns_record::data_ptr, ast_dns_record::list, ast_dns_result::records, ast_dns_query::result, ast_dns_record::rr_class, ast_dns_record::rr_type, and ast_dns_record::ttl.

Referenced by AST_TEST_DEFINE(), dns_system_resolver_add_record(), naptr_thread(), resolution_thread(), srv_thread(), and unbound_resolver_callback().

{
   struct ast_dns_record *record;

   if (rr_type < 0) {
      ast_debug(2, "Query '%p': Could not add record, invalid resource record type '%d'\n",
         query, rr_type);
      return -1;
   } else if (rr_type > 65536) {
      ast_debug(2, "Query '%p': Could not add record, resource record type '%d' exceeds maximum\n",
         query, rr_type);
      return -1;
   } else if (rr_class < 0) {
      ast_debug(2, "Query '%p': Could not add record, invalid resource record class '%d'\n",
         query, rr_class);
      return -1;
   } else if (rr_class > 65536) {
      ast_debug(2, "Query '%p': Could not add record, resource record class '%d' exceeds maximum\n",
         query, rr_class);
      return -1;
   } else if (ttl < 0) {
      ast_debug(2, "Query '%p': Could not add record, invalid TTL '%d'\n",
         query, ttl);
      return -1;
   } else if (!data || !size) {
      ast_debug(2, "Query '%p': Could not add record, no data specified\n",
         query);
      return -1;
   } else if (!query->result) {
      ast_debug(2, "Query '%p': No result was set on the query, thus records can not be added\n",
         query);
      return -1;
   }

   record = allocate_dns_record(rr_type, query, data, size);
   if (!record) {
      return -1;
   }

   record->rr_type = rr_type;
   record->rr_class = rr_class;
   record->ttl = ttl;
   record->data_len = size;
   memcpy(record->data_ptr, data, size);

   AST_LIST_INSERT_TAIL(&query->result->records, record, list);

   return 0;
}

ast_dns_resolver_completed()

void ast_dns_resolver_completed

(

struct ast_dns_query *

query

)

Mark a DNS query as having been completed.

Parameters

query

The DNS query

Definition at line 599 of file dns_core.c.

References ast_dns_query_get_rr_type(), ast_dns_query::callback, ast_dns_query::result, and sort_result().

Referenced by dns_system_resolver_process_query(), naptr_thread(), resolution_thread(), srv_thread(), and unbound_resolver_callback().

{
   sort_result(ast_dns_query_get_rr_type(query), query->result);

   query->callback(query);
}

ast_dns_resolver_get_data()

void* ast_dns_resolver_get_data

(

const struct ast_dns_query *

query

)

Retrieve resolver specific data.

Parameters

query

The DNS query

Returns

the resolver specific data

Note

The reference count of the resolver data is NOT incremented on return

Definition at line 451 of file dns_core.c.

References ast_dns_query::resolver_data.

Referenced by AST_TEST_DEFINE(), and unbound_resolver_cancel().

{
   return query->resolver_data;
}

ast_dns_resolver_register()

int ast_dns_resolver_register

(

struct ast_dns_resolver *

resolver

)

Register a DNS resolver.

Parameters

resolver

A DNS resolver implementation

Return values

0	success
-1	failure

Definition at line 630 of file dns_core.c.

References AST_LIST_TRAVERSE, ast_log, AST_RWLIST_INSERT_BEFORE_CURRENT, AST_RWLIST_INSERT_TAIL, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero, ast_verb, ast_dns_resolver::cancel, LOG_ERROR, ast_dns_resolver::name, ast_dns_resolver::priority, and ast_dns_resolver::resolve.

Referenced by ast_dns_system_resolver_init(), AST_TEST_DEFINE(), invalid_record_test(), load_module(), nominal_test(), off_nominal_test(), and query_set_test().

{
   struct ast_dns_resolver *iter;
   int inserted = 0;

   if (!resolver) {
      return -1;
   } else if (ast_strlen_zero(resolver->name)) {
      ast_log(LOG_ERROR, "Registration of DNS resolver failed as it does not have a name\n");
      return -1;
   } else if (!resolver->resolve) {
      ast_log(LOG_ERROR, "DNS resolver '%s' does not implement the resolve callback which is required\n",
         resolver->name);
      return -1;
   } else if (!resolver->cancel) {
      ast_log(LOG_ERROR, "DNS resolver '%s' does not implement the cancel callback which is required\n",
         resolver->name);
      return -1;
   }

   AST_RWLIST_WRLOCK(&resolvers);

   AST_LIST_TRAVERSE(&resolvers, iter, next) {
      if (!strcmp(iter->name, resolver->name)) {
         ast_log(LOG_ERROR, "A DNS resolver with the name '%s' is already registered\n", resolver->name);
         AST_RWLIST_UNLOCK(&resolvers);
         return -1;
      }
   }

   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&resolvers, iter, next) {
      if (iter->priority > resolver->priority) {
         AST_RWLIST_INSERT_BEFORE_CURRENT(resolver, next);
         inserted = 1;
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;

   if (!inserted) {
      AST_RWLIST_INSERT_TAIL(&resolvers, resolver, next);
   }

   AST_RWLIST_UNLOCK(&resolvers);

   ast_verb(2, "Registered DNS resolver '%s' with priority '%d'\n", resolver->name, resolver->priority);

   return 0;
}

ast_dns_resolver_set_data()

int ast_dns_resolver_set_data	(	struct ast_dns_query *	query,
		void *	data
	)

Set resolver specific data on a query.

Parameters

query	The DNS query
data	The resolver specific data

Note

The resolver data MUST be an ao2 object

This function increments the reference count of the resolver data, it does NOT steal

Once resolver specific data has been set it can not be changed

Return values

0	success
-1	failure, resolver data is already set

Definition at line 440 of file dns_core.c.

References ao2_bump, and ast_dns_query::resolver_data.

Referenced by AST_TEST_DEFINE(), and unbound_resolver_resolve().

{
   if (query->resolver_data) {
      return -1;
   }

   query->resolver_data = ao2_bump(data);

   return 0;
}

ast_dns_resolver_set_result()

int ast_dns_resolver_set_result	(	struct ast_dns_query *	query,
		unsigned int	secure,
		unsigned int	bogus,
		unsigned int	rcode,
		const char *	canonical,
		const char *	answer,
		size_t	answer_size
	)

Set result information for a DNS query.

Parameters

query	The DNS query
result	Whether the result is secured or not
bogus	Whether the result is bogus or not
rcode	Optional response code
canonical	The canonical name
answer	The raw DNS answer
answer_size	The size of the raw DNS answer

Zero-sized and NULL answers are permitted by this function. This may be necessary if the query fails at an early stage and no actual DNS response has been received from a DNS server.

Return values

0	success
-1	failure

Definition at line 456 of file dns_core.c.

References ast_dns_result::answer, ast_dns_result::answer_size, ast_calloc, ast_debug, ast_dns_result_free(), ast_strlen_zero, ast_dns_result::bogus, ast_dns_result::buf, ast_dns_result::canonical, ast_dns_result::rcode, ast_dns_query::result, and ast_dns_result::secure.

Referenced by AST_TEST_DEFINE(), dns_system_resolver_set_response(), naptr_thread(), resolution_thread(), srv_thread(), and unbound_resolver_callback().

{
   char *buf_ptr;

   if (secure && bogus) {
      ast_debug(2, "Query '%p': Could not set result information, it can not be both secure and bogus\n",
         query);
      return -1;
   }

   if (ast_strlen_zero(canonical)) {
      ast_debug(2, "Query '%p': Could not set result information since no canonical name was provided\n",
         query);
      return -1;
   }

   if (!answer) {
      answer = "";
      answer_size = 0;
      ast_debug(2, "Query '%p': Assuming zero-sized answer on NULL input\n", query);
   }

   ast_dns_result_free(query->result);

   query->result = ast_calloc(1, sizeof(*query->result) + strlen(canonical) + 1 + answer_size);
   if (!query->result) {
      return -1;
   }

   query->result->secure = secure;
   query->result->bogus = bogus;
   query->result->rcode = rcode;

   buf_ptr = query->result->buf;
   strcpy(buf_ptr, canonical); /* SAFE */
   query->result->canonical = buf_ptr;

   buf_ptr += strlen(canonical) + 1;
   memcpy(buf_ptr, answer, answer_size); /* SAFE */
   query->result->answer = buf_ptr;
   query->result->answer_size = answer_size;

   return 0;
}

ast_dns_resolver_unregister()

void ast_dns_resolver_unregister

(

struct ast_dns_resolver *

resolver

)

Unregister a DNS resolver.

Parameters

resolver

A DNS resolver implementation

Definition at line 680 of file dns_core.c.

References AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, and ast_dns_resolver::name.

Referenced by AST_TEST_DEFINE(), dns_system_resolver_destroy(), invalid_record_test(), nominal_test(), off_nominal_test(), and query_set_test().

{
   struct ast_dns_resolver *iter;

   if (!resolver) {
      return;
   }

   AST_RWLIST_WRLOCK(&resolvers);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&resolvers, iter, next) {
      if (resolver == iter) {
         AST_RWLIST_REMOVE_CURRENT(next);
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&resolvers);

   ast_verb(2, "Unregistered DNS resolver '%s'\n", resolver->name);
}