gio/gresolver.c

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2
   3 /* GIO - GLib Input, Output and Streaming Library
   4  *
   5  * Copyright (C) 2008 Red Hat, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General
  18  * Public License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include "config.h"
  24 #include <glib.h>
  25 #include "glibintl.h"
  26
  27 #include "gresolver.h"
  28 #include "gnetworkingprivate.h"
  29 #include "gasyncresult.h"
  30 #include "ginetaddress.h"
  31 #include "gsimpleasyncresult.h"
  32 #include "gtask.h"
  33 #include "gsrvtarget.h"
  34 #include "gthreadedresolver.h"
  35
  36 #ifdef G_OS_UNIX
  37 #include <sys/stat.h>
  38 #endif
  39
  40 #include <stdlib.h>
  41
  42
  43 /**
  44  * SECTION:gresolver
  45  * @short_description: Asynchronous and cancellable DNS resolver
  46  * @include: gio/gio.h
  47  *
  48  * #GResolver provides cancellable synchronous and asynchronous DNS
  49  * resolution, for hostnames (g_resolver_lookup_by_address(),
  50  * g_resolver_lookup_by_name() and their async variants) and SRV
  51  * (service) records (g_resolver_lookup_service()).
  52  *
  53  * #GNetworkAddress and #GNetworkService provide wrappers around
  54  * #GResolver functionality that also implement #GSocketConnectable,
  55  * making it easy to connect to a remote host/service.
  56  */
  57
  58 enum {
  59   RELOAD,
  60   LAST_SIGNAL
  61 };
  62
  63 static guint signals[LAST_SIGNAL] = { 0 };
  64
  65 struct _GResolverPrivate {
  66 #ifdef G_OS_UNIX
  67   time_t resolv_conf_timestamp;
  68 #else
  69   int dummy;
  70 #endif
  71 };
  72
  73 /**
  74  * GResolver:
  75  *
  76  * The object that handles DNS resolution. Use g_resolver_get_default()
  77  * to get the default resolver.
  78  */
  79 G_DEFINE_TYPE_WITH_CODE (GResolver, g_resolver, G_TYPE_OBJECT,
  80                          G_ADD_PRIVATE (GResolver)
  81                          g_networking_init ();)
  82
  83 static GList *
  84 srv_records_to_targets (GList *records)
  85 {
  86   const gchar *hostname;
  87   guint16 port, priority, weight;
  88   GSrvTarget *target;
  89   GList *l;
  90
  91   for (l = records; l != NULL; l = g_list_next (l))
  92     {
  93       g_variant_get (l->data, "(qqq&s)", &priority, &weight, &port, &hostname);
  94       target = g_srv_target_new (hostname, port, priority, weight);
  95       g_variant_unref (l->data);
  96       l->data = target;
  97     }
  98
  99   return g_srv_target_list_sort (records);
 100 }
 101
 102 static GList *
 103 g_resolver_real_lookup_service (GResolver            *resolver,
 104                                 const gchar          *rrname,
 105                                 GCancellable         *cancellable,
 106                                 GError              **error)
 107 {
 108   GList *records;
 109
 110   records = G_RESOLVER_GET_CLASS (resolver)->lookup_records (resolver,
 111                                                              rrname,
 112                                                              G_RESOLVER_RECORD_SRV,
 113                                                              cancellable,
 114                                                              error);
 115
 116   return srv_records_to_targets (records);
 117 }
 118
 119 static void
 120 g_resolver_real_lookup_service_async (GResolver            *resolver,
 121                                       const gchar          *rrname,
 122                                       GCancellable         *cancellable,
 123                                       GAsyncReadyCallback   callback,
 124                                       gpointer              user_data)
 125 {
 126   G_RESOLVER_GET_CLASS (resolver)->lookup_records_async (resolver,
 127                                                          rrname,
 128                                                          G_RESOLVER_RECORD_SRV,
 129                                                          cancellable,
 130                                                          callback,
 131                                                          user_data);
 132 }
 133
 134 static GList *
 135 g_resolver_real_lookup_service_finish (GResolver            *resolver,
 136                                        GAsyncResult         *result,
 137                                        GError              **error)
 138 {
 139   GList *records;
 140
 141   records = G_RESOLVER_GET_CLASS (resolver)->lookup_records_finish (resolver,
 142                                                                     result,
 143                                                                     error);
 144
 145   return srv_records_to_targets (records);
 146 }
 147
 148 static void
 149 g_resolver_class_init (GResolverClass *resolver_class)
 150 {
 151   /* Automatically pass these over to the lookup_records methods */
 152   resolver_class->lookup_service = g_resolver_real_lookup_service;
 153   resolver_class->lookup_service_async = g_resolver_real_lookup_service_async;
 154   resolver_class->lookup_service_finish = g_resolver_real_lookup_service_finish;
 155
 156   /**
 157    * GResolver::reload:
 158    * @resolver: a #GResolver
 159    *
 160    * Emitted when the resolver notices that the system resolver
 161    * configuration has changed.
 162    **/
 163   signals[RELOAD] =
 164     g_signal_new (I_("reload"),
 165                   G_TYPE_RESOLVER,
 166                   G_SIGNAL_RUN_LAST,
 167                   G_STRUCT_OFFSET (GResolverClass, reload),
 168                   NULL, NULL,
 169                   g_cclosure_marshal_VOID__VOID,
 170                   G_TYPE_NONE, 0);
 171 }
 172
 173 static void
 174 g_resolver_init (GResolver *resolver)
 175 {
 176 #ifdef G_OS_UNIX
 177   struct stat st;
 178 #endif
 179
 180   resolver->priv = g_resolver_get_instance_private (resolver);
 181
 182 #ifdef G_OS_UNIX
 183   if (stat (_PATH_RESCONF, &st) == 0)
 184     resolver->priv->resolv_conf_timestamp = st.st_mtime;
 185 #endif
 186 }
 187
 188 static GResolver *default_resolver;
 189
 190 /**
 191  * g_resolver_get_default:
 192  *
 193  * Gets the default #GResolver. You should unref it when you are done
 194  * with it. #GResolver may use its reference count as a hint about how
 195  * many threads it should allocate for concurrent DNS resolutions.
 196  *
 197  * Return value: (transfer full): the default #GResolver.
 198  *
 199  * Since: 2.22
 200  */
 201 GResolver *
 202 g_resolver_get_default (void)
 203 {
 204   if (!default_resolver)
 205     default_resolver = g_object_new (G_TYPE_THREADED_RESOLVER, NULL);
 206
 207   return g_object_ref (default_resolver);
 208 }
 209
 210 /**
 211  * g_resolver_set_default:
 212  * @resolver: the new default #GResolver
 213  *
 214  * Sets @resolver to be the application's default resolver (reffing
 215  * @resolver, and unreffing the previous default resolver, if any).
 216  * Future calls to g_resolver_get_default() will return this resolver.
 217  *
 218  * This can be used if an application wants to perform any sort of DNS
 219  * caching or "pinning"; it can implement its own #GResolver that
 220  * calls the original default resolver for DNS operations, and
 221  * implements its own cache policies on top of that, and then set
 222  * itself as the default resolver for all later code to use.
 223  *
 224  * Since: 2.22
 225  */
 226 void
 227 g_resolver_set_default (GResolver *resolver)
 228 {
 229   if (default_resolver)
 230     g_object_unref (default_resolver);
 231   default_resolver = g_object_ref (resolver);
 232 }
 233
 234 /* Bionic has res_init() but it's not in any header */
 235 #ifdef __BIONIC__
 236 int res_init (void);
 237 #endif
 238
 239 static void
 240 g_resolver_maybe_reload (GResolver *resolver)
 241 {
 242 #ifdef G_OS_UNIX
 243   struct stat st;
 244
 245   if (stat (_PATH_RESCONF, &st) == 0)
 246     {
 247       if (st.st_mtime != resolver->priv->resolv_conf_timestamp)
 248         {
 249           resolver->priv->resolv_conf_timestamp = st.st_mtime;
 250 #ifdef HAVE_RES_INIT
 251           res_init ();
 252 #endif
 253           g_signal_emit (resolver, signals[RELOAD], 0);
 254         }
 255     }
 256 #endif
 257 }
 258
 259 /* filter out duplicates, cf. https://bugzilla.gnome.org/show_bug.cgi?id=631379 */
 260 static void
 261 remove_duplicates (GList *addrs)
 262 {
 263   GList *l;
 264   GList *ll;
 265   GList *lll;
 266
 267   /* TODO: if this is too slow (it's O(n^2) but n is typically really
 268    * small), we can do something more clever but note that we must not
 269    * change the order of elements...
 270    */
 271   for (l = addrs; l != NULL; l = l->next)
 272     {
 273       GInetAddress *address = G_INET_ADDRESS (l->data);
 274       for (ll = l->next; ll != NULL; ll = lll)
 275         {
 276           GInetAddress *other_address = G_INET_ADDRESS (ll->data);
 277           lll = ll->next;
 278           if (g_inet_address_equal (address, other_address))
 279             {
 280               g_object_unref (other_address);
 281               /* we never return the first element */
 282               g_warn_if_fail (g_list_delete_link (addrs, ll) == addrs);
 283             }
 284         }
 285     }
 286 }
 287
 288
 289 /**
 290  * g_resolver_lookup_by_name:
 291  * @resolver: a #GResolver
 292  * @hostname: the hostname to look up
 293  * @cancellable: (allow-none): a #GCancellable, or %NULL
 294  * @error: return location for a #GError, or %NULL
 295  *
 296  * Synchronously resolves @hostname to determine its associated IP
 297  * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
 298  * the textual form of an IP address (in which case this just becomes
 299  * a wrapper around g_inet_address_new_from_string()).
 300  *
 301  * On success, g_resolver_lookup_by_name() will return a #GList of
 302  * #GInetAddress, sorted in order of preference and guaranteed to not
 303  * contain duplicates. That is, if using the result to connect to
 304  * @hostname, you should attempt to connect to the first address
 305  * first, then the second if the first fails, etc. If you are using
 306  * the result to listen on a socket, it is appropriate to add each
 307  * result using e.g. g_socket_listener_add_address().
 308  *
 309  * If the DNS resolution fails, @error (if non-%NULL) will be set to a
 310  * value from #GResolverError.
 311  *
 312  * If @cancellable is non-%NULL, it can be used to cancel the
 313  * operation, in which case @error (if non-%NULL) will be set to
 314  * %G_IO_ERROR_CANCELLED.
 315  *
 316  * If you are planning to connect to a socket on the resolved IP
 317  * address, it may be easier to create a #GNetworkAddress and use its
 318  * #GSocketConnectable interface.
 319  *
 320  * Return value: (element-type GInetAddress) (transfer full): a #GList
 321  * of #GInetAddress, or %NULL on error. You
 322  * must unref each of the addresses and free the list when you are
 323  * done with it. (You can use g_resolver_free_addresses() to do this.)
 324  *
 325  * Since: 2.22
 326  */
 327 GList *
 328 g_resolver_lookup_by_name (GResolver     *resolver,
 329                            const gchar   *hostname,
 330                            GCancellable  *cancellable,
 331                            GError       **error)
 332 {
 333   GInetAddress *addr;
 334   GList *addrs;
 335   gchar *ascii_hostname = NULL;
 336
 337   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 338   g_return_val_if_fail (hostname != NULL, NULL);
 339
 340   /* Check if @hostname is just an IP address */
 341   addr = g_inet_address_new_from_string (hostname);
 342   if (addr)
 343     return g_list_append (NULL, addr);
 344
 345   if (g_hostname_is_non_ascii (hostname))
 346     hostname = ascii_hostname = g_hostname_to_ascii (hostname);
 347
 348   g_resolver_maybe_reload (resolver);
 349   addrs = G_RESOLVER_GET_CLASS (resolver)->
 350     lookup_by_name (resolver, hostname, cancellable, error);
 351
 352   remove_duplicates (addrs);
 353
 354   g_free (ascii_hostname);
 355   return addrs;
 356 }
 357
 358 /**
 359  * g_resolver_lookup_by_name_async:
 360  * @resolver: a #GResolver
 361  * @hostname: the hostname to look up the address of
 362  * @cancellable: (allow-none): a #GCancellable, or %NULL
 363  * @callback: (scope async): callback to call after resolution completes
 364  * @user_data: (closure): data for @callback
 365  *
 366  * Begins asynchronously resolving @hostname to determine its
 367  * associated IP address(es), and eventually calls @callback, which
 368  * must call g_resolver_lookup_by_name_finish() to get the result.
 369  * See g_resolver_lookup_by_name() for more details.
 370  *
 371  * Since: 2.22
 372  */
 373 void
 374 g_resolver_lookup_by_name_async (GResolver           *resolver,
 375                                  const gchar         *hostname,
 376                                  GCancellable        *cancellable,
 377                                  GAsyncReadyCallback  callback,
 378                                  gpointer             user_data)
 379 {
 380   GInetAddress *addr;
 381   gchar *ascii_hostname = NULL;
 382
 383   g_return_if_fail (G_IS_RESOLVER (resolver));
 384   g_return_if_fail (hostname != NULL);
 385
 386   /* Check if @hostname is just an IP address */
 387   addr = g_inet_address_new_from_string (hostname);
 388   if (addr)
 389     {
 390       GTask *task;
 391
 392       task = g_task_new (resolver, cancellable, callback, user_data);
 393       g_task_set_source_tag (task, g_resolver_lookup_by_name_async);
 394       g_task_return_pointer (task, g_list_append (NULL, addr),
 395                              (GDestroyNotify) g_resolver_free_addresses);
 396       g_object_unref (task);
 397       return;
 398     }
 399
 400   if (g_hostname_is_non_ascii (hostname))
 401     hostname = ascii_hostname = g_hostname_to_ascii (hostname);
 402
 403   g_resolver_maybe_reload (resolver);
 404   G_RESOLVER_GET_CLASS (resolver)->
 405     lookup_by_name_async (resolver, hostname, cancellable, callback, user_data);
 406
 407   g_free (ascii_hostname);
 408 }
 409
 410 /**
 411  * g_resolver_lookup_by_name_finish:
 412  * @resolver: a #GResolver
 413  * @result: the result passed to your #GAsyncReadyCallback
 414  * @error: return location for a #GError, or %NULL
 415  *
 416  * Retrieves the result of a call to
 417  * g_resolver_lookup_by_name_async().
 418  *
 419  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 420  * a value from #GResolverError. If the operation was cancelled,
 421  * @error will be set to %G_IO_ERROR_CANCELLED.
 422  *
 423  * Return value: (element-type GInetAddress) (transfer full): a #GList
 424  * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
 425  * for more details.
 426  *
 427  * Since: 2.22
 428  */
 429 GList *
 430 g_resolver_lookup_by_name_finish (GResolver     *resolver,
 431                                   GAsyncResult  *result,
 432                                   GError       **error)
 433 {
 434   GList *addrs;
 435
 436   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 437
 438   if (g_async_result_legacy_propagate_error (result, error))
 439     return NULL;
 440   else if (g_async_result_is_tagged (result, g_resolver_lookup_by_name_async))
 441     {
 442       /* Handle the stringified-IP-addr case */
 443       return g_task_propagate_pointer (G_TASK (result), error);
 444     }
 445
 446   addrs = G_RESOLVER_GET_CLASS (resolver)->
 447     lookup_by_name_finish (resolver, result, error);
 448
 449   remove_duplicates (addrs);
 450
 451   return addrs;
 452 }
 453
 454 /**
 455  * g_resolver_free_addresses: (skip)
 456  * @addresses: a #GList of #GInetAddress
 457  *
 458  * Frees @addresses (which should be the return value from
 459  * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
 460  * (This is a convenience method; you can also simply free the results
 461  * by hand.)
 462  *
 463  * Since: 2.22
 464  */
 465 void
 466 g_resolver_free_addresses (GList *addresses)
 467 {
 468   GList *a;
 469
 470   for (a = addresses; a; a = a->next)
 471     g_object_unref (a->data);
 472   g_list_free (addresses);
 473 }
 474
 475 /**
 476  * g_resolver_lookup_by_address:
 477  * @resolver: a #GResolver
 478  * @address: the address to reverse-resolve
 479  * @cancellable: (allow-none): a #GCancellable, or %NULL
 480  * @error: return location for a #GError, or %NULL
 481  *
 482  * Synchronously reverse-resolves @address to determine its
 483  * associated hostname.
 484  *
 485  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 486  * a value from #GResolverError.
 487  *
 488  * If @cancellable is non-%NULL, it can be used to cancel the
 489  * operation, in which case @error (if non-%NULL) will be set to
 490  * %G_IO_ERROR_CANCELLED.
 491  *
 492  * Return value: a hostname (either ASCII-only, or in ASCII-encoded
 493  *     form), or %NULL on error.
 494  *
 495  * Since: 2.22
 496  */
 497 gchar *
 498 g_resolver_lookup_by_address (GResolver     *resolver,
 499                               GInetAddress  *address,
 500                               GCancellable  *cancellable,
 501                               GError       **error)
 502 {
 503   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 504   g_return_val_if_fail (G_IS_INET_ADDRESS (address), NULL);
 505
 506   g_resolver_maybe_reload (resolver);
 507   return G_RESOLVER_GET_CLASS (resolver)->
 508     lookup_by_address (resolver, address, cancellable, error);
 509 }
 510
 511 /**
 512  * g_resolver_lookup_by_address_async:
 513  * @resolver: a #GResolver
 514  * @address: the address to reverse-resolve
 515  * @cancellable: (allow-none): a #GCancellable, or %NULL
 516  * @callback: (scope async): callback to call after resolution completes
 517  * @user_data: (closure): data for @callback
 518  *
 519  * Begins asynchronously reverse-resolving @address to determine its
 520  * associated hostname, and eventually calls @callback, which must
 521  * call g_resolver_lookup_by_address_finish() to get the final result.
 522  *
 523  * Since: 2.22
 524  */
 525 void
 526 g_resolver_lookup_by_address_async (GResolver           *resolver,
 527                                     GInetAddress        *address,
 528                                     GCancellable        *cancellable,
 529                                     GAsyncReadyCallback  callback,
 530                                     gpointer             user_data)
 531 {
 532   g_return_if_fail (G_IS_RESOLVER (resolver));
 533   g_return_if_fail (G_IS_INET_ADDRESS (address));
 534
 535   g_resolver_maybe_reload (resolver);
 536   G_RESOLVER_GET_CLASS (resolver)->
 537     lookup_by_address_async (resolver, address, cancellable, callback, user_data);
 538 }
 539
 540 /**
 541  * g_resolver_lookup_by_address_finish:
 542  * @resolver: a #GResolver
 543  * @result: the result passed to your #GAsyncReadyCallback
 544  * @error: return location for a #GError, or %NULL
 545  *
 546  * Retrieves the result of a previous call to
 547  * g_resolver_lookup_by_address_async().
 548  *
 549  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 550  * a value from #GResolverError. If the operation was cancelled,
 551  * @error will be set to %G_IO_ERROR_CANCELLED.
 552  *
 553  * Return value: a hostname (either ASCII-only, or in ASCII-encoded
 554  * form), or %NULL on error.
 555  *
 556  * Since: 2.22
 557  */
 558 gchar *
 559 g_resolver_lookup_by_address_finish (GResolver     *resolver,
 560                                      GAsyncResult  *result,
 561                                      GError       **error)
 562 {
 563   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 564
 565   if (g_async_result_legacy_propagate_error (result, error))
 566     return NULL;
 567
 568   return G_RESOLVER_GET_CLASS (resolver)->
 569     lookup_by_address_finish (resolver, result, error);
 570 }
 571
 572 static gchar *
 573 g_resolver_get_service_rrname (const char *service,
 574                                const char *protocol,
 575                                const char *domain)
 576 {
 577   gchar *rrname, *ascii_domain = NULL;
 578
 579   if (g_hostname_is_non_ascii (domain))
 580     domain = ascii_domain = g_hostname_to_ascii (domain);
 581
 582   rrname = g_strdup_printf ("_%s._%s.%s", service, protocol, domain);
 583
 584   g_free (ascii_domain);
 585   return rrname;
 586 }
 587
 588 /**
 589  * g_resolver_lookup_service:
 590  * @resolver: a #GResolver
 591  * @service: the service type to look up (eg, "ldap")
 592  * @protocol: the networking protocol to use for @service (eg, "tcp")
 593  * @domain: the DNS domain to look up the service in
 594  * @cancellable: (allow-none): a #GCancellable, or %NULL
 595  * @error: return location for a #GError, or %NULL
 596  *
 597  * Synchronously performs a DNS SRV lookup for the given @service and
 598  * @protocol in the given @domain and returns an array of #GSrvTarget.
 599  * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
 600  * @service and @protocol arguments <emphasis>do not</emphasis>
 601  * include the leading underscore that appears in the actual DNS
 602  * entry.
 603  *
 604  * On success, g_resolver_lookup_service() will return a #GList of
 605  * #GSrvTarget, sorted in order of preference. (That is, you should
 606  * attempt to connect to the first target first, then the second if
 607  * the first fails, etc.)
 608  *
 609  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 610  * a value from #GResolverError.
 611  *
 612  * If @cancellable is non-%NULL, it can be used to cancel the
 613  * operation, in which case @error (if non-%NULL) will be set to
 614  * %G_IO_ERROR_CANCELLED.
 615  *
 616  * If you are planning to connect to the service, it is usually easier
 617  * to create a #GNetworkService and use its #GSocketConnectable
 618  * interface.
 619  *
 620  * Return value: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
 621  * or %NULL on error. You must free each of the targets and the list when you are
 622  * done with it. (You can use g_resolver_free_targets() to do this.)
 623  *
 624  * Since: 2.22
 625  */
 626 GList *
 627 g_resolver_lookup_service (GResolver     *resolver,
 628                            const gchar   *service,
 629                            const gchar   *protocol,
 630                            const gchar   *domain,
 631                            GCancellable  *cancellable,
 632                            GError       **error)
 633 {
 634   GList *targets;
 635   gchar *rrname;
 636
 637   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 638   g_return_val_if_fail (service != NULL, NULL);
 639   g_return_val_if_fail (protocol != NULL, NULL);
 640   g_return_val_if_fail (domain != NULL, NULL);
 641
 642   rrname = g_resolver_get_service_rrname (service, protocol, domain);
 643
 644   g_resolver_maybe_reload (resolver);
 645   targets = G_RESOLVER_GET_CLASS (resolver)->
 646     lookup_service (resolver, rrname, cancellable, error);
 647
 648   g_free (rrname);
 649   return targets;
 650 }
 651
 652 /**
 653  * g_resolver_lookup_service_async:
 654  * @resolver: a #GResolver
 655  * @service: the service type to look up (eg, "ldap")
 656  * @protocol: the networking protocol to use for @service (eg, "tcp")
 657  * @domain: the DNS domain to look up the service in
 658  * @cancellable: (allow-none): a #GCancellable, or %NULL
 659  * @callback: (scope async): callback to call after resolution completes
 660  * @user_data: (closure): data for @callback
 661  *
 662  * Begins asynchronously performing a DNS SRV lookup for the given
 663  * @service and @protocol in the given @domain, and eventually calls
 664  * @callback, which must call g_resolver_lookup_service_finish() to
 665  * get the final result. See g_resolver_lookup_service() for more
 666  * details.
 667  *
 668  * Since: 2.22
 669  */
 670 void
 671 g_resolver_lookup_service_async (GResolver           *resolver,
 672                                  const gchar         *service,
 673                                  const gchar         *protocol,
 674                                  const gchar         *domain,
 675                                  GCancellable        *cancellable,
 676                                  GAsyncReadyCallback  callback,
 677                                  gpointer             user_data)
 678 {
 679   gchar *rrname;
 680
 681   g_return_if_fail (G_IS_RESOLVER (resolver));
 682   g_return_if_fail (service != NULL);
 683   g_return_if_fail (protocol != NULL);
 684   g_return_if_fail (domain != NULL);
 685
 686   rrname = g_resolver_get_service_rrname (service, protocol, domain);
 687
 688   g_resolver_maybe_reload (resolver);
 689   G_RESOLVER_GET_CLASS (resolver)->
 690     lookup_service_async (resolver, rrname, cancellable, callback, user_data);
 691
 692   g_free (rrname);
 693 }
 694
 695 /**
 696  * g_resolver_lookup_service_finish:
 697  * @resolver: a #GResolver
 698  * @result: the result passed to your #GAsyncReadyCallback
 699  * @error: return location for a #GError, or %NULL
 700  *
 701  * Retrieves the result of a previous call to
 702  * g_resolver_lookup_service_async().
 703  *
 704  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 705  * a value from #GResolverError. If the operation was cancelled,
 706  * @error will be set to %G_IO_ERROR_CANCELLED.
 707  *
 708  * Return value: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
 709  * or %NULL on error. See g_resolver_lookup_service() for more details.
 710  *
 711  * Since: 2.22
 712  */
 713 GList *
 714 g_resolver_lookup_service_finish (GResolver     *resolver,
 715                                   GAsyncResult  *result,
 716                                   GError       **error)
 717 {
 718   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 719
 720   if (g_async_result_legacy_propagate_error (result, error))
 721     return NULL;
 722
 723   return G_RESOLVER_GET_CLASS (resolver)->
 724     lookup_service_finish (resolver, result, error);
 725 }
 726
 727 /**
 728  * g_resolver_free_targets: (skip)
 729  * @targets: a #GList of #GSrvTarget
 730  *
 731  * Frees @targets (which should be the return value from
 732  * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
 733  * (This is a convenience method; you can also simply free the
 734  * results by hand.)
 735  *
 736  * Since: 2.22
 737  */
 738 void
 739 g_resolver_free_targets (GList *targets)
 740 {
 741   GList *t;
 742
 743   for (t = targets; t; t = t->next)
 744     g_srv_target_free (t->data);
 745   g_list_free (targets);
 746 }
 747
 748 /**
 749  * g_resolver_lookup_records:
 750  * @resolver: a #GResolver
 751  * @rrname: the DNS name to lookup the record for
 752  * @record_type: the type of DNS record to lookup
 753  * @cancellable: (allow-none): a #GCancellable, or %NULL
 754  * @error: return location for a #GError, or %NULL
 755  *
 756  * Synchronously performs a DNS record lookup for the given @rrname and returns
 757  * a list of records as #GVariant tuples. See #GResolverRecordType for
 758  * information on what the records contain for each @record_type.
 759  *
 760  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 761  * a value from #GResolverError.
 762  *
 763  * If @cancellable is non-%NULL, it can be used to cancel the
 764  * operation, in which case @error (if non-%NULL) will be set to
 765  * %G_IO_ERROR_CANCELLED.
 766  *
 767  * Return value: (element-type GVariant) (transfer full): a #GList of #GVariant,
 768  * or %NULL on error. You must free each of the records and the list when you are
 769  * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
 770  *
 771  * Since: 2.34
 772  */
 773 GList *
 774 g_resolver_lookup_records (GResolver            *resolver,
 775                            const gchar          *rrname,
 776                            GResolverRecordType   record_type,
 777                            GCancellable         *cancellable,
 778                            GError              **error)
 779 {
 780   GList *records;
 781
 782   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 783   g_return_val_if_fail (rrname != NULL, NULL);
 784
 785   g_resolver_maybe_reload (resolver);
 786   records = G_RESOLVER_GET_CLASS (resolver)->
 787     lookup_records (resolver, rrname, record_type, cancellable, error);
 788
 789   return records;
 790 }
 791
 792 /**
 793  * g_resolver_lookup_records_async:
 794  * @resolver: a #GResolver
 795  * @rrname: the DNS name to lookup the record for
 796  * @record_type: the type of DNS record to lookup
 797  * @cancellable: (allow-none): a #GCancellable, or %NULL
 798  * @callback: (scope async): callback to call after resolution completes
 799  * @user_data: (closure): data for @callback
 800  *
 801  * Begins asynchronously performing a DNS lookup for the given
 802  * @rrname, and eventually calls @callback, which must call
 803  * g_resolver_lookup_records_finish() to get the final result. See
 804  * g_resolver_lookup_records() for more details.
 805  *
 806  * Since: 2.34
 807  */
 808 void
 809 g_resolver_lookup_records_async (GResolver           *resolver,
 810                                  const gchar         *rrname,
 811                                  GResolverRecordType  record_type,
 812                                  GCancellable        *cancellable,
 813                                  GAsyncReadyCallback  callback,
 814                                  gpointer             user_data)
 815 {
 816   g_return_if_fail (G_IS_RESOLVER (resolver));
 817   g_return_if_fail (rrname != NULL);
 818
 819   g_resolver_maybe_reload (resolver);
 820   G_RESOLVER_GET_CLASS (resolver)->
 821     lookup_records_async (resolver, rrname, record_type, cancellable, callback, user_data);
 822 }
 823
 824 /**
 825  * g_resolver_lookup_records_finish:
 826  * @resolver: a #GResolver
 827  * @result: the result passed to your #GAsyncReadyCallback
 828  * @error: return location for a #GError, or %NULL
 829  *
 830  * Retrieves the result of a previous call to
 831  * g_resolver_lookup_records_async(). Returns a list of records as #GVariant
 832  * tuples. See #GResolverRecordType for information on what the records contain.
 833  *
 834  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 835  * a value from #GResolverError. If the operation was cancelled,
 836  * @error will be set to %G_IO_ERROR_CANCELLED.
 837  *
 838  * Return value: (element-type GVariant) (transfer full): a #GList of #GVariant,
 839  * or %NULL on error. You must free each of the records and the list when you are
 840  * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
 841  *
 842  * Since: 2.34
 843  */
 844 GList *
 845 g_resolver_lookup_records_finish (GResolver     *resolver,
 846                                   GAsyncResult  *result,
 847                                   GError       **error)
 848 {
 849   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 850   return G_RESOLVER_GET_CLASS (resolver)->
 851     lookup_records_finish (resolver, result, error);
 852 }
 853
 854 guint64
 855 g_resolver_get_serial (GResolver *resolver)
 856 {
 857   g_return_val_if_fail (G_IS_RESOLVER (resolver), 0);
 858
 859   g_resolver_maybe_reload (resolver);
 860
 861 #ifdef G_OS_UNIX
 862   return (guint64) resolver->priv->resolv_conf_timestamp;
 863 #else
 864   return 1;
 865 #endif
 866 }
 867
 868 /**
 869  * g_resolver_error_quark:
 870  *
 871  * Gets the #GResolver Error Quark.
 872  *
 873  * Return value: a #GQuark.
 874  *
 875  * Since: 2.22
 876  */
 877 G_DEFINE_QUARK (g-resolver-error-quark, g_resolver_error)