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 do not include the leading underscore
 599  * that appears in the actual DNS entry.
 600  *
 601  * On success, g_resolver_lookup_service() will return a #GList of
 602  * #GSrvTarget, sorted in order of preference. (That is, you should
 603  * attempt to connect to the first target first, then the second if
 604  * the first fails, etc.)
 605  *
 606  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 607  * a value from #GResolverError.
 608  *
 609  * If @cancellable is non-%NULL, it can be used to cancel the
 610  * operation, in which case @error (if non-%NULL) will be set to
 611  * %G_IO_ERROR_CANCELLED.
 612  *
 613  * If you are planning to connect to the service, it is usually easier
 614  * to create a #GNetworkService and use its #GSocketConnectable
 615  * interface.
 616  *
 617  * Return value: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
 618  * or %NULL on error. You must free each of the targets and the list when you are
 619  * done with it. (You can use g_resolver_free_targets() to do this.)
 620  *
 621  * Since: 2.22
 622  */
 623 GList *
 624 g_resolver_lookup_service (GResolver     *resolver,
 625                            const gchar   *service,
 626                            const gchar   *protocol,
 627                            const gchar   *domain,
 628                            GCancellable  *cancellable,
 629                            GError       **error)
 630 {
 631   GList *targets;
 632   gchar *rrname;
 633
 634   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 635   g_return_val_if_fail (service != NULL, NULL);
 636   g_return_val_if_fail (protocol != NULL, NULL);
 637   g_return_val_if_fail (domain != NULL, NULL);
 638
 639   rrname = g_resolver_get_service_rrname (service, protocol, domain);
 640
 641   g_resolver_maybe_reload (resolver);
 642   targets = G_RESOLVER_GET_CLASS (resolver)->
 643     lookup_service (resolver, rrname, cancellable, error);
 644
 645   g_free (rrname);
 646   return targets;
 647 }
 648
 649 /**
 650  * g_resolver_lookup_service_async:
 651  * @resolver: a #GResolver
 652  * @service: the service type to look up (eg, "ldap")
 653  * @protocol: the networking protocol to use for @service (eg, "tcp")
 654  * @domain: the DNS domain to look up the service in
 655  * @cancellable: (allow-none): a #GCancellable, or %NULL
 656  * @callback: (scope async): callback to call after resolution completes
 657  * @user_data: (closure): data for @callback
 658  *
 659  * Begins asynchronously performing a DNS SRV lookup for the given
 660  * @service and @protocol in the given @domain, and eventually calls
 661  * @callback, which must call g_resolver_lookup_service_finish() to
 662  * get the final result. See g_resolver_lookup_service() for more
 663  * details.
 664  *
 665  * Since: 2.22
 666  */
 667 void
 668 g_resolver_lookup_service_async (GResolver           *resolver,
 669                                  const gchar         *service,
 670                                  const gchar         *protocol,
 671                                  const gchar         *domain,
 672                                  GCancellable        *cancellable,
 673                                  GAsyncReadyCallback  callback,
 674                                  gpointer             user_data)
 675 {
 676   gchar *rrname;
 677
 678   g_return_if_fail (G_IS_RESOLVER (resolver));
 679   g_return_if_fail (service != NULL);
 680   g_return_if_fail (protocol != NULL);
 681   g_return_if_fail (domain != NULL);
 682
 683   rrname = g_resolver_get_service_rrname (service, protocol, domain);
 684
 685   g_resolver_maybe_reload (resolver);
 686   G_RESOLVER_GET_CLASS (resolver)->
 687     lookup_service_async (resolver, rrname, cancellable, callback, user_data);
 688
 689   g_free (rrname);
 690 }
 691
 692 /**
 693  * g_resolver_lookup_service_finish:
 694  * @resolver: a #GResolver
 695  * @result: the result passed to your #GAsyncReadyCallback
 696  * @error: return location for a #GError, or %NULL
 697  *
 698  * Retrieves the result of a previous call to
 699  * g_resolver_lookup_service_async().
 700  *
 701  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 702  * a value from #GResolverError. If the operation was cancelled,
 703  * @error will be set to %G_IO_ERROR_CANCELLED.
 704  *
 705  * Return value: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
 706  * or %NULL on error. See g_resolver_lookup_service() for more details.
 707  *
 708  * Since: 2.22
 709  */
 710 GList *
 711 g_resolver_lookup_service_finish (GResolver     *resolver,
 712                                   GAsyncResult  *result,
 713                                   GError       **error)
 714 {
 715   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 716
 717   if (g_async_result_legacy_propagate_error (result, error))
 718     return NULL;
 719
 720   return G_RESOLVER_GET_CLASS (resolver)->
 721     lookup_service_finish (resolver, result, error);
 722 }
 723
 724 /**
 725  * g_resolver_free_targets: (skip)
 726  * @targets: a #GList of #GSrvTarget
 727  *
 728  * Frees @targets (which should be the return value from
 729  * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
 730  * (This is a convenience method; you can also simply free the
 731  * results by hand.)
 732  *
 733  * Since: 2.22
 734  */
 735 void
 736 g_resolver_free_targets (GList *targets)
 737 {
 738   GList *t;
 739
 740   for (t = targets; t; t = t->next)
 741     g_srv_target_free (t->data);
 742   g_list_free (targets);
 743 }
 744
 745 /**
 746  * g_resolver_lookup_records:
 747  * @resolver: a #GResolver
 748  * @rrname: the DNS name to lookup the record for
 749  * @record_type: the type of DNS record to lookup
 750  * @cancellable: (allow-none): a #GCancellable, or %NULL
 751  * @error: return location for a #GError, or %NULL
 752  *
 753  * Synchronously performs a DNS record lookup for the given @rrname and returns
 754  * a list of records as #GVariant tuples. See #GResolverRecordType for
 755  * information on what the records contain for each @record_type.
 756  *
 757  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 758  * a value from #GResolverError.
 759  *
 760  * If @cancellable is non-%NULL, it can be used to cancel the
 761  * operation, in which case @error (if non-%NULL) will be set to
 762  * %G_IO_ERROR_CANCELLED.
 763  *
 764  * Return value: (element-type GVariant) (transfer full): a #GList of #GVariant,
 765  * or %NULL on error. You must free each of the records and the list when you are
 766  * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
 767  *
 768  * Since: 2.34
 769  */
 770 GList *
 771 g_resolver_lookup_records (GResolver            *resolver,
 772                            const gchar          *rrname,
 773                            GResolverRecordType   record_type,
 774                            GCancellable         *cancellable,
 775                            GError              **error)
 776 {
 777   GList *records;
 778
 779   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 780   g_return_val_if_fail (rrname != NULL, NULL);
 781
 782   g_resolver_maybe_reload (resolver);
 783   records = G_RESOLVER_GET_CLASS (resolver)->
 784     lookup_records (resolver, rrname, record_type, cancellable, error);
 785
 786   return records;
 787 }
 788
 789 /**
 790  * g_resolver_lookup_records_async:
 791  * @resolver: a #GResolver
 792  * @rrname: the DNS name to lookup the record for
 793  * @record_type: the type of DNS record to lookup
 794  * @cancellable: (allow-none): a #GCancellable, or %NULL
 795  * @callback: (scope async): callback to call after resolution completes
 796  * @user_data: (closure): data for @callback
 797  *
 798  * Begins asynchronously performing a DNS lookup for the given
 799  * @rrname, and eventually calls @callback, which must call
 800  * g_resolver_lookup_records_finish() to get the final result. See
 801  * g_resolver_lookup_records() for more details.
 802  *
 803  * Since: 2.34
 804  */
 805 void
 806 g_resolver_lookup_records_async (GResolver           *resolver,
 807                                  const gchar         *rrname,
 808                                  GResolverRecordType  record_type,
 809                                  GCancellable        *cancellable,
 810                                  GAsyncReadyCallback  callback,
 811                                  gpointer             user_data)
 812 {
 813   g_return_if_fail (G_IS_RESOLVER (resolver));
 814   g_return_if_fail (rrname != NULL);
 815
 816   g_resolver_maybe_reload (resolver);
 817   G_RESOLVER_GET_CLASS (resolver)->
 818     lookup_records_async (resolver, rrname, record_type, cancellable, callback, user_data);
 819 }
 820
 821 /**
 822  * g_resolver_lookup_records_finish:
 823  * @resolver: a #GResolver
 824  * @result: the result passed to your #GAsyncReadyCallback
 825  * @error: return location for a #GError, or %NULL
 826  *
 827  * Retrieves the result of a previous call to
 828  * g_resolver_lookup_records_async(). Returns a list of records as #GVariant
 829  * tuples. See #GResolverRecordType for information on what the records contain.
 830  *
 831  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 832  * a value from #GResolverError. If the operation was cancelled,
 833  * @error will be set to %G_IO_ERROR_CANCELLED.
 834  *
 835  * Return value: (element-type GVariant) (transfer full): a #GList of #GVariant,
 836  * or %NULL on error. You must free each of the records and the list when you are
 837  * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.)
 838  *
 839  * Since: 2.34
 840  */
 841 GList *
 842 g_resolver_lookup_records_finish (GResolver     *resolver,
 843                                   GAsyncResult  *result,
 844                                   GError       **error)
 845 {
 846   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 847   return G_RESOLVER_GET_CLASS (resolver)->
 848     lookup_records_finish (resolver, result, error);
 849 }
 850
 851 guint64
 852 g_resolver_get_serial (GResolver *resolver)
 853 {
 854   g_return_val_if_fail (G_IS_RESOLVER (resolver), 0);
 855
 856   g_resolver_maybe_reload (resolver);
 857
 858 #ifdef G_OS_UNIX
 859   return (guint64) resolver->priv->resolv_conf_timestamp;
 860 #else
 861   return 1;
 862 #endif
 863 }
 864
 865 /**
 866  * g_resolver_error_quark:
 867  *
 868  * Gets the #GResolver Error Quark.
 869  *
 870  * Return value: a #GQuark.
 871  *
 872  * Since: 2.22
 873  */
 874 G_DEFINE_QUARK (g-resolver-error-quark, g_resolver_error)