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: (allow-none): 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
 102   address = g_socket_address_enumerator_next (enumerator, cancellable, &error);
 103   if (error)
 104     g_task_return_error (task, error);
 105   else
 106     g_task_return_pointer (task, address, g_object_unref);
 107
 108   g_object_unref (task);
 109 }
 110
 111 /**
 112  * g_socket_address_enumerator_next_async:
 113  * @enumerator: a #GSocketAddressEnumerator
 114  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 115  * @callback: (scope async): a #GAsyncReadyCallback to call when the request
 116  *     is satisfied
 117  * @user_data: (closure): the data to pass to callback function
 118  *
 119  * Asynchronously retrieves the next #GSocketAddress from @enumerator
 120  * and then calls @callback, which must call
 121  * g_socket_address_enumerator_next_finish() to get the result.
 122  */
 123 void
 124 g_socket_address_enumerator_next_async (GSocketAddressEnumerator *enumerator,
 125                                         GCancellable             *cancellable,
 126                                         GAsyncReadyCallback       callback,
 127                                         gpointer                  user_data)
 128 {
 129   GSocketAddressEnumeratorClass *klass;
 130
 131   g_return_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator));
 132
 133   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 134
 135   (* klass->next_async) (enumerator, cancellable, callback, user_data);
 136 }
 137
 138 static GSocketAddress *
 139 g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator  *enumerator,
 140                                               GAsyncResult              *result,
 141                                               GError                   **error)
 142 {
 143   g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
 144
 145   return g_task_propagate_pointer (G_TASK (result), error);
 146 }
 147
 148 /**
 149  * g_socket_address_enumerator_next_finish:
 150  * @enumerator: a #GSocketAddressEnumerator
 151  * @result: a #GAsyncResult
 152  * @error: a #GError
 153  *
 154  * Retrieves the result of a completed call to
 155  * g_socket_address_enumerator_next_async(). See
 156  * g_socket_address_enumerator_next() for more information about
 157  * error handling.
 158  *
 159  * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
 160  *     error (in which case *@error will be set) or if there are no
 161  *     more addresses.
 162  */
 163 GSocketAddress *
 164 g_socket_address_enumerator_next_finish (GSocketAddressEnumerator  *enumerator,
 165                                          GAsyncResult              *result,
 166                                          GError                   **error)
 167 {
 168   GSocketAddressEnumeratorClass *klass;
 169
 170   g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
 171
 172   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 173
 174   return (* klass->next_finish) (enumerator, result, error);
 175 }