Asterisk - The Open Source Telephony Project GIT-master-2de1a68
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)
28extern "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 */
69int 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 */
80void *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 secure 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 */
100int 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 */
116int 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 */
123void 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 */
static int answer(void *data)
Definition: chan_pjsip.c:683
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 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
void ast_dns_resolver_completed(struct ast_dns_query *query)
Mark a DNS query as having been completed.
Definition: dns_core.c:599
void * ast_dns_resolver_get_data(const struct ast_dns_query *query)
Retrieve resolver specific data.
Definition: dns_core.c:451
int ast_dns_resolver_register(struct ast_dns_resolver *resolver)
Register a DNS resolver.
Definition: dns_core.c:630
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
A DNS query.
Definition: dns_internal.h:137
struct ast_dns_resolver * resolver
The resolver in use for this query.
Definition: dns_internal.h:143
int rr_class
Resource record class.
Definition: dns_internal.h:151
int rr_type
Resource record type.
Definition: dns_internal.h:149
DNS resolver implementation.
Definition: dns_resolver.h:32
unsigned int priority
Priority for this resolver if multiple exist, lower being higher priority.
Definition: dns_resolver.h:37
int(* cancel)(struct ast_dns_query *query)
Cancel resolution of a DNS query.
Definition: dns_resolver.h:48
const char * name
The name of the resolver implementation.
Definition: dns_resolver.h:34
int(* resolve)(struct ast_dns_query *query)
Perform resolution of a DNS query.
Definition: dns_resolver.h:45
AST_RWLIST_ENTRY(ast_dns_resolver) next
Linked list information.