dns_query_set.c File Reference

DNS Query Set API. More...

#include "asterisk.h"
#include "asterisk/vector.h"
#include "asterisk/astobj2.h"
#include "asterisk/utils.h"
#include "asterisk/linkedlists.h"
#include "asterisk/dns_core.h"
#include "asterisk/dns_query_set.h"
#include "asterisk/dns_internal.h"
#include "asterisk/dns_resolver.h"

Include dependency graph for dns_query_set.c:

Go to the source code of this file.

Data Structures
struct	dns_synchronous_resolve
	Structure used for signaling back for synchronous resolution completion. More...

Macros
#define	DNS_QUERY_SET_EXPECTED_QUERY_COUNT   5
	The default number of expected queries to be added to the query set.

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.
struct ast_dns_query_set *	ast_dns_query_set_create (void)
	Create a query set to hold queries.
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.
void *	ast_dns_query_set_get_data (const struct ast_dns_query_set *query_set)
	Retrieve user specific data from a query set.
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.
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.
int	ast_dns_query_set_resolve_cancel (struct ast_dns_query_set *query_set)
	Cancel an asynchronous DNS query set resolution.
int	ast_query_set_resolve (struct ast_dns_query_set *query_set)
	Synchronously resolve queries in a query set.
static void	dns_query_set_callback (const struct ast_dns_query *query)
	Callback invoked upon completion of a DNS query.
static void	dns_query_set_destroy (void *data)
	Destructor for DNS query set.
static void	dns_synchronous_resolve_callback (const struct ast_dns_query_set *query_set)
	Callback used to implement synchronous resolution.
static void	dns_synchronous_resolve_destroy (void *data)
	Destructor for synchronous resolution structure.

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.c.

Macro Definition Documentation

DNS_QUERY_SET_EXPECTED_QUERY_COUNT

#define DNS_QUERY_SET_EXPECTED_QUERY_COUNT   5

The default number of expected queries to be added to the query set.

Definition at line 42 of file dns_query_set.c.

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.

{
    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;
}

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, name, NULL, ast_dns_query_set::queries, and dns_query_set_query::query.

Referenced by ast_dns_resolve_ipv6_and_ipv4(), and query_set_test().

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.

{
    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;
}

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

Referenced by ast_dns_resolve_ipv6_and_ipv4(), and query_set_test().

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.

{
    /* 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;
}

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

Referenced by ast_dns_resolve_ipv6_and_ipv4(), and query_set_test().

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.

{
    return query_set->user_data;
}

References ast_dns_query_set::user_data.

Referenced by dns_synchronous_resolve_callback(), and query_set_callback().

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.

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

References AST_VECTOR_SIZE, and ast_dns_query_set::queries.

Referenced by ast_dns_resolve_ipv6_and_ipv4(), and query_set_test().

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.

{
    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);
}

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

Referenced by ast_query_set_resolve(), and query_set_test().

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.

{
    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;
}

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

Referenced by query_set_test().

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.

{
    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;
}

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().

dns_query_set_callback()

static void dns_query_set_callback ( const struct ast_dns_query *  query )

static

Callback invoked upon completion of a DNS query.

Definition at line 78 of file dns_query_set.c.

{
    struct ast_dns_query_set *query_set = ast_dns_query_get_data(query);
 
    /* The reference count of the query set is bumped here in case this query holds the last reference */
    ao2_ref(query_set, +1);
 
    /* Drop the query set from the query so the query set can be destroyed if this is the last one */
    ao2_cleanup(((struct ast_dns_query *)query)->user_data);
    ((struct ast_dns_query *)query)->user_data = NULL;
 
    if (ast_atomic_fetchadd_int(&query_set->queries_completed, +1) != (AST_VECTOR_SIZE(&query_set->queries) - 1)) {
        ao2_ref(query_set, -1);
        return;
    }
 
    /* All queries have been completed, invoke final callback */
    if (query_set->queries_cancelled != AST_VECTOR_SIZE(&query_set->queries)) {
        query_set->callback(query_set);
    }
 
    ao2_cleanup(query_set->user_data);
    query_set->user_data = NULL;
 
    ao2_ref(query_set, -1);
}

References ao2_cleanup, ao2_ref, ast_atomic_fetchadd_int(), ast_dns_query_get_data(), AST_VECTOR_SIZE, ast_dns_query_set::callback, NULL, ast_dns_query_set::queries, ast_dns_query_set::queries_cancelled, ast_dns_query_set::queries_completed, and ast_dns_query_set::user_data.

Referenced by ast_dns_query_set_add(), ast_dns_query_set_resolve_async(), and ast_dns_query_set_resolve_cancel().

dns_query_set_destroy()

static void dns_query_set_destroy ( void *  data )

static

Destructor for DNS query set.

Definition at line 45 of file dns_query_set.c.

{
    struct ast_dns_query_set *query_set = data;
    int idx;
 
    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);
 
        ao2_ref(query->query, -1);
    }
    AST_VECTOR_FREE(&query_set->queries);
 
    ao2_cleanup(query_set->user_data);
}

References ao2_cleanup, ao2_ref, AST_VECTOR_FREE, AST_VECTOR_GET_ADDR, AST_VECTOR_SIZE, ast_dns_query_set::queries, dns_query_set_query::query, and ast_dns_query_set::user_data.

Referenced by ast_dns_query_set_create().

dns_synchronous_resolve_callback()

static void dns_synchronous_resolve_callback ( const struct ast_dns_query_set *  query_set )

static

Callback used to implement synchronous resolution.

Definition at line 229 of file dns_query_set.c.

{
    struct dns_synchronous_resolve *synchronous = ast_dns_query_set_get_data(query_set);
 
    ast_mutex_lock(&synchronous->lock);
    synchronous->completed = 1;
    ast_cond_signal(&synchronous->cond);
    ast_mutex_unlock(&synchronous->lock);
}

References ast_cond_signal, ast_dns_query_set_get_data(), ast_mutex_lock, ast_mutex_unlock, dns_synchronous_resolve::completed, dns_synchronous_resolve::cond, and dns_synchronous_resolve::lock.

Referenced by ast_query_set_resolve().

dns_synchronous_resolve_destroy()

static void dns_synchronous_resolve_destroy ( void *  data )

static

Destructor for synchronous resolution structure.

Definition at line 220 of file dns_query_set.c.

{
    struct dns_synchronous_resolve *synchronous = data;
 
    ast_mutex_destroy(&synchronous->lock);
    ast_cond_destroy(&synchronous->cond);
}

References ast_cond_destroy, ast_mutex_destroy, dns_synchronous_resolve::cond, and dns_synchronous_resolve::lock.

Referenced by ast_query_set_resolve().