gio/gsocketaddressenumerator.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2008 Red Hat, Inc.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #include "config.h"
  20 #include "gsocketaddressenumerator.h"
  21 #include "glibintl.h"
  22
  23 #include "gtask.h"
  24
  25
  26 G_DEFINE_ABSTRACT_TYPE (GSocketAddressEnumerator, g_socket_address_enumerator, G_TYPE_OBJECT);
  27
  28 static void            g_socket_address_enumerator_real_next_async  (GSocketAddressEnumerator  *enumerator,
  29                                                                      GCancellable              *cancellable,
  30                                                                      GAsyncReadyCallback        callback,
  31                                                                      gpointer                   user_data);
  32 static GSocketAddress *g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator  *enumerator,
  33                                                                      GAsyncResult              *result,
  34                                                                      GError                   **error);
  35
  36 static void
  37 g_socket_address_enumerator_init (GSocketAddressEnumerator *enumerator)
  38 {
  39 }
  40
  41 static void
  42 g_socket_address_enumerator_class_init (GSocketAddressEnumeratorClass *enumerator_class)
  43 {
  44   enumerator_class->next_async = g_socket_address_enumerator_real_next_async;
  45   enumerator_class->next_finish = g_socket_address_enumerator_real_next_finish;
  46 }
  47
  48 /**
  49  * g_socket_address_enumerator_next:
  50  * @enumerator: a #GSocketAddressEnumerator
  51  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  52  * @error: a #GError.
  53  *
  54  * Retrieves the next #GSocketAddress from @enumerator. Note that this
  55  * may block for some amount of time. (Eg, a #GNetworkAddress may need
  56  * to do a DNS lookup before it can return an address.) Use
  57  * g_socket_address_enumerator_next_async() if you need to avoid
  58  * blocking.
  59  *
  60  * If @enumerator is expected to yield addresses, but for some reason
  61  * is unable to (eg, because of a DNS error), then the first call to
  62  * g_socket_address_enumerator_next() will return an appropriate error
  63  * in *@error. However, if the first call to
  64  * g_socket_address_enumerator_next() succeeds, then any further
  65  * internal errors (other than @cancellable being triggered) will be
  66  * ignored.
  67  *
  68  * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
  69  *     error (in which case *@error will be set) or if there are no
  70  *     more addresses.
  71  */
  72 GSocketAddress *
  73 g_socket_address_enumerator_next (GSocketAddressEnumerator  *enumerator,
  74                                   GCancellable              *cancellable,
  75                                   GError                   **error)
  76 {
  77   GSocketAddressEnumeratorClass *klass;
  78
  79   g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
  80
  81   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
  82
  83   return (* klass->next) (enumerator, cancellable, error);
  84 }
  85
  86 /* Default implementation just calls the synchronous method; this can
  87  * be used if the implementation already knows all of its addresses,
  88  * and so the synchronous method will never block.
  89  */
  90 static void
  91 g_socket_address_enumerator_real_next_async (GSocketAddressEnumerator *enumerator,
  92                                              GCancellable             *cancellable,
  93                                              GAsyncReadyCallback       callback,
  94                                              gpointer                  user_data)
  95 {
  96   GTask *task;
  97   GSocketAddress *address;
  98   GError *error = NULL;
  99
 100   task = g_task_new (enumerator, NULL, callback, user_data);
 101   g_task_set_source_tag (task, g_socket_address_enumerator_real_next_async);
 102
 103   address = g_socket_address_enumerator_next (enumerator, cancellable, &error);
 104   if (error)
 105     g_task_return_error (task, error);
 106   else
 107     g_task_return_pointer (task, address, g_object_unref);
 108
 109   g_object_unref (task);
 110 }
 111
 112 /**
 113  * g_socket_address_enumerator_next_async:
 114  * @enumerator: a #GSocketAddressEnumerator
 115  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
 116  * @callback: (scope async): a #GAsyncReadyCallback to call when the request
 117  *     is satisfied
 118  * @user_data: (closure): the data to pass to callback function
 119  *
 120  * Asynchronously retrieves the next #GSocketAddress from @enumerator
 121  * and then calls @callback, which must call
 122  * g_socket_address_enumerator_next_finish() to get the result.
 123  */
 124 void
 125 g_socket_address_enumerator_next_async (GSocketAddressEnumerator *enumerator,
 126                                         GCancellable             *cancellable,
 127                                         GAsyncReadyCallback       callback,
 128                                         gpointer                  user_data)
 129 {
 130   GSocketAddressEnumeratorClass *klass;
 131
 132   g_return_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator));
 133
 134   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 135
 136   (* klass->next_async) (enumerator, cancellable, callback, user_data);
 137 }
 138
 139 static GSocketAddress *
 140 g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator  *enumerator,
 141                                               GAsyncResult              *result,
 142                                               GError                   **error)
 143 {
 144   g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
 145
 146   return g_task_propagate_pointer (G_TASK (result), error);
 147 }
 148
 149 /**
 150  * g_socket_address_enumerator_next_finish:
 151  * @enumerator: a #GSocketAddressEnumerator
 152  * @result: a #GAsyncResult
 153  * @error: a #GError
 154  *
 155  * Retrieves the result of a completed call to
 156  * g_socket_address_enumerator_next_async(). See
 157  * g_socket_address_enumerator_next() for more information about
 158  * error handling.
 159  *
 160  * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
 161  *     error (in which case *@error will be set) or if there are no
 162  *     more addresses.
 163  */
 164 GSocketAddress *
 165 g_socket_address_enumerator_next_finish (GSocketAddressEnumerator  *enumerator,
 166                                          GAsyncResult              *result,
 167                                          GError                   **error)
 168 {
 169   GSocketAddressEnumeratorClass *klass;
 170
 171   g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
 172
 173   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 174
 175   return (* klass->next_finish) (enumerator, result, error);
 176 }