dns_core.h File Reference

Core DNS 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_resolve_callback )(const struct ast_dns_query *query)
 Callback invoked when a query completes.

Functions

void * ast_dns_query_get_data (const struct ast_dns_query *query)
 Get the user specific data of a DNS query.
const char * ast_dns_query_get_name (const struct ast_dns_query *query)
 Get the name queried in a DNS query.
struct ast_dns_resultast_dns_query_get_result (const struct ast_dns_query *query)
 Get the result information for a DNS query.
int ast_dns_query_get_rr_class (const struct ast_dns_query *query)
 Get the record resource class of a DNS query.
int ast_dns_query_get_rr_type (const struct ast_dns_query *query)
 Get the record resource type of a DNS query.
const char * ast_dns_record_get_data (const struct ast_dns_record *record)
 Retrieve the raw DNS record.
struct ast_dns_recordast_dns_record_get_next (const struct ast_dns_record *record)
 Get the next DNS record.
int ast_dns_record_get_rr_class (const struct ast_dns_record *record)
 Get the resource record class of a DNS record.
int ast_dns_record_get_rr_type (const struct ast_dns_record *record)
 Get the resource record type of a DNS record.
int ast_dns_record_get_ttl (const struct ast_dns_record *record)
 Get the TTL of a DNS record.
int ast_dns_resolve (const char *name, int rr_type, int rr_class, struct ast_dns_result **result)
 Synchronously resolve a DNS query.
struct ast_dns_query_activeast_dns_resolve_async (const char *name, int rr_type, int rr_class, ast_dns_resolve_callback callback, void *data)
 Asynchronously resolve a DNS query.
int ast_dns_resolve_cancel (struct ast_dns_query_active *active)
 Cancel an asynchronous DNS resolution.
void ast_dns_result_free (struct ast_dns_result *result)
 Free the DNS result information.
const char * ast_dns_result_get_answer (const struct ast_dns_result *result)
 Get the raw DNS answer from a DNS result.
unsigned int ast_dns_result_get_bogus (const struct ast_dns_result *result)
 Get whether the result is bogus or not.
const char * ast_dns_result_get_canonical (const struct ast_dns_result *result)
 Get the canonical name of the result.
int ast_dns_result_get_lowest_ttl (const struct ast_dns_result *result)
 Retrieve the lowest TTL from a result.
unsigned int ast_dns_result_get_rcode (const struct ast_dns_result *result)
 Get the error rcode of a DN result.
struct ast_dns_recordast_dns_result_get_records (const struct ast_dns_result *result)
 Get the first record of a DNS Result.
unsigned int ast_dns_result_get_secure (const struct ast_dns_result *result)
 Get whether the result is secure or not.


Detailed Description

Core DNS API.

Author:
Joshua Colp <jcolp@digium.com>

Definition in file dns_core.h.


Typedef Documentation

typedef void(* ast_dns_resolve_callback)(const struct ast_dns_query *query)

Callback invoked when a query completes.

Parameters:
query The DNS query that was invoked

Definition at line 169 of file dns_core.h.


Function Documentation

void* ast_dns_query_get_data ( const struct ast_dns_query query  ) 

Get the user specific data of a DNS query.

Parameters:
query The DNS query
Returns:
the user specific data
Note:
The reference count of the data is NOT incremented on return

Definition at line 73 of file dns_core.c.

References ast_dns_query::user_data.

Referenced by async_callback(), dns_query_recurring_resolution_callback(), dns_synchronous_resolve_callback(), recurring_cancel(), recurring_resolve(), and resolution_thread().

00074 {
00075    return query->user_data;
00076 }

const char* ast_dns_query_get_name ( const struct ast_dns_query query  ) 

Get the name queried in a DNS query.

Parameters:
query The DNS query
Returns:
the name queried

Definition at line 58 of file dns_core.c.

References ast_dns_query::name.

Referenced by unbound_resolver_callback(), and unbound_resolver_resolve().

00059 {
00060    return query->name;
00061 }

struct ast_dns_result* ast_dns_query_get_result ( const struct ast_dns_query query  )  [read]

Get the result information for a DNS query.

Parameters:
query The DNS query
Returns:
the DNS result information
Note:
The result is NOT ao2 allocated

Definition at line 78 of file dns_core.c.

References ast_dns_query::result.

Referenced by AST_TEST_DEFINE(), dns_query_recurring_resolution_callback(), and test_results().

00079 {
00080    return query->result;
00081 }

int ast_dns_query_get_rr_class ( const struct ast_dns_query query  ) 

Get the record resource class of a DNS query.

Parameters:
query The DNS query
Returns:
the record resource class

Definition at line 68 of file dns_core.c.

References ast_dns_query::rr_class.

Referenced by unbound_resolver_resolve().

00069 {
00070    return query->rr_class;
00071 }

int ast_dns_query_get_rr_type ( const struct ast_dns_query query  ) 

Get the record resource type of a DNS query.

Parameters:
query The DNS query
Returns:
the record resource type

Definition at line 63 of file dns_core.c.

References ast_dns_query::rr_type.

Referenced by ast_dns_resolver_completed(), and unbound_resolver_resolve().

00064 {
00065    return query->rr_type;
00066 }

const char* ast_dns_record_get_data ( const struct ast_dns_record record  ) 

Retrieve the raw DNS record.

Parameters:
record The DNS record
Returns:
the raw DNS record

Definition at line 161 of file dns_core.c.

References ast_dns_record::data_ptr.

Referenced by test_record().

00162 {
00163    return record->data_ptr;
00164 }

struct ast_dns_record* ast_dns_record_get_next ( const struct ast_dns_record record  )  [read]

Get the next DNS record.

Parameters:
record The current DNS record
Returns:
the next DNS record

Definition at line 166 of file dns_core.c.

References AST_LIST_NEXT.

Referenced by ast_dns_result_get_lowest_ttl(), AST_TEST_DEFINE(), and nominal_test().

00167 {
00168    return AST_LIST_NEXT(record, list);
00169 }

int ast_dns_record_get_rr_class ( const struct ast_dns_record record  ) 

Get the resource record class of a DNS record.

Parameters:
record The DNS record
Returns:
the resource record class

Definition at line 151 of file dns_core.c.

References ast_dns_record::rr_class.

Referenced by test_record().

00152 {
00153    return record->rr_class;
00154 }

int ast_dns_record_get_rr_type ( const struct ast_dns_record record  ) 

Get the resource record type of a DNS record.

Parameters:
record The DNS record
Returns:
the resource record type

Definition at line 146 of file dns_core.c.

References ast_dns_record::rr_type.

Referenced by ast_dns_naptr_get_flags(), ast_dns_naptr_get_order(), ast_dns_naptr_get_preference(), ast_dns_naptr_get_regexp(), ast_dns_naptr_get_replacement(), ast_dns_naptr_get_service(), ast_dns_srv_get_host(), ast_dns_srv_get_port(), ast_dns_srv_get_priority(), ast_dns_srv_get_weight(), AST_TEST_DEFINE(), and test_record().

00147 {
00148    return record->rr_type;
00149 }

int ast_dns_record_get_ttl ( const struct ast_dns_record record  ) 

Get the TTL of a DNS record.

Parameters:
record The DNS record
Returns:
the TTL

Definition at line 156 of file dns_core.c.

References ast_dns_record::ttl.

Referenced by ast_dns_result_get_lowest_ttl(), and test_record().

00157 {
00158    return record->ttl;
00159 }

int ast_dns_resolve ( const char *  name,
int  rr_type,
int  rr_class,
struct ast_dns_result **  result 
)

Synchronously resolve a DNS query.

Parameters:
name The name of what to resolve
rr_type Resource record type
rr_class Resource record class
result A pointer to hold the DNS result
Return values:
0 success - query was completed and result is available
-1 failure

Definition at line 298 of file dns_core.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, ast_cond_init, ast_cond_wait, ast_dns_resolve_async(), ast_log, ast_mutex_init, ast_mutex_lock, ast_mutex_unlock, ast_strlen_zero, dns_synchronous_resolve::completed, dns_synchronous_resolve::cond, dns_synchronous_resolve_callback(), dns_synchronous_resolve_destroy(), dns_synchronous_resolve::lock, LOG_WARNING, NULL, and dns_synchronous_resolve::result.

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

00299 {
00300    struct dns_synchronous_resolve *synchronous;
00301    struct ast_dns_query_active *active;
00302 
00303    if (ast_strlen_zero(name)) {
00304       ast_log(LOG_WARNING, "Could not perform synchronous resolution, no name provided\n");
00305       return -1;
00306    } else if (rr_type > ns_t_max) {
00307       ast_log(LOG_WARNING, "Could not perform synchronous resolution of '%s', resource record type '%d' exceeds maximum\n",
00308          name, rr_type);
00309       return -1;
00310    } else if (rr_type < 0) {
00311       ast_log(LOG_WARNING, "Could not perform synchronous resolution of '%s', invalid resource record type '%d'\n",
00312          name, rr_type);
00313       return -1;
00314    } else if (rr_class > ns_c_max) {
00315       ast_log(LOG_WARNING, "Could not perform synchronous resolution of '%s', resource record class '%d' exceeds maximum\n",
00316          name, rr_class);
00317       return -1;
00318    } else if (rr_class < 0) {
00319       ast_log(LOG_WARNING, "Could not perform synchronous resolution of '%s', invalid resource class '%d'\n",
00320          name, rr_class);
00321       return -1;
00322    } else if (!result) {
00323       ast_log(LOG_WARNING, "Could not perform synchronous resolution of '%s', no result pointer provided for storing results\n",
00324          name);
00325       return -1;
00326    }
00327 
00328    synchronous = ao2_alloc_options(sizeof(*synchronous), dns_synchronous_resolve_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
00329    if (!synchronous) {
00330       return -1;
00331    }
00332 
00333    ast_mutex_init(&synchronous->lock);
00334    ast_cond_init(&synchronous->cond, NULL);
00335 
00336    active = ast_dns_resolve_async(name, rr_type, rr_class, dns_synchronous_resolve_callback, synchronous);
00337    if (active) {
00338       /* Wait for resolution to complete */
00339       ast_mutex_lock(&synchronous->lock);
00340       while (!synchronous->completed) {
00341          ast_cond_wait(&synchronous->cond, &synchronous->lock);
00342       }
00343       ast_mutex_unlock(&synchronous->lock);
00344       ao2_ref(active, -1);
00345    }
00346 
00347    *result = synchronous->result;
00348    ao2_ref(synchronous, -1);
00349 
00350    return *result ? 0 : -1;
00351 }

struct ast_dns_query_active* ast_dns_resolve_async ( const char *  name,
int  rr_type,
int  rr_class,
ast_dns_resolve_callback  callback,
void *  data 
) [read]

Asynchronously resolve a DNS query.

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 result passed to the callback does not need to be freed

The user data MUST be an ao2 object

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

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

Definition at line 189 of file dns_core.c.

References AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_bump, ao2_ref, ast_log, AST_RWLIST_FIRST, AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, ast_strlen_zero, ast_dns_query::callback, dns_query_active_destroy(), dns_query_destroy(), LOG_ERROR, LOG_WARNING, ast_dns_resolver::name, ast_dns_query::name, NULL, ast_dns_query_active::query, ast_dns_resolver::resolve, ast_dns_query::resolver, ast_dns_query::rr_class, ast_dns_query::rr_type, and ast_dns_query::user_data.

Referenced by ast_dns_resolve(), ast_dns_resolve_recurring(), AST_TEST_DEFINE(), and dns_query_recurring_scheduled_callback().

00190 {
00191    struct ast_dns_query_active *active;
00192 
00193    if (ast_strlen_zero(name)) {
00194       ast_log(LOG_WARNING, "Could not perform asynchronous resolution, no name provided\n");
00195       return NULL;
00196    } else if (rr_type > ns_t_max) {
00197       ast_log(LOG_WARNING, "Could not perform asynchronous resolution of '%s', resource record type '%d' exceeds maximum\n",
00198          name, rr_type);
00199       return NULL;
00200    } else if (rr_type < 0) {
00201       ast_log(LOG_WARNING, "Could not perform asynchronous resolution of '%s', invalid resource record type '%d'\n",
00202          name, rr_type);
00203       return NULL;
00204    } else if (rr_class > ns_c_max) {
00205       ast_log(LOG_WARNING, "Could not perform asynchronous resolution of '%s', resource record class '%d' exceeds maximum\n",
00206          name, rr_class);
00207       return NULL;
00208    } else if (rr_class < 0) {
00209       ast_log(LOG_WARNING, "Could not perform asynchronous resolution of '%s', invalid resource class '%d'\n",
00210          name, rr_class);
00211       return NULL;
00212    } else if (!callback) {
00213       ast_log(LOG_WARNING, "Could not perform asynchronous resolution of '%s', no callback provided\n",
00214          name);
00215       return NULL;
00216    }
00217 
00218    active = ao2_alloc_options(sizeof(*active), dns_query_active_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
00219    if (!active) {
00220       return NULL;
00221    }
00222 
00223    active->query = ao2_alloc_options(sizeof(*active->query) + strlen(name) + 1, dns_query_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
00224    if (!active->query) {
00225       ao2_ref(active, -1);
00226       return NULL;
00227    }
00228 
00229    active->query->callback = callback;
00230    active->query->user_data = ao2_bump(data);
00231    active->query->rr_type = rr_type;
00232    active->query->rr_class = rr_class;
00233    strcpy(active->query->name, name); /* SAFE */
00234 
00235    AST_RWLIST_RDLOCK(&resolvers);
00236    active->query->resolver = AST_RWLIST_FIRST(&resolvers);
00237    AST_RWLIST_UNLOCK(&resolvers);
00238 
00239    if (!active->query->resolver) {
00240       ast_log(LOG_ERROR, "Attempted to do a DNS query for '%s' of class '%d' and type '%d' but no resolver is available\n",
00241          name, rr_class, rr_type);
00242       ao2_ref(active, -1);
00243       return NULL;
00244    }
00245 
00246    if (active->query->resolver->resolve(active->query)) {
00247       ast_log(LOG_ERROR, "Resolver '%s' returned an error when resolving '%s' of class '%d' and type '%d'\n",
00248          active->query->resolver->name, name, rr_class, rr_type);
00249       ao2_ref(active, -1);
00250       return NULL;
00251    }
00252 
00253    return active;
00254 }

int ast_dns_resolve_cancel ( struct ast_dns_query_active active  ) 

Cancel an asynchronous DNS resolution.

Parameters:
active The active DNS query returned from ast_dns_resolve_async
Return values:
0 success
-1 failure
Note:
If successfully cancelled the callback will not be invoked

Definition at line 256 of file dns_core.c.

References ast_dns_resolver::cancel, ast_dns_query_active::query, and ast_dns_query::resolver.

Referenced by ast_dns_resolve_recurring_cancel(), and AST_TEST_DEFINE().

00257 {
00258    return active->query->resolver->cancel(active->query);
00259 }

void ast_dns_result_free ( struct ast_dns_result result  ) 

Free the DNS result information.

Parameters:
result The DNS result

Definition at line 131 of file dns_core.c.

References ast_free, and AST_LIST_REMOVE_HEAD.

Referenced by ast_dns_resolver_set_result(), AST_TEST_DEFINE(), dns_query_destroy(), invalid_record_test(), nominal_test(), and off_nominal_test().

00132 {
00133    struct ast_dns_record *record;
00134 
00135    if (!result) {
00136       return;
00137    }
00138 
00139    while ((record = AST_LIST_REMOVE_HEAD(&result->records, list))) {
00140       ast_free(record);
00141    }
00142 
00143    ast_free(result);
00144 }

const char* ast_dns_result_get_answer ( const struct ast_dns_result result  ) 

Get the raw DNS answer from a DNS result.

Parameters:
result The DNS result
Returns:
The DNS result

Definition at line 108 of file dns_core.c.

References ast_dns_result::answer.

Referenced by test_results().

00109 {
00110    return result->answer;
00111 }

unsigned int ast_dns_result_get_bogus ( const struct ast_dns_result result  ) 

Get whether the result is bogus or not.

Parameters:
result The DNS result
Returns:
whether the result is bogus or not

Definition at line 88 of file dns_core.c.

References ast_dns_result::bogus.

Referenced by test_results().

00089 {
00090    return result->bogus;
00091 }

const char* ast_dns_result_get_canonical ( const struct ast_dns_result result  ) 

Get the canonical name of the result.

Parameters:
result The DNS result
Returns:
the canonical name

Definition at line 98 of file dns_core.c.

References ast_dns_result::canonical.

Referenced by test_results().

00099 {
00100    return result->canonical;
00101 }

int ast_dns_result_get_lowest_ttl ( const struct ast_dns_result result  ) 

Retrieve the lowest TTL from a result.

Parameters:
result The DNS result
Returns:
the lowest TTL
Note:
If no records exist this function will return a TTL of 0

Definition at line 113 of file dns_core.c.

References ast_dns_record_get_next(), ast_dns_record_get_ttl(), ast_dns_result_get_rcode(), ast_dns_result_get_records(), and ast_dns_record::ttl.

Referenced by dns_query_recurring_resolution_callback().

00114 {
00115    int ttl = 0;
00116    const struct ast_dns_record *record;
00117 
00118    if (ast_dns_result_get_rcode(result) == ns_r_nxdomain) {
00119       return 0;
00120    }
00121 
00122    for (record = ast_dns_result_get_records(result); record; record = ast_dns_record_get_next(record)) {
00123       if (!ttl || (ast_dns_record_get_ttl(record) && (ast_dns_record_get_ttl(record) < ttl))) {
00124          ttl = ast_dns_record_get_ttl(record);
00125       }
00126    }
00127 
00128    return ttl;
00129 }

unsigned int ast_dns_result_get_rcode ( const struct ast_dns_result result  ) 

Get the error rcode of a DN result.

Parameters:
query The DNS result
Returns:
the DNS rcode

Definition at line 93 of file dns_core.c.

References ast_dns_result::rcode.

Referenced by ast_dns_result_get_lowest_ttl(), and test_results().

00094 {
00095    return result->rcode;
00096 }

struct ast_dns_record* ast_dns_result_get_records ( const struct ast_dns_result result  )  [read]

Get the first record of a DNS Result.

Parameters:
result The DNS result
Returns:
first DNS record

Definition at line 103 of file dns_core.c.

References AST_LIST_FIRST.

Referenced by ast_dns_result_get_lowest_ttl(), AST_TEST_DEFINE(), invalid_record_test(), nominal_test(), and off_nominal_test().

00104 {
00105    return AST_LIST_FIRST(&result->records);
00106 }

unsigned int ast_dns_result_get_secure ( const struct ast_dns_result result  ) 

Get whether the result is secure or not.

Parameters:
result The DNS result
Returns:
whether the result is secure or not

Definition at line 83 of file dns_core.c.

References ast_dns_result::secure.

Referenced by test_results().

00084 {
00085    return result->secure;
00086 }


Generated on Thu Apr 16 06:30:42 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6