Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
dns_resolver.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2015, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief DNS Resolver API
21  * \author Joshua Colp <jcolp@digium.com>
22  */
23 
24 #ifndef _ASTERISK_DNS_RESOLVER_H
25 #define _ASTERISK_DNS_RESOLVER_H
26 
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30 
31 /*! \brief DNS resolver implementation */
33  /*! \brief The name of the resolver implementation */
34  const char *name;
35 
36  /*! \brief Priority for this resolver if multiple exist, lower being higher priority */
37  unsigned int priority;
38 
39  /*!
40  * \brief Perform resolution of a DNS query
41  *
42  * \note The reference count of the query should be increased and released
43  * upon the query completing or being successfully cancelled
44  */
45  int (*resolve)(struct ast_dns_query *query);
46 
47  /*! \brief Cancel resolution of a DNS query */
48  int (*cancel)(struct ast_dns_query *query);
49 
50  /*! \brief Linked list information */
52 };
53 
54 /*!
55  * \brief Set resolver specific data on a query
56  *
57  * \param query The DNS query
58  * \param data The resolver specific data
59  *
60  * \note The resolver data MUST be an ao2 object
61  *
62  * \note This function increments the reference count of the resolver data, it does NOT steal
63  *
64  * \note Once resolver specific data has been set it can not be changed
65  *
66  * \retval 0 success
67  * \retval -1 failure, resolver data is already set
68  */
69 int ast_dns_resolver_set_data(struct ast_dns_query *query, void *data);
70 
71 /*!
72  * \brief Retrieve resolver specific data
73  *
74  * \param query The DNS query
75  *
76  * \return the resolver specific data
77  *
78  * \note The reference count of the resolver data is NOT incremented on return
79  */
80 void *ast_dns_resolver_get_data(const struct ast_dns_query *query);
81 
82 /*!
83  * \brief Set result information for a DNS query
84  *
85  * \param query The DNS query
86  * \param result Whether the result is secured or not
87  * \param bogus Whether the result is bogus or not
88  * \param rcode Optional response code
89  * \param canonical The canonical name
90  * \param answer The raw DNS answer
91  * \param answer_size The size of the raw DNS answer
92  *
93  * Zero-sized and NULL answers are permitted by this function. This may be
94  * necessary if the query fails at an early stage and no actual DNS response
95  * has been received from a DNS server.
96  *
97  * \retval 0 success
98  * \retval -1 failure
99  */
100 int ast_dns_resolver_set_result(struct ast_dns_query *query, unsigned int secure, unsigned int bogus,
101  unsigned int rcode, const char *canonical, const char *answer, size_t answer_size);
102 
103 /*!
104  * \brief Add a DNS record to the result of a DNS query
105  *
106  * \param query The DNS query
107  * \param rr_type Resource record type
108  * \param rr_class Resource record class
109  * \param ttl TTL of the record
110  * \param data The raw DNS record
111  * \param size The size of the raw DNS record
112  *
113  * \retval 0 success
114  * \retval -1 failure
115  */
116 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);
117 
118 /*!
119  * \brief Mark a DNS query as having been completed
120  *
121  * \param query The DNS query
122  */
123 void ast_dns_resolver_completed(struct ast_dns_query *query);
124 
125 /*!
126  * \brief Register a DNS resolver
127  *
128  * \param resolver A DNS resolver implementation
129  *
130  * \retval 0 success
131  * \retval -1 failure
132  */
134 
135 /*!
136  * \brief Unregister a DNS resolver
137  *
138  * \param resolver A DNS resolver implementation
139  */
141 
142 #if defined(__cplusplus) || defined(c_plusplus)
143 }
144 #endif
145 
146 #endif /* _ASTERISK_DNS_RESOLVER_H */
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.
Definition: dns_core.c:535
void ast_dns_resolver_unregister(struct ast_dns_resolver *resolver)
Unregister a DNS resolver.
Definition: dns_core.c:680
int rr_type
Resource record type.
Definition: dns_internal.h:149
int rr_class
Resource record class.
Definition: dns_internal.h:151
AST_RWLIST_ENTRY(ast_dns_resolver) next
Linked list information.
void * ast_dns_resolver_get_data(const struct ast_dns_query *query)
Retrieve resolver specific data.
Definition: dns_core.c:451
const char * name
The name of the resolver implementation.
Definition: dns_resolver.h:34
int ast_dns_resolver_register(struct ast_dns_resolver *resolver)
Register a DNS resolver.
Definition: dns_core.c:630
static int answer(void *data)
Definition: chan_pjsip.c:682
void ast_dns_resolver_completed(struct ast_dns_query *query)
Mark a DNS query as having been completed.
Definition: dns_core.c:599
int ast_dns_resolver_set_data(struct ast_dns_query *query, void *data)
Set resolver specific data on a query.
Definition: dns_core.c:440
int(* resolve)(struct ast_dns_query *query)
Perform resolution of a DNS query.
Definition: dns_resolver.h:45
DNS resolver implementation.
Definition: dns_resolver.h:32
A DNS query.
Definition: dns_internal.h:137
unsigned int priority
Priority for this resolver if multiple exist, lower being higher priority.
Definition: dns_resolver.h:37
struct ast_dns_resolver * resolver
The resolver in use for this query.
Definition: dns_internal.h:143
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.
Definition: dns_core.c:456
int(* cancel)(struct ast_dns_query *query)
Cancel resolution of a DNS query.
Definition: dns_resolver.h:48