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