xref: /openbmc/qemu/include/io/dns-resolver.h (revision 8680d6e3)
1 /*
2  * QEMU DNS resolver
3  *
4  * Copyright (c) 2016-2017 Red Hat, Inc.
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 #ifndef QIO_DNS_RESOLVER_H
22 #define QIO_DNS_RESOLVER_H
23 
24 #include "qapi/qapi-types-sockets.h"
25 #include "qom/object.h"
26 #include "io/task.h"
27 
28 #define TYPE_QIO_DNS_RESOLVER "qio-dns-resolver"
29 OBJECT_DECLARE_SIMPLE_TYPE(QIODNSResolver,
30                            QIO_DNS_RESOLVER)
31 
32 
33 /**
34  * QIODNSResolver:
35  *
36  * The QIODNSResolver class provides a framework for doing
37  * DNS resolution on SocketAddress objects, independently
38  * of socket creation.
39  *
40  * <example>
41  *   <title>Resolving addresses synchronously</title>
42  *   <programlisting>
43  *    int mylisten(SocketAddress *addr, Error **errp) {
44  *      QIODNSResolver *resolver = qio_dns_resolver_get_instance();
45  *      SocketAddress **rawaddrs = NULL;
46  *      size_t nrawaddrs = 0;
47  *      Error *err = NULL;
48  *      QIOChannel **socks = NULL;
49  *      size_t nsocks = 0;
50  *
51  *      if (qio_dns_resolver_lookup_sync(dns, addr, &nrawaddrs,
52  *                                       &rawaddrs, errp) < 0) {
53  *          return -1;
54  *      }
55  *
56  *      for (i = 0; i < nrawaddrs; i++) {
57  *         QIOChannel *sock = qio_channel_new();
58  *         Error *local_err = NULL;
59  *         qio_channel_listen_sync(sock, rawaddrs[i], &local_err);
60  *         if (local_err) {
61  *            error_propagate(&err, local_err);
62  *         } else {
63  *            socks = g_renew(QIOChannelSocket *, socks, nsocks + 1);
64  *            socks[nsocks++] = sock;
65  *         }
66  *         qapi_free_SocketAddress(rawaddrs[i]);
67  *      }
68  *      g_free(rawaddrs);
69  *
70  *      if (nsocks == 0) {
71  *         error_propagate(errp, err);
72  *      } else {
73  *         error_free(err);
74  *      }
75  *   }
76  *   </programlisting>
77  * </example>
78  *
79  * <example>
80  *   <title>Resolving addresses asynchronously</title>
81  *   <programlisting>
82  *    typedef struct MyListenData {
83  *       Error *err;
84  *       QIOChannelSocket **socks;
85  *       size_t nsocks;
86  *    } MyListenData;
87  *
88  *    void mylistenresult(QIOTask *task, void *opaque) {
89  *      MyListenData *data = opaque;
90  *      QIODNSResolver *resolver =
91  *         QIO_DNS_RESOLVER(qio_task_get_source(task);
92  *      SocketAddress **rawaddrs = NULL;
93  *      size_t nrawaddrs = 0;
94  *      Error *err = NULL;
95  *
96  *      if (qio_task_propagate_error(task, &data->err)) {
97  *         return;
98  *      }
99  *
100  *      qio_dns_resolver_lookup_result(resolver, task,
101  *                                     &nrawaddrs, &rawaddrs);
102  *
103  *      for (i = 0; i < nrawaddrs; i++) {
104  *         QIOChannel *sock = qio_channel_new();
105  *         Error *local_err = NULL;
106  *         qio_channel_listen_sync(sock, rawaddrs[i], &local_err);
107  *         if (local_err) {
108  *            error_propagate(&err, local_err);
109  *         } else {
110  *            socks = g_renew(QIOChannelSocket *, socks, nsocks + 1);
111  *            socks[nsocks++] = sock;
112  *         }
113  *         qapi_free_SocketAddress(rawaddrs[i]);
114  *      }
115  *      g_free(rawaddrs);
116  *
117  *      if (nsocks == 0) {
118  *         error_propagate(&data->err, err);
119  *      } else {
120  *         error_free(err);
121  *      }
122  *    }
123  *
124  *    void mylisten(SocketAddress *addr, MyListenData *data) {
125  *      QIODNSResolver *resolver = qio_dns_resolver_get_instance();
126  *      qio_dns_resolver_lookup_async(dns, addr,
127  *                                    mylistenresult, data, NULL);
128  *    }
129  *   </programlisting>
130  * </example>
131  */
132 struct QIODNSResolver {
133     Object parent;
134 };
135 
136 
137 
138 /**
139  * qio_dns_resolver_get_instance:
140  *
141  * Get the singleton dns resolver instance. The caller
142  * does not own a reference on the returned object.
143  *
144  * Returns: the single dns resolver instance
145  */
146 QIODNSResolver *qio_dns_resolver_get_instance(void);
147 
148 /**
149  * qio_dns_resolver_lookup_sync:
150  * @resolver: the DNS resolver instance
151  * @addr: the address to resolve
152  * @naddr: pointer to hold number of resolved addresses
153  * @addrs: pointer to hold resolved addresses
154  * @errp: pointer to NULL initialized error object
155  *
156  * This will attempt to resolve the address provided
157  * in @addr. If resolution succeeds, @addrs will be filled
158  * with all the resolved addresses. @naddrs will specify
159  * the number of entries allocated in @addrs. The caller
160  * is responsible for freeing each entry in @addrs, as
161  * well as @addrs itself. @naddrs is guaranteed to be
162  * greater than zero on success.
163  *
164  * DNS resolution will be done synchronously so execution
165  * of the caller may be blocked for an arbitrary length
166  * of time.
167  *
168  * Returns: 0 if resolution was successful, -1 on error
169  */
170 int qio_dns_resolver_lookup_sync(QIODNSResolver *resolver,
171                                  SocketAddress *addr,
172                                  size_t *naddrs,
173                                  SocketAddress ***addrs,
174                                  Error **errp);
175 
176 /**
177  * qio_dns_resolver_lookup_async:
178  * @resolver: the DNS resolver instance
179  * @addr: the address to resolve
180  * @func: the callback to invoke on lookup completion
181  * @opaque: data blob to pass to @func
182  * @notify: the callback to free @opaque, or NULL
183  *
184  * This will attempt to resolve the address provided
185  * in @addr. The callback @func will be invoked when
186  * resolution has either completed or failed. On
187  * success, the @func should call the method
188  * qio_dns_resolver_lookup_result() to obtain the
189  * results.
190  *
191  * DNS resolution will be done asynchronously so execution
192  * of the caller will not be blocked.
193  */
194 void qio_dns_resolver_lookup_async(QIODNSResolver *resolver,
195                                    SocketAddress *addr,
196                                    QIOTaskFunc func,
197                                    gpointer opaque,
198                                    GDestroyNotify notify);
199 
200 /**
201  * qio_dns_resolver_lookup_result:
202  * @resolver: the DNS resolver instance
203  * @task: the task object to get results for
204  * @naddr: pointer to hold number of resolved addresses
205  * @addrs: pointer to hold resolved addresses
206  *
207  * This method should be called from the callback passed
208  * to qio_dns_resolver_lookup_async() in order to obtain
209  * results.  @addrs will be filled with all the resolved
210  * addresses. @naddrs will specify the number of entries
211  * allocated in @addrs. The caller is responsible for
212  * freeing each entry in @addrs, as well as @addrs itself.
213  */
214 void qio_dns_resolver_lookup_result(QIODNSResolver *resolver,
215                                     QIOTask *task,
216                                     size_t *naddrs,
217                                     SocketAddress ***addrs);
218 
219 #endif /* QIO_DNS_RESOLVER_H */
220