qemu

dns-resolver.h (7196B)

---

 /*
  * 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.1 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 "qapi/qapi-types-sockets.h"
 #include "qom/object.h"
 #include "io/task.h"
 
 #define TYPE_QIO_DNS_RESOLVER "qio-dns-resolver"
 OBJECT_DECLARE_SIMPLE_TYPE(QIODNSResolver,
                            QIO_DNS_RESOLVER)
 
 
 /**
  * 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;
 };
 
 
 
 /**
  * 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 */