include/io/dns-resolver.h

   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 */