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 "gsimpleasyncresult.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: 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   GSimpleAsyncResult *result;
  99   GSocketAddress *address;
 100   GError *error = NULL;
 101
 102   result = g_simple_async_result_new (G_OBJECT (enumerator),
 103                                       callback, user_data,
 104                                       g_socket_address_enumerator_real_next_async);
 105   address = g_socket_address_enumerator_next (enumerator, cancellable, &error);
 106   if (address)
 107     g_simple_async_result_set_op_res_gpointer (result, address, NULL);
 108   else if (error)
 109     {
 110       g_simple_async_result_set_from_error (result, error);
 111       g_error_free (error);
 112     }
 113   g_simple_async_result_complete_in_idle (result);
 114   g_object_unref (result);
 115 }
 116
 117 /**
 118  * g_socket_address_enumerator_next_async:
 119  * @enumerator: a #GSocketAddressEnumerator
 120  * @cancellable: optional #GCancellable object, %NULL to ignore.
 121  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
 122  * @user_data: the data to pass to callback function
 123  *
 124  * Asynchronously retrieves the next #GSocketAddress from @enumerator
 125  * and then calls @callback, which must call
 126  * g_socket_address_enumerator_next_finish() to get the result.
 127  */
 128 void
 129 g_socket_address_enumerator_next_async (GSocketAddressEnumerator *enumerator,
 130                                         GCancellable             *cancellable,
 131                                         GAsyncReadyCallback       callback,
 132                                         gpointer                  user_data)
 133 {
 134   GSocketAddressEnumeratorClass *klass;
 135
 136   g_return_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator));
 137
 138   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 139
 140   (* klass->next_async) (enumerator, cancellable, callback, user_data);
 141 }
 142
 143 static GSocketAddress *
 144 g_socket_address_enumerator_real_next_finish (GSocketAddressEnumerator  *enumerator,
 145                                               GAsyncResult              *result,
 146                                               GError                   **error)
 147 {
 148   GSimpleAsyncResult *simple;
 149
 150   g_return_val_if_fail (G_IS_SIMPLE_ASYNC_RESULT (result), NULL);
 151   simple = G_SIMPLE_ASYNC_RESULT (result);
 152   g_return_val_if_fail (g_simple_async_result_get_source_tag (simple) == g_socket_address_enumerator_real_next_async, NULL);
 153
 154   if (g_simple_async_result_propagate_error (simple, error))
 155     return NULL;
 156   else
 157     return g_simple_async_result_get_op_res_gpointer (simple);
 158 }
 159
 160 /**
 161  * g_socket_address_enumerator_next_finish:
 162  * @enumerator: a #GSocketAddressEnumerator
 163  * @result: a #GAsyncResult
 164  * @error: a #GError
 165  *
 166  * Retrieves the result of a completed call to
 167  * g_socket_address_enumerator_next_async(). See
 168  * g_socket_address_enumerator_next() for more information about
 169  * error handling.
 170  *
 171  * Return value: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
 172  *     error (in which case *@error will be set) or if there are no
 173  *     more addresses.
 174  */
 175 GSocketAddress *
 176 g_socket_address_enumerator_next_finish (GSocketAddressEnumerator  *enumerator,
 177                                          GAsyncResult              *result,
 178                                          GError                   **error)
 179 {
 180   GSocketAddressEnumeratorClass *klass;
 181
 182   g_return_val_if_fail (G_IS_SOCKET_ADDRESS_ENUMERATOR (enumerator), NULL);
 183
 184   klass = G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS (enumerator);
 185
 186   return (* klass->next_finish) (enumerator, result, error);
 187 }