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