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  * Returns: (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 /* Note that this does not follow the "FALSE means @error is set"
 287  * convention. The return value tells the caller whether it should
 288  * return @addrs and @error to the caller right away, or if it should
 289  * continue and trying to resolve the name as a hostname.
 290  */
 291 static gboolean
 292 handle_ip_address (const char  *hostname,
 293                    GList      **addrs,
 294                    GError     **error)
 295 {
 296   GInetAddress *addr;
 297
 298 #ifndef G_OS_WIN32
 299   struct in_addr ip4addr;
 300 #endif
 301
 302   addr = g_inet_address_new_from_string (hostname);
 303   if (addr)
 304     {
 305       *addrs = g_list_append (NULL, addr);
 306       return TRUE;
 307     }
 308
 309   *addrs = NULL;
 310
 311 #ifdef G_OS_WIN32
 312
 313   /* Reject IPv6 addresses that have brackets ('[' or ']') and/or port numbers,
 314    * as no valid addresses should contain these at this point.
 315    * Non-standard IPv4 addresses would be rejected during the call to
 316    * getaddrinfo() later.
 317    */
 318   if (strrchr (hostname, '[') != NULL ||
 319       strrchr (hostname, ']') != NULL)
 320 #else
 321
 322   /* Reject non-standard IPv4 numbers-and-dots addresses.
 323    * g_inet_address_new_from_string() will have accepted any "real" IP
 324    * address, so if inet_aton() succeeds, then it's an address we want
 325    * to reject.
 326    */
 327   if (inet_aton (hostname, &ip4addr))
 328 #endif
 329     {
 330       g_set_error (error, G_RESOLVER_ERROR, G_RESOLVER_ERROR_NOT_FOUND,
 331                    _("Error resolving '%s': %s"),
 332                    hostname, gai_strerror (EAI_NONAME));
 333       return TRUE;
 334     }
 335
 336   return FALSE;
 337 }
 338
 339 /**
 340  * g_resolver_lookup_by_name:
 341  * @resolver: a #GResolver
 342  * @hostname: the hostname to look up
 343  * @cancellable: (allow-none): a #GCancellable, or %NULL
 344  * @error: return location for a #GError, or %NULL
 345  *
 346  * Synchronously resolves @hostname to determine its associated IP
 347  * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or
 348  * the textual form of an IP address (in which case this just becomes
 349  * a wrapper around g_inet_address_new_from_string()).
 350  *
 351  * On success, g_resolver_lookup_by_name() will return a non-empty #GList of
 352  * #GInetAddress, sorted in order of preference and guaranteed to not
 353  * contain duplicates. That is, if using the result to connect to
 354  * @hostname, you should attempt to connect to the first address
 355  * first, then the second if the first fails, etc. If you are using
 356  * the result to listen on a socket, it is appropriate to add each
 357  * result using e.g. g_socket_listener_add_address().
 358  *
 359  * If the DNS resolution fails, @error (if non-%NULL) will be set to a
 360  * value from #GResolverError and %NULL will be returned.
 361  *
 362  * If @cancellable is non-%NULL, it can be used to cancel the
 363  * operation, in which case @error (if non-%NULL) will be set to
 364  * %G_IO_ERROR_CANCELLED.
 365  *
 366  * If you are planning to connect to a socket on the resolved IP
 367  * address, it may be easier to create a #GNetworkAddress and use its
 368  * #GSocketConnectable interface.
 369  *
 370  * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList
 371  * of #GInetAddress, or %NULL on error. You
 372  * must unref each of the addresses and free the list when you are
 373  * done with it. (You can use g_resolver_free_addresses() to do this.)
 374  *
 375  * Since: 2.22
 376  */
 377 GList *
 378 g_resolver_lookup_by_name (GResolver     *resolver,
 379                            const gchar   *hostname,
 380                            GCancellable  *cancellable,
 381                            GError       **error)
 382 {
 383   GList *addrs;
 384   gchar *ascii_hostname = NULL;
 385
 386   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 387   g_return_val_if_fail (hostname != NULL, NULL);
 388
 389   /* Check if @hostname is just an IP address */
 390   if (handle_ip_address (hostname, &addrs, error))
 391     return addrs;
 392
 393   if (g_hostname_is_non_ascii (hostname))
 394     hostname = ascii_hostname = g_hostname_to_ascii (hostname);
 395
 396   g_resolver_maybe_reload (resolver);
 397   addrs = G_RESOLVER_GET_CLASS (resolver)->
 398     lookup_by_name (resolver, hostname, cancellable, error);
 399
 400   remove_duplicates (addrs);
 401
 402   g_free (ascii_hostname);
 403   return addrs;
 404 }
 405
 406 /**
 407  * g_resolver_lookup_by_name_async:
 408  * @resolver: a #GResolver
 409  * @hostname: the hostname to look up the address of
 410  * @cancellable: (allow-none): a #GCancellable, or %NULL
 411  * @callback: (scope async): callback to call after resolution completes
 412  * @user_data: (closure): data for @callback
 413  *
 414  * Begins asynchronously resolving @hostname to determine its
 415  * associated IP address(es), and eventually calls @callback, which
 416  * must call g_resolver_lookup_by_name_finish() to get the result.
 417  * See g_resolver_lookup_by_name() for more details.
 418  *
 419  * Since: 2.22
 420  */
 421 void
 422 g_resolver_lookup_by_name_async (GResolver           *resolver,
 423                                  const gchar         *hostname,
 424                                  GCancellable        *cancellable,
 425                                  GAsyncReadyCallback  callback,
 426                                  gpointer             user_data)
 427 {
 428   gchar *ascii_hostname = NULL;
 429   GList *addrs;
 430   GError *error = NULL;
 431
 432   g_return_if_fail (G_IS_RESOLVER (resolver));
 433   g_return_if_fail (hostname != NULL);
 434
 435   /* Check if @hostname is just an IP address */
 436   if (handle_ip_address (hostname, &addrs, &error))
 437     {
 438       GTask *task;
 439
 440       task = g_task_new (resolver, cancellable, callback, user_data);
 441       g_task_set_source_tag (task, g_resolver_lookup_by_name_async);
 442       if (addrs)
 443         g_task_return_pointer (task, addrs, (GDestroyNotify) g_resolver_free_addresses);
 444       else
 445         g_task_return_error (task, error);
 446       g_object_unref (task);
 447       return;
 448     }
 449
 450   if (g_hostname_is_non_ascii (hostname))
 451     hostname = ascii_hostname = g_hostname_to_ascii (hostname);
 452
 453   g_resolver_maybe_reload (resolver);
 454   G_RESOLVER_GET_CLASS (resolver)->
 455     lookup_by_name_async (resolver, hostname, cancellable, callback, user_data);
 456
 457   g_free (ascii_hostname);
 458 }
 459
 460 /**
 461  * g_resolver_lookup_by_name_finish:
 462  * @resolver: a #GResolver
 463  * @result: the result passed to your #GAsyncReadyCallback
 464  * @error: return location for a #GError, or %NULL
 465  *
 466  * Retrieves the result of a call to
 467  * g_resolver_lookup_by_name_async().
 468  *
 469  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 470  * a value from #GResolverError. If the operation was cancelled,
 471  * @error will be set to %G_IO_ERROR_CANCELLED.
 472  *
 473  * Returns: (element-type GInetAddress) (transfer full): a #GList
 474  * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
 475  * for more details.
 476  *
 477  * Since: 2.22
 478  */
 479 GList *
 480 g_resolver_lookup_by_name_finish (GResolver     *resolver,
 481                                   GAsyncResult  *result,
 482                                   GError       **error)
 483 {
 484   GList *addrs;
 485
 486   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 487
 488   if (g_async_result_legacy_propagate_error (result, error))
 489     return NULL;
 490   else if (g_async_result_is_tagged (result, g_resolver_lookup_by_name_async))
 491     {
 492       /* Handle the stringified-IP-addr case */
 493       return g_task_propagate_pointer (G_TASK (result), error);
 494     }
 495
 496   addrs = G_RESOLVER_GET_CLASS (resolver)->
 497     lookup_by_name_finish (resolver, result, error);
 498
 499   remove_duplicates (addrs);
 500
 501   return addrs;
 502 }
 503
 504 /**
 505  * g_resolver_free_addresses: (skip)
 506  * @addresses: a #GList of #GInetAddress
 507  *
 508  * Frees @addresses (which should be the return value from
 509  * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()).
 510  * (This is a convenience method; you can also simply free the results
 511  * by hand.)
 512  *
 513  * Since: 2.22
 514  */
 515 void
 516 g_resolver_free_addresses (GList *addresses)
 517 {
 518   GList *a;
 519
 520   for (a = addresses; a; a = a->next)
 521     g_object_unref (a->data);
 522   g_list_free (addresses);
 523 }
 524
 525 /**
 526  * g_resolver_lookup_by_address:
 527  * @resolver: a #GResolver
 528  * @address: the address to reverse-resolve
 529  * @cancellable: (allow-none): a #GCancellable, or %NULL
 530  * @error: return location for a #GError, or %NULL
 531  *
 532  * Synchronously reverse-resolves @address to determine its
 533  * associated hostname.
 534  *
 535  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 536  * a value from #GResolverError.
 537  *
 538  * If @cancellable is non-%NULL, it can be used to cancel the
 539  * operation, in which case @error (if non-%NULL) will be set to
 540  * %G_IO_ERROR_CANCELLED.
 541  *
 542  * Returns: a hostname (either ASCII-only, or in ASCII-encoded
 543  *     form), or %NULL on error.
 544  *
 545  * Since: 2.22
 546  */
 547 gchar *
 548 g_resolver_lookup_by_address (GResolver     *resolver,
 549                               GInetAddress  *address,
 550                               GCancellable  *cancellable,
 551                               GError       **error)
 552 {
 553   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 554   g_return_val_if_fail (G_IS_INET_ADDRESS (address), NULL);
 555
 556   g_resolver_maybe_reload (resolver);
 557   return G_RESOLVER_GET_CLASS (resolver)->
 558     lookup_by_address (resolver, address, cancellable, error);
 559 }
 560
 561 /**
 562  * g_resolver_lookup_by_address_async:
 563  * @resolver: a #GResolver
 564  * @address: the address to reverse-resolve
 565  * @cancellable: (allow-none): a #GCancellable, or %NULL
 566  * @callback: (scope async): callback to call after resolution completes
 567  * @user_data: (closure): data for @callback
 568  *
 569  * Begins asynchronously reverse-resolving @address to determine its
 570  * associated hostname, and eventually calls @callback, which must
 571  * call g_resolver_lookup_by_address_finish() to get the final result.
 572  *
 573  * Since: 2.22
 574  */
 575 void
 576 g_resolver_lookup_by_address_async (GResolver           *resolver,
 577                                     GInetAddress        *address,
 578                                     GCancellable        *cancellable,
 579                                     GAsyncReadyCallback  callback,
 580                                     gpointer             user_data)
 581 {
 582   g_return_if_fail (G_IS_RESOLVER (resolver));
 583   g_return_if_fail (G_IS_INET_ADDRESS (address));
 584
 585   g_resolver_maybe_reload (resolver);
 586   G_RESOLVER_GET_CLASS (resolver)->
 587     lookup_by_address_async (resolver, address, cancellable, callback, user_data);
 588 }
 589
 590 /**
 591  * g_resolver_lookup_by_address_finish:
 592  * @resolver: a #GResolver
 593  * @result: the result passed to your #GAsyncReadyCallback
 594  * @error: return location for a #GError, or %NULL
 595  *
 596  * Retrieves the result of a previous call to
 597  * g_resolver_lookup_by_address_async().
 598  *
 599  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 600  * a value from #GResolverError. If the operation was cancelled,
 601  * @error will be set to %G_IO_ERROR_CANCELLED.
 602  *
 603  * Returns: a hostname (either ASCII-only, or in ASCII-encoded
 604  * form), or %NULL on error.
 605  *
 606  * Since: 2.22
 607  */
 608 gchar *
 609 g_resolver_lookup_by_address_finish (GResolver     *resolver,
 610                                      GAsyncResult  *result,
 611                                      GError       **error)
 612 {
 613   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 614
 615   if (g_async_result_legacy_propagate_error (result, error))
 616     return NULL;
 617
 618   return G_RESOLVER_GET_CLASS (resolver)->
 619     lookup_by_address_finish (resolver, result, error);
 620 }
 621
 622 static gchar *
 623 g_resolver_get_service_rrname (const char *service,
 624                                const char *protocol,
 625                                const char *domain)
 626 {
 627   gchar *rrname, *ascii_domain = NULL;
 628
 629   if (g_hostname_is_non_ascii (domain))
 630     domain = ascii_domain = g_hostname_to_ascii (domain);
 631
 632   rrname = g_strdup_printf ("_%s._%s.%s", service, protocol, domain);
 633
 634   g_free (ascii_domain);
 635   return rrname;
 636 }
 637
 638 /**
 639  * g_resolver_lookup_service:
 640  * @resolver: a #GResolver
 641  * @service: the service type to look up (eg, "ldap")
 642  * @protocol: the networking protocol to use for @service (eg, "tcp")
 643  * @domain: the DNS domain to look up the service in
 644  * @cancellable: (allow-none): a #GCancellable, or %NULL
 645  * @error: return location for a #GError, or %NULL
 646  *
 647  * Synchronously performs a DNS SRV lookup for the given @service and
 648  * @protocol in the given @domain and returns an array of #GSrvTarget.
 649  * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
 650  * @service and @protocol arguments do not include the leading underscore
 651  * that appears in the actual DNS entry.
 652  *
 653  * On success, g_resolver_lookup_service() will return a non-empty #GList of
 654  * #GSrvTarget, sorted in order of preference. (That is, you should
 655  * attempt to connect to the first target first, then the second if
 656  * the first fails, etc.)
 657  *
 658  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 659  * a value from #GResolverError and %NULL will be returned.
 660  *
 661  * If @cancellable is non-%NULL, it can be used to cancel the
 662  * operation, in which case @error (if non-%NULL) will be set to
 663  * %G_IO_ERROR_CANCELLED.
 664  *
 665  * If you are planning to connect to the service, it is usually easier
 666  * to create a #GNetworkService and use its #GSocketConnectable
 667  * interface.
 668  *
 669  * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
 670  * #GSrvTarget, or %NULL on error. You must free each of the targets and the
 671  * list when you are done with it. (You can use g_resolver_free_targets() to do
 672  * this.)
 673  *
 674  * Since: 2.22
 675  */
 676 GList *
 677 g_resolver_lookup_service (GResolver     *resolver,
 678                            const gchar   *service,
 679                            const gchar   *protocol,
 680                            const gchar   *domain,
 681                            GCancellable  *cancellable,
 682                            GError       **error)
 683 {
 684   GList *targets;
 685   gchar *rrname;
 686
 687   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 688   g_return_val_if_fail (service != NULL, NULL);
 689   g_return_val_if_fail (protocol != NULL, NULL);
 690   g_return_val_if_fail (domain != NULL, NULL);
 691
 692   rrname = g_resolver_get_service_rrname (service, protocol, domain);
 693
 694   g_resolver_maybe_reload (resolver);
 695   targets = G_RESOLVER_GET_CLASS (resolver)->
 696     lookup_service (resolver, rrname, cancellable, error);
 697
 698   g_free (rrname);
 699   return targets;
 700 }
 701
 702 /**
 703  * g_resolver_lookup_service_async:
 704  * @resolver: a #GResolver
 705  * @service: the service type to look up (eg, "ldap")
 706  * @protocol: the networking protocol to use for @service (eg, "tcp")
 707  * @domain: the DNS domain to look up the service in
 708  * @cancellable: (allow-none): a #GCancellable, or %NULL
 709  * @callback: (scope async): callback to call after resolution completes
 710  * @user_data: (closure): data for @callback
 711  *
 712  * Begins asynchronously performing a DNS SRV lookup for the given
 713  * @service and @protocol in the given @domain, and eventually calls
 714  * @callback, which must call g_resolver_lookup_service_finish() to
 715  * get the final result. See g_resolver_lookup_service() for more
 716  * details.
 717  *
 718  * Since: 2.22
 719  */
 720 void
 721 g_resolver_lookup_service_async (GResolver           *resolver,
 722                                  const gchar         *service,
 723                                  const gchar         *protocol,
 724                                  const gchar         *domain,
 725                                  GCancellable        *cancellable,
 726                                  GAsyncReadyCallback  callback,
 727                                  gpointer             user_data)
 728 {
 729   gchar *rrname;
 730
 731   g_return_if_fail (G_IS_RESOLVER (resolver));
 732   g_return_if_fail (service != NULL);
 733   g_return_if_fail (protocol != NULL);
 734   g_return_if_fail (domain != NULL);
 735
 736   rrname = g_resolver_get_service_rrname (service, protocol, domain);
 737
 738   g_resolver_maybe_reload (resolver);
 739   G_RESOLVER_GET_CLASS (resolver)->
 740     lookup_service_async (resolver, rrname, cancellable, callback, user_data);
 741
 742   g_free (rrname);
 743 }
 744
 745 /**
 746  * g_resolver_lookup_service_finish:
 747  * @resolver: a #GResolver
 748  * @result: the result passed to your #GAsyncReadyCallback
 749  * @error: return location for a #GError, or %NULL
 750  *
 751  * Retrieves the result of a previous call to
 752  * g_resolver_lookup_service_async().
 753  *
 754  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 755  * a value from #GResolverError. If the operation was cancelled,
 756  * @error will be set to %G_IO_ERROR_CANCELLED.
 757  *
 758  * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of
 759  * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more
 760  * details.
 761  *
 762  * Since: 2.22
 763  */
 764 GList *
 765 g_resolver_lookup_service_finish (GResolver     *resolver,
 766                                   GAsyncResult  *result,
 767                                   GError       **error)
 768 {
 769   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 770
 771   if (g_async_result_legacy_propagate_error (result, error))
 772     return NULL;
 773
 774   return G_RESOLVER_GET_CLASS (resolver)->
 775     lookup_service_finish (resolver, result, error);
 776 }
 777
 778 /**
 779  * g_resolver_free_targets: (skip)
 780  * @targets: a #GList of #GSrvTarget
 781  *
 782  * Frees @targets (which should be the return value from
 783  * g_resolver_lookup_service() or g_resolver_lookup_service_finish()).
 784  * (This is a convenience method; you can also simply free the
 785  * results by hand.)
 786  *
 787  * Since: 2.22
 788  */
 789 void
 790 g_resolver_free_targets (GList *targets)
 791 {
 792   GList *t;
 793
 794   for (t = targets; t; t = t->next)
 795     g_srv_target_free (t->data);
 796   g_list_free (targets);
 797 }
 798
 799 /**
 800  * g_resolver_lookup_records:
 801  * @resolver: a #GResolver
 802  * @rrname: the DNS name to lookup the record for
 803  * @record_type: the type of DNS record to lookup
 804  * @cancellable: (allow-none): a #GCancellable, or %NULL
 805  * @error: return location for a #GError, or %NULL
 806  *
 807  * Synchronously performs a DNS record lookup for the given @rrname and returns
 808  * a list of records as #GVariant tuples. See #GResolverRecordType for
 809  * information on what the records contain for each @record_type.
 810  *
 811  * If the DNS resolution fails, @error (if non-%NULL) will be set to
 812  * a value from #GResolverError and %NULL will be returned.
 813  *
 814  * If @cancellable is non-%NULL, it can be used to cancel the
 815  * operation, in which case @error (if non-%NULL) will be set to
 816  * %G_IO_ERROR_CANCELLED.
 817  *
 818  * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
 819  * #GVariant, or %NULL on error. You must free each of the records and the list
 820  * when you are done with it. (You can use g_list_free_full() with
 821  * g_variant_unref() to do this.)
 822  *
 823  * Since: 2.34
 824  */
 825 GList *
 826 g_resolver_lookup_records (GResolver            *resolver,
 827                            const gchar          *rrname,
 828                            GResolverRecordType   record_type,
 829                            GCancellable         *cancellable,
 830                            GError              **error)
 831 {
 832   GList *records;
 833
 834   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 835   g_return_val_if_fail (rrname != NULL, NULL);
 836
 837   g_resolver_maybe_reload (resolver);
 838   records = G_RESOLVER_GET_CLASS (resolver)->
 839     lookup_records (resolver, rrname, record_type, cancellable, error);
 840
 841   return records;
 842 }
 843
 844 /**
 845  * g_resolver_lookup_records_async:
 846  * @resolver: a #GResolver
 847  * @rrname: the DNS name to lookup the record for
 848  * @record_type: the type of DNS record to lookup
 849  * @cancellable: (allow-none): a #GCancellable, or %NULL
 850  * @callback: (scope async): callback to call after resolution completes
 851  * @user_data: (closure): data for @callback
 852  *
 853  * Begins asynchronously performing a DNS lookup for the given
 854  * @rrname, and eventually calls @callback, which must call
 855  * g_resolver_lookup_records_finish() to get the final result. See
 856  * g_resolver_lookup_records() for more details.
 857  *
 858  * Since: 2.34
 859  */
 860 void
 861 g_resolver_lookup_records_async (GResolver           *resolver,
 862                                  const gchar         *rrname,
 863                                  GResolverRecordType  record_type,
 864                                  GCancellable        *cancellable,
 865                                  GAsyncReadyCallback  callback,
 866                                  gpointer             user_data)
 867 {
 868   g_return_if_fail (G_IS_RESOLVER (resolver));
 869   g_return_if_fail (rrname != NULL);
 870
 871   g_resolver_maybe_reload (resolver);
 872   G_RESOLVER_GET_CLASS (resolver)->
 873     lookup_records_async (resolver, rrname, record_type, cancellable, callback, user_data);
 874 }
 875
 876 /**
 877  * g_resolver_lookup_records_finish:
 878  * @resolver: a #GResolver
 879  * @result: the result passed to your #GAsyncReadyCallback
 880  * @error: return location for a #GError, or %NULL
 881  *
 882  * Retrieves the result of a previous call to
 883  * g_resolver_lookup_records_async(). Returns a non-empty list of records as
 884  * #GVariant tuples. See #GResolverRecordType for information on what the
 885  * records contain.
 886  *
 887  * If the DNS resolution failed, @error (if non-%NULL) will be set to
 888  * a value from #GResolverError. If the operation was cancelled,
 889  * @error will be set to %G_IO_ERROR_CANCELLED.
 890  *
 891  * Returns: (element-type GVariant) (transfer full): a non-empty #GList of
 892  * #GVariant, or %NULL on error. You must free each of the records and the list
 893  * when you are done with it. (You can use g_list_free_full() with
 894  * g_variant_unref() to do this.)
 895  *
 896  * Since: 2.34
 897  */
 898 GList *
 899 g_resolver_lookup_records_finish (GResolver     *resolver,
 900                                   GAsyncResult  *result,
 901                                   GError       **error)
 902 {
 903   g_return_val_if_fail (G_IS_RESOLVER (resolver), NULL);
 904   return G_RESOLVER_GET_CLASS (resolver)->
 905     lookup_records_finish (resolver, result, error);
 906 }
 907
 908 guint64
 909 g_resolver_get_serial (GResolver *resolver)
 910 {
 911   g_return_val_if_fail (G_IS_RESOLVER (resolver), 0);
 912
 913   g_resolver_maybe_reload (resolver);
 914
 915 #ifdef G_OS_UNIX
 916   return (guint64) resolver->priv->resolv_conf_timestamp;
 917 #else
 918   return 1;
 919 #endif
 920 }
 921
 922 /**
 923  * g_resolver_error_quark:
 924  *
 925  * Gets the #GResolver Error Quark.
 926  *
 927  * Returns: a #GQuark.
 928  *
 929  * Since: 2.22
 930  */
 931 G_DEFINE_QUARK (g-resolver-error-quark, g_resolver_error)