dns_recurring.h File Reference

DNS Recurring Resolution API. More...

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

Go to the source code of this file.

Functions
struct ast_dns_query_recurring *	ast_dns_resolve_recurring (const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data)
	Asynchronously resolve a DNS query, and continue resolving it according to the lowest TTL available. More...
int	ast_dns_resolve_recurring_cancel (struct ast_dns_query_recurring *recurring)
	Cancel an asynchronous recurring DNS resolution. More...

Detailed Description

DNS Recurring Resolution API.

Author

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

Definition in file dns_recurring.h.

Function Documentation

ast_dns_resolve_recurring()

struct ast_dns_query_recurring * ast_dns_resolve_recurring	(	const char *	name,
		int	rr_type,
		int	rr_class,
		ast_dns_resolve_callback	callback,
		void *	data
	)

Asynchronously resolve a DNS query, and continue resolving it according to the lowest TTL available.

Parameters

name	The name of what to resolve
rr_type	Resource record type
rr_class	Resource record class
callback	The callback to invoke upon completion
data	User data to make available on the query

Return values

non-NULL	success - query has been sent for resolution
NULL	failure

Note

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

This query will continue to happen according to the lowest TTL unless cancelled using ast_dns_resolve_recurring_cancel

It is NOT possible for the callback to be invoked concurrently for the query multiple times

The query will occur when the TTL expires, not before. This means that there is a period of time where the previous information can be considered stale.

If the TTL is determined to be 0 (the record specifies 0, or no records exist) this will cease doing a recurring query. It is the responsibility of the caller to resume querying at an interval they determine.

Definition at line 114 of file dns_recurring.c.

{
    struct ast_dns_query_recurring *recurring;
 
    if (ast_strlen_zero(name) || !callback || !ast_dns_get_sched()) {
        return NULL;
    }
 
    recurring = ao2_alloc(sizeof(*recurring) + strlen(name) + 1, dns_query_recurring_destroy);
    if (!recurring) {
        return NULL;
    }
 
    recurring->callback = callback;
    recurring->user_data = ao2_bump(data);
    recurring->timer = -1;
    recurring->rr_type = rr_type;
    recurring->rr_class = rr_class;
    strcpy(recurring->name, name); /* SAFE */
 
    recurring->active = ast_dns_resolve_async(name, rr_type, rr_class, dns_query_recurring_resolution_callback, recurring);
    if (!recurring->active) {
        ao2_ref(recurring, -1);
        return NULL;
    }
 
    return recurring;
}

References ast_dns_query_recurring::active, ao2_alloc, ao2_bump, ao2_ref, ast_dns_get_sched(), ast_dns_resolve_async(), ast_strlen_zero(), ast_dns_query_recurring::callback, dns_query_recurring_destroy(), dns_query_recurring_resolution_callback(), ast_dns_query_recurring::name, name, NULL, ast_dns_query_recurring::rr_class, ast_dns_query_recurring::rr_type, ast_dns_query_recurring::timer, and ast_dns_query_recurring::user_data.

Referenced by AST_TEST_DEFINE(), and rtp_reload().

ast_dns_resolve_recurring_cancel()

int ast_dns_resolve_recurring_cancel

(

struct ast_dns_query_recurring *

recurring

)

Cancel an asynchronous recurring DNS resolution.

Parameters

recurring

The DNS query returned from ast_dns_resolve_recurring

Return values

0	success - any active query has been cancelled and the query will no longer occur
-1	failure - an active query was in progress and could not be cancelled

Note

If successfully cancelled the callback will not be invoked

This function does NOT drop your reference to the recurring query, this should be dropped using ao2_ref

Definition at line 143 of file dns_recurring.c.

{
    int res = 0;
 
    ao2_lock(recurring);
 
    recurring->cancelled = 1;
    AST_SCHED_DEL_UNREF(ast_dns_get_sched(), recurring->timer, ao2_ref(recurring, -1));
 
    if (recurring->active) {
        res = ast_dns_resolve_cancel(recurring->active);
        ao2_replace(recurring->active, NULL);
    }
 
    ao2_unlock(recurring);
 
    return res;
}

References ast_dns_query_recurring::active, ao2_lock, ao2_ref, ao2_replace, ao2_unlock, ast_dns_get_sched(), ast_dns_resolve_cancel(), AST_SCHED_DEL_UNREF, ast_dns_query_recurring::cancelled, NULL, and ast_dns_query_recurring::timer.

Referenced by AST_TEST_DEFINE().