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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22 #include "gsocketaddressenumerator.h"
  23 #include "glibintl.h"
  24
  25 #include "gtask.h"
  26
  27
  28 G_DEFINE_ABSTRACT_TYPE (GSocketAddressEnumerator, g_socket_address_enumerator, G_TYPE_OBJECT);
  29
  30 static void            g_socket_address_enumerator_real_next_async  (GSocketAddressEnumerator  *enumerator,
  31                                                                      GCancellable              *cancellable,
  32                                                                      GAsyncReadyCallback        callback,
  33                                                                      gpointer                   user_data);
  34 static GSocketAddress *g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator  *enumerator,
  35                                                                      GAsyncResult              *result,
  36                                                                      GError                   **error);
  37
  38 static void
  39 g_socket_address_enumerator_init (GSocketAddressEnumerator *enumerator)
  40 {
  41 }
  42
  43 static void
  44 g_socket_address_enumerator_class_init (GSocketAddressEnumeratorClass *enumerator_class)
  45 {
  46   enumerator_class->next_async = g_socket_address_enumerator_real_next_async;
  47   enumerator_class->next_finish = g_socket_address_enumerator_real_next_finish;
  48 }
  49
  50 /**
  51  * g_socket_address_enumerator_next:
  52  * @enumerator: a #GSocketAddressEnumerator
  53  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
  54  * @error: a #GError.
  55  *
  56  * Retrieves the next #GSocketAddress from @enumerator. Note that this
  57  * may block for some amount of time. (Eg, a #GNetworkAddress may need
  58  * to do a DNS lookup before it can return an address.) Use
  59  * g_socket_address_enumerator_next_async() if you need to avoid
  60  * blocking.
  61  *
  62  * If @enumerator is expected to yield addresses, but for some reason
  63  * is unable to (eg, because of a DNS error), then the first call to
  64  * g_socket_address_enumerator_next() will return an appropriate error
  65  * in *@error. However, if the first call to
  66  * g_socket_address_enumerator_next() succeeds, then any further
  67  * internal errors (other than @cancellable being triggered) will be
  68  * ignored.
  69  *
  70  * Return value: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
  71  *     error (in which case *@error will be set) or if there are no
  72  *     more addresses.
  73  */
  74 GSocketAddress *
  75 g_socket_address_enumerator_next (GSocketAddressEnumerator  *enumerator,
  76                                   GCancellable              *cancellable,
  77                                   GError                   **error)
  78 {
  79   GSocketAddressEnumeratorClass *klass;
  80
  81   g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
  82
  83   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
  84
  85   return (* klass->next) (enumerator, cancellable, error);
  86 }
  87
  88 /* Default implementation just calls the synchronous method; this can
  89  * be used if the implementation already knows all of its addresses,
  90  * and so the synchronous method will never block.
  91  */
  92 static void
  93 g_socket_address_enumerator_real_next_async (GSocketAddressEnumerator *enumerator,
  94                                              GCancellable             *cancellable,
  95                                              GAsyncReadyCallback       callback,
  96                                              gpointer                  user_data)
  97 {
  98   GTask *task;
  99   GSocketAddress *address;
 100   GError *error = NULL;
 101
 102   task = g_task_new (enumerator, NULL, callback, user_data);
 103
 104   address = g_socket_address_enumerator_next (enumerator, cancellable, &error);
 105   if (error)
 106     g_task_return_error (task, error);
 107   else
 108     g_task_return_pointer (task, address, g_object_unref);
 109
 110   g_object_unref (task);
 111 }
 112
 113 /**
 114  * g_socket_address_enumerator_next_async:
 115  * @enumerator: a #GSocketAddressEnumerator
 116  * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
 117  * @callback: (scope async): a #GAsyncReadyCallback to call when the request
 118  *     is satisfied
 119  * @user_data: (closure): the data to pass to callback function
 120  *
 121  * Asynchronously retrieves the next #GSocketAddress from @enumerator
 122  * and then calls @callback, which must call
 123  * g_socket_address_enumerator_next_finish() to get the result.
 124  */
 125 void
 126 g_socket_address_enumerator_next_async (GSocketAddressEnumerator *enumerator,
 127                                         GCancellable             *cancellable,
 128                                         GAsyncReadyCallback       callback,
 129                                         gpointer                  user_data)
 130 {
 131   GSocketAddressEnumeratorClass *klass;
 132
 133   g_return_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator));
 134
 135   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 136
 137   (* klass->next_async) (enumerator, cancellable, callback, user_data);
 138 }
 139
 140 static GSocketAddress *
 141 g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator  *enumerator,
 142                                               GAsyncResult              *result,
 143                                               GError                   **error)
 144 {
 145   g_return_val_if_fail (g_task_is_valid (result, enumerator), NULL);
 146
 147   return g_task_propagate_pointer (G_TASK (result), error);
 148 }
 149
 150 /**
 151  * g_socket_address_enumerator_next_finish:
 152  * @enumerator: a #GSocketAddressEnumerator
 153  * @result: a #GAsyncResult
 154  * @error: a #GError
 155  *
 156  * Retrieves the result of a completed call to
 157  * g_socket_address_enumerator_next_async(). See
 158  * g_socket_address_enumerator_next() for more information about
 159  * error handling.
 160  *
 161  * Return value: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
 162  *     error (in which case *@error will be set) or if there are no
 163  *     more addresses.
 164  */
 165 GSocketAddress *
 166 g_socket_address_enumerator_next_finish (GSocketAddressEnumerator  *enumerator,
 167                                          GAsyncResult              *result,
 168                                          GError                   **error)
 169 {
 170   GSocketAddressEnumeratorClass *klass;
 171
 172   g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
 173
 174   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 175
 176   return (* klass->next_finish) (enumerator, result, error);
 177 }