dns_query_set.h File Reference

DNS Query Set API. More...

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

Go to the source code of this file.

Typedefs
typedef void(*	ast_dns_query_set_callback) (const struct ast_dns_query_set *query_set)
	Callback invoked when a query set completes. More...

Functions
int	ast_dns_query_set_add (struct ast_dns_query_set *query_set, const char *name, int rr_type, int rr_class)
	Add a query to a query set. More...
struct ast_dns_query_set *	ast_dns_query_set_create (void)
	Create a query set to hold queries. More...
struct ast_dns_query *	ast_dns_query_set_get (const struct ast_dns_query_set *query_set, unsigned int index)
	Retrieve a query from a query set. More...
void *	ast_dns_query_set_get_data (const struct ast_dns_query_set *query_set)
	Retrieve user specific data from a query set. More...
size_t	ast_dns_query_set_num_queries (const struct ast_dns_query_set *query_set)
	Retrieve the number of queries in a query set. More...
void	ast_dns_query_set_resolve_async (struct ast_dns_query_set *query_set, ast_dns_query_set_callback callback, void *data)
	Asynchronously resolve queries in a query set. More...
int	ast_dns_query_set_resolve_cancel (struct ast_dns_query_set *query_set)
	Cancel an asynchronous DNS query set resolution. More...
int	ast_query_set_resolve (struct ast_dns_query_set *query_set)
	Synchronously resolve queries in a query set. More...

Detailed Description

DNS Query Set API.

Author

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

Definition in file dns_query_set.h.

Typedef Documentation

ast_dns_query_set_callback

typedef void(* ast_dns_query_set_callback) (const struct ast_dns_query_set *query_set)

Callback invoked when a query set completes.

Parameters

query_set

The DNS query set that was invoked

Definition at line 39 of file dns_query_set.h.

Function Documentation

ast_dns_query_set_add()

int ast_dns_query_set_add	(	struct ast_dns_query_set *	query_set,
		const char *	name,
		int	rr_type,
		int	rr_class
	)

Add a query to a query set.

Parameters

query_set	A DNS query set
name	The name of what to resolve
rr_type	Resource record type
rr_class	Resource record class

Return values

0	success
-1	failure

Definition at line 105 of file dns_query_set.c.

References ao2_ref, ast_assert, ast_log, AST_VECTOR_APPEND, dns_query_alloc(), dns_query_set_callback(), ast_dns_query_set::in_progress, LOG_ERROR, NULL, dns_query_set_query::query, and dns_query_set_query::started.

Referenced by ast_dns_resolve_ipv6_and_ipv4(), query_set_test(), and sip_resolve_add().

{
   struct dns_query_set_query query = {
      .started = 0,
   };

   ast_assert(!query_set->in_progress);
   if (query_set->in_progress) {
      ast_log(LOG_ERROR, "Attempted to add additional query to query set '%p' after resolution has started\n",
         query_set);
      return -1;
   }

   /*
    * We are intentionally passing NULL for the user data even
    * though dns_query_set_callback() is not NULL tolerant.  Doing
    * this avoids a circular reference chain until the queries are
    * started.  ast_dns_query_set_resolve_async() will set the
    * query user_data for us later when we actually kick off the
    * queries.
    */
   query.query = dns_query_alloc(name, rr_type, rr_class, dns_query_set_callback, NULL);
   if (!query.query) {
      return -1;
   }

   if (AST_VECTOR_APPEND(&query_set->queries, query)) {
      ao2_ref(query.query, -1);
      return -1;
   }

   return 0;
}

ast_dns_query_set_create()

struct ast_dns_query_set* ast_dns_query_set_create

(

void

)

Create a query set to hold queries.

Return values

non-NULL	success
NULL	failure

Note

The query set must be released upon cancellation or completion using ao2_ref

Definition at line 60 of file dns_query_set.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, AST_VECTOR_INIT, dns_query_set_destroy(), DNS_QUERY_SET_EXPECTED_QUERY_COUNT, and NULL.

Referenced by ast_dns_resolve_ipv6_and_ipv4(), query_set_test(), and sip_resolve_add().

{
   struct ast_dns_query_set *query_set;

   query_set = ao2_alloc_options(sizeof(*query_set), dns_query_set_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!query_set) {
      return NULL;
   }

   if (AST_VECTOR_INIT(&query_set->queries, DNS_QUERY_SET_EXPECTED_QUERY_COUNT)) {
      ao2_ref(query_set, -1);
      return NULL;
   }

   return query_set;
}

ast_dns_query_set_get()

struct ast_dns_query* ast_dns_query_set_get	(	const struct ast_dns_query_set *	query_set,
		unsigned int	index
	)

Retrieve a query from a query set.

Parameters

query_set	A DNS query set
index	The index of the query to retrieve

Return values

non-NULL	success
NULL	failure

Note

The returned query is only valid for the lifetime of the query set itself

Definition at line 144 of file dns_query_set.c.

References AST_VECTOR_GET_ADDR, AST_VECTOR_SIZE, NULL, and ast_dns_query_set::queries_completed.

Referenced by ast_dns_resolve_ipv6_and_ipv4(), query_set_test(), and sip_resolve_callback().

{
   /* Only once all queries have been completed can results be retrieved */
   if (query_set->queries_completed != AST_VECTOR_SIZE(&query_set->queries)) {
      return NULL;
   }

   /* If the index exceeds the number of queries... no query for you */
   if (index >= AST_VECTOR_SIZE(&query_set->queries)) {
      return NULL;
   }

   return AST_VECTOR_GET_ADDR(&query_set->queries, index)->query;
}

ast_dns_query_set_get_data()

void* ast_dns_query_set_get_data

(

const struct ast_dns_query_set *

query_set

)

Retrieve user specific data from a query set.

Parameters

query_set

A DNS query set

Returns

user specific data

Definition at line 159 of file dns_query_set.c.

References ast_dns_query_set::user_data.

Referenced by dns_synchronous_resolve_callback(), query_set_callback(), and sip_resolve_callback().

{
   return query_set->user_data;
}

ast_dns_query_set_num_queries()

size_t ast_dns_query_set_num_queries

(

const struct ast_dns_query_set *

query_set

)

Retrieve the number of queries in a query set.

Parameters

query_set

A DNS query set

Returns

the number of queries

Definition at line 139 of file dns_query_set.c.

References AST_VECTOR_SIZE.

Referenced by ast_dns_resolve_ipv6_and_ipv4(), query_set_test(), and sip_resolve_callback().

{
   return AST_VECTOR_SIZE(&query_set->queries);
}

ast_dns_query_set_resolve_async()

void ast_dns_query_set_resolve_async	(	struct ast_dns_query_set *	query_set,
		ast_dns_query_set_callback	callback,
		void *	data
	)

Asynchronously resolve queries in a query set.

Parameters

query_set	The query set
callback	The callback to invoke upon completion
data	User data to make available on the query set

Note

The callback will be invoked when all queries have completed

The user data passed in to this function must be ao2 allocated

Definition at line 164 of file dns_query_set.c.

References ao2_bump, ao2_cleanup, ao2_ref, ast_assert, ast_log, AST_VECTOR_GET_ADDR, AST_VECTOR_SIZE, ast_dns_query::callback, ast_dns_query_set::callback, dns_synchronous_resolve::completed, dns_synchronous_resolve::cond, dns_query_set_callback(), ast_dns_query_set::in_progress, dns_synchronous_resolve::lock, LOG_ERROR, NULL, dns_query_set_query::query, ast_dns_resolver::resolve, ast_dns_query::resolver, dns_query_set_query::started, ast_dns_query::user_data, and ast_dns_query_set::user_data.

Referenced by ast_query_set_resolve(), query_set_test(), sip_resolve(), and sip_resolve_callback().

{
   int idx;

   ast_assert(!query_set->in_progress);
   if (query_set->in_progress) {
      ast_log(LOG_ERROR, "Attempted to start asynchronous resolution of query set '%p' when it has already started\n",
         query_set);
      return;
   }

   query_set->in_progress = 1;
   query_set->callback = callback;
   query_set->user_data = ao2_bump(data);

   /*
    * Bump the query_set ref in case all queries complete
    * before we are done kicking them off.
    */
   ao2_ref(query_set, +1);
   for (idx = 0; idx < AST_VECTOR_SIZE(&query_set->queries); ++idx) {
      struct dns_query_set_query *query = AST_VECTOR_GET_ADDR(&query_set->queries, idx);

      query->query->user_data = ao2_bump(query_set);

      if (!query->query->resolver->resolve(query->query)) {
         query->started = 1;
         continue;
      }

      dns_query_set_callback(query->query);
   }
   if (!idx) {
      /*
       * There were no queries in the set;
       * therefore all queries are "completed".
       * Invoke the final callback.
       */
      query_set->callback(query_set);
      ao2_cleanup(query_set->user_data);
      query_set->user_data = NULL;
   }
   ao2_ref(query_set, -1);
}

ast_dns_query_set_resolve_cancel()

int ast_dns_query_set_resolve_cancel

(

struct ast_dns_query_set *

query_set

)

Cancel an asynchronous DNS query set resolution.

Parameters

query_set

The DNS query set

Return values

0	success (all queries have been cancelled)
-1	failure (some queries could not be cancelled)

Note

If successfully cancelled the callback will not be invoked

Definition at line 265 of file dns_query_set.c.

References AST_VECTOR_GET_ADDR, AST_VECTOR_SIZE, ast_dns_resolver::cancel, dns_query_set_callback(), ast_dns_query_set::queries_cancelled, dns_query_set_query::query, ast_dns_query::resolver, and dns_query_set_query::started.

Referenced by query_set_test().

{
   int idx;
   size_t query_count = AST_VECTOR_SIZE(&query_set->queries);

   for (idx = 0; idx < AST_VECTOR_SIZE(&query_set->queries); ++idx) {
      struct dns_query_set_query *query = AST_VECTOR_GET_ADDR(&query_set->queries, idx);

      if (query->started) {
         if (!query->query->resolver->cancel(query->query)) {
            query_set->queries_cancelled++;
            dns_query_set_callback(query->query);
         }
      } else {
         query_set->queries_cancelled++;
      }
   }

   return (query_set->queries_cancelled == query_count) ? 0 : -1;
}

ast_query_set_resolve()

int ast_query_set_resolve

(

struct ast_dns_query_set *

query_set

)

Synchronously resolve queries in a query set.

Parameters

query_set

The query set

Return values

0	success
-1	failure

Note

This function will return when all queries have been completed

Definition at line 239 of file dns_query_set.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, ast_cond_init, ast_cond_wait, ast_dns_query_set_resolve_async(), ast_mutex_init, ast_mutex_lock, ast_mutex_unlock, dns_synchronous_resolve::completed, dns_synchronous_resolve::cond, dns_synchronous_resolve_callback(), dns_synchronous_resolve_destroy(), dns_synchronous_resolve::lock, and NULL.

Referenced by ast_dns_resolve_ipv6_and_ipv4().

{
   struct dns_synchronous_resolve *synchronous;

   synchronous = ao2_alloc_options(sizeof(*synchronous), dns_synchronous_resolve_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!synchronous) {
      return -1;
   }

   ast_mutex_init(&synchronous->lock);
   ast_cond_init(&synchronous->cond, NULL);

   ast_dns_query_set_resolve_async(query_set, dns_synchronous_resolve_callback, synchronous);

   /* Wait for resolution to complete */
   ast_mutex_lock(&synchronous->lock);
   while (!synchronous->completed) {
      ast_cond_wait(&synchronous->cond, &synchronous->lock);
   }
   ast_mutex_unlock(&synchronous->lock);

   ao2_ref(synchronous, -1);

   return 0;
}