summaryrefslogtreecommitdiffstats
path: root/include/io
diff options
context:
space:
mode:
authorDaniel P. Berrange2016-07-19 13:54:47 +0200
committerDaniel P. Berrange2017-01-23 16:32:46 +0100
commitc1b412f1d94ba717896f876dbf59fffa91e596fc (patch)
tree74603d5bd4f1bbe41cd974d22b79c6bba377604b /include/io
parentio: remove Error parameter from QIOTask thread worker (diff)
downloadqemu-c1b412f1d94ba717896f876dbf59fffa91e596fc.tar.gz
qemu-c1b412f1d94ba717896f876dbf59fffa91e596fc.tar.xz
qemu-c1b412f1d94ba717896f876dbf59fffa91e596fc.zip
io: introduce a DNS resolver API
Currently DNS resolution is done automatically as part of the creation of a QIOChannelSocket object instance. This works ok for network clients where you just end up a single network socket, but for servers, the results of DNS resolution may require creation of multiple sockets. Introducing a DNS resolver API allows DNS resolution to be separated from the socket object creation. This will make it practical to create multiple QIOChannelSocket instances for servers. Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Diffstat (limited to 'include/io')
-rw-r--r--include/io/dns-resolver.h228
1 files changed, 228 insertions, 0 deletions
diff --git a/include/io/dns-resolver.h b/include/io/dns-resolver.h
new file mode 100644
index 0000000000..2f69c08c13
--- /dev/null
+++ b/include/io/dns-resolver.h
@@ -0,0 +1,228 @@
+/*
+ * QEMU DNS resolver
+ *
+ * Copyright (c) 2016-2017 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#ifndef QIO_DNS_RESOLVER_H
+#define QIO_DNS_RESOLVER_H
+
+#include "qemu-common.h"
+#include "qom/object.h"
+#include "io/task.h"
+
+#define TYPE_QIO_DNS_RESOLVER "qio-dns-resolver"
+#define QIO_DNS_RESOLVER(obj) \
+ OBJECT_CHECK(QIODNSResolver, (obj), TYPE_QIO_DNS_RESOLVER)
+#define QIO_DNS_RESOLVER_CLASS(klass) \
+ OBJECT_CLASS_CHECK(QIODNSResolverClass, klass, TYPE_QIO_DNS_RESOLVER)
+#define QIO_DNS_RESOLVER_GET_CLASS(obj) \
+ OBJECT_GET_CLASS(QIODNSResolverClass, obj, TYPE_QIO_DNS_RESOLVER)
+
+typedef struct QIODNSResolver QIODNSResolver;
+typedef struct QIODNSResolverClass QIODNSResolverClass;
+
+/**
+ * QIODNSResolver:
+ *
+ * The QIODNSResolver class provides a framework for doing
+ * DNS resolution on SocketAddress objects, independently
+ * of socket creation.
+ *
+ * <example>
+ * <title>Resolving addresses synchronously</title>
+ * <programlisting>
+ * int mylisten(SocketAddress *addr, Error **errp) {
+ * QIODNSResolver *resolver = qio_dns_resolver_get_instance();
+ * SocketAddress **rawaddrs = NULL;
+ * size_t nrawaddrs = 0;
+ * Error *err = NULL;
+ * QIOChannel **socks = NULL;
+ * size_t nsocks = 0;
+ *
+ * if (qio_dns_resolver_lookup_sync(dns, addr, &nrawaddrs,
+ * &rawaddrs, errp) < 0) {
+ * return -1;
+ * }
+ *
+ * for (i = 0; i < nrawaddrs; i++) {
+ * QIOChannel *sock = qio_channel_new();
+ * Error *local_err = NULL;
+ * qio_channel_listen_sync(sock, rawaddrs[i], &local_err);
+ * if (local_err) {
+ * error_propagate(&err, local_err);
+ * } else {
+ * socks = g_renew(QIOChannelSocket *, socks, nsocks + 1);
+ * socks[nsocks++] = sock;
+ * }
+ * qapi_free_SocketAddress(rawaddrs[i]);
+ * }
+ * g_free(rawaddrs);
+ *
+ * if (nsocks == 0) {
+ * error_propagate(errp, err);
+ * } else {
+ * error_free(err);
+ * }
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * <example>
+ * <title>Resolving addresses asynchronously</title>
+ * <programlisting>
+ * typedef struct MyListenData {
+ * Error *err;
+ * QIOChannelSocket **socks;
+ * size_t nsocks;
+ * } MyListenData;
+ *
+ * void mylistenresult(QIOTask *task, void *opaque) {
+ * MyListenData *data = opaque;
+ * QIODNSResolver *resolver =
+ * QIO_DNS_RESOLVER(qio_task_get_source(task);
+ * SocketAddress **rawaddrs = NULL;
+ * size_t nrawaddrs = 0;
+ * Error *err = NULL;
+ *
+ * if (qio_task_propagate_error(task, &data->err)) {
+ * return;
+ * }
+ *
+ * qio_dns_resolver_lookup_result(resolver, task,
+ * &nrawaddrs, &rawaddrs);
+ *
+ * for (i = 0; i < nrawaddrs; i++) {
+ * QIOChannel *sock = qio_channel_new();
+ * Error *local_err = NULL;
+ * qio_channel_listen_sync(sock, rawaddrs[i], &local_err);
+ * if (local_err) {
+ * error_propagate(&err, local_err);
+ * } else {
+ * socks = g_renew(QIOChannelSocket *, socks, nsocks + 1);
+ * socks[nsocks++] = sock;
+ * }
+ * qapi_free_SocketAddress(rawaddrs[i]);
+ * }
+ * g_free(rawaddrs);
+ *
+ * if (nsocks == 0) {
+ * error_propagate(&data->err, err);
+ * } else {
+ * error_free(err);
+ * }
+ * }
+ *
+ * void mylisten(SocketAddress *addr, MyListenData *data) {
+ * QIODNSResolver *resolver = qio_dns_resolver_get_instance();
+ * qio_dns_resolver_lookup_async(dns, addr,
+ * mylistenresult, data, NULL);
+ * }
+ * </programlisting>
+ * </example>
+ */
+struct QIODNSResolver {
+ Object parent;
+};
+
+struct QIODNSResolverClass {
+ ObjectClass parent;
+};
+
+
+/**
+ * qio_dns_resolver_get_instance:
+ *
+ * Get the singleton dns resolver instance. The caller
+ * does not own a reference on the returned object.
+ *
+ * Returns: the single dns resolver instance
+ */
+QIODNSResolver *qio_dns_resolver_get_instance(void);
+
+/**
+ * qio_dns_resolver_lookup_sync:
+ * @resolver: the DNS resolver instance
+ * @addr: the address to resolve
+ * @naddr: pointer to hold number of resolved addresses
+ * @addrs: pointer to hold resolved addresses
+ * @errp: pointer to NULL initialized error object
+ *
+ * This will attempt to resolve the address provided
+ * in @addr. If resolution succeeds, @addrs will be filled
+ * with all the resolved addresses. @naddrs will specify
+ * the number of entries allocated in @addrs. The caller
+ * is responsible for freeing each entry in @addrs, as
+ * well as @addrs itself. @naddrs is guaranteed to be
+ * greater than zero on success.
+ *
+ * DNS resolution will be done synchronously so execution
+ * of the caller may be blocked for an arbitrary length
+ * of time.
+ *
+ * Returns: 0 if resolution was successful, -1 on error
+ */
+int qio_dns_resolver_lookup_sync(QIODNSResolver *resolver,
+ SocketAddress *addr,
+ size_t *naddrs,
+ SocketAddress ***addrs,
+ Error **errp);
+
+/**
+ * qio_dns_resolver_lookup_async:
+ * @resolver: the DNS resolver instance
+ * @addr: the address to resolve
+ * @func: the callback to invoke on lookup completion
+ * @opaque: data blob to pass to @func
+ * @notify: the callback to free @opaque, or NULL
+ *
+ * This will attempt to resolve the address provided
+ * in @addr. The callback @func will be invoked when
+ * resolution has either completed or failed. On
+ * success, the @func should call the method
+ * qio_dns_resolver_lookup_result() to obtain the
+ * results.
+ *
+ * DNS resolution will be done asynchronously so execution
+ * of the caller will not be blocked.
+ */
+void qio_dns_resolver_lookup_async(QIODNSResolver *resolver,
+ SocketAddress *addr,
+ QIOTaskFunc func,
+ gpointer opaque,
+ GDestroyNotify notify);
+
+/**
+ * qio_dns_resolver_lookup_result:
+ * @resolver: the DNS resolver instance
+ * @task: the task object to get results for
+ * @naddr: pointer to hold number of resolved addresses
+ * @addrs: pointer to hold resolved addresses
+ *
+ * This method should be called from the callback passed
+ * to qio_dns_resolver_lookup_async() in order to obtain
+ * results. @addrs will be filled with all the resolved
+ * addresses. @naddrs will specify the number of entries
+ * allocated in @addrs. The caller is responsible for
+ * freeing each entry in @addrs, as well as @addrs itself.
+ */
+void qio_dns_resolver_lookup_result(QIODNSResolver *resolver,
+ QIOTask *task,
+ size_t *naddrs,
+ SocketAddress ***addrs);
+
+#endif /* QIO_DNS_RESOLVER_H */