gio/gsocketconnectable.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 "gsocketconnectable.h"
  23 #include "glibintl.h"
  24
  25
  26 /**
  27  * SECTION:gsocketconnectable
  28  * @short_description: Interface for potential socket endpoints
  29  *
  30  * Objects that describe one or more potential socket endpoints
  31  * implement #GSocketConnectable. Callers can then use
  32  * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator
  33  * to try out each socket address in turn until one succeeds, as shown
  34  * in the sample code below.
  35  *
  36  * |[
  37  * MyConnectionType *
  38  * connect_to_host (const char    *hostname,
  39  *                  guint16        port,
  40  *                  GCancellable  *cancellable,
  41  *                  GError       **error)
  42  * {
  43  *   MyConnection *conn = NULL;
  44  *   GSocketConnectable *addr;
  45  *   GSocketAddressEnumerator *enumerator;
  46  *   GSocketAddress *sockaddr;
  47  *   GError *conn_error = NULL;
  48  *
  49  *   addr = g_network_address_new (hostname, port);
  50  *   enumerator = g_socket_connectable_enumerate (addr);
  51  *   g_object_unref (addr);
  52  *
  53  *   /<!-- -->* Try each sockaddr until we succeed. Record the first
  54  *    * connection error, but not any further ones (since they'll probably
  55  *    * be basically the same as the first).
  56  *    *<!-- -->/
  57  *   while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
  58  *     {
  59  *       conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
  60  *       g_object_unref (sockaddr);
  61  *     }
  62  *   g_object_unref (enumerator);
  63  *
  64  *   if (conn)
  65  *     {
  66  *       if (conn_error)
  67  *         {
  68  *           /<!-- -->* We couldn't connect to the first address, but we succeeded
  69  *            * in connecting to a later address.
  70  *            *<!-- -->/
  71  *           g_error_free (conn_error);
  72  *         }
  73  *       return conn;
  74  *     }
  75  *   else if (error)
  76  *     {
  77  *       /<!-- -->* Either the initial lookup failed, or else the caller
  78  *        * cancelled us.
  79  *        *<!-- -->/
  80  *       if (conn_error)
  81  *         g_error_free (conn_error);
  82  *       return NULL;
  83  *     }
  84  *   else
  85  *     {
  86  *       g_error_propagate (error, conn_error);
  87  *       return NULL;
  88  *     }
  89  * }
  90  * ]|
  91  */
  92
  93
  94 typedef GSocketConnectableIface GSocketConnectableInterface;
  95 G_DEFINE_INTERFACE (GSocketConnectable, g_socket_connectable, G_TYPE_OBJECT)
  96
  97 static void
  98 g_socket_connectable_default_init (GSocketConnectableInterface *iface)
  99 {
 100 }
 101
 102 /**
 103  * g_socket_connectable_enumerate:
 104  * @connectable: a #GSocketConnectable
 105  *
 106  * Creates a #GSocketAddressEnumerator for @connectable.
 107  *
 108  * Return value: (transfer full): a new #GSocketAddressEnumerator.
 109  *
 110  * Since: 2.22
 111  */
 112 GSocketAddressEnumerator *
 113 g_socket_connectable_enumerate (GSocketConnectable *connectable)
 114 {
 115   GSocketConnectableIface *iface;
 116
 117   g_return_val_if_fail (G_IS_SOCKET_CONNECTABLE (connectable), NULL);
 118
 119   iface = G_SOCKET_CONNECTABLE_GET_IFACE (connectable);
 120
 121   return (* iface->enumerate) (connectable);
 122 }
 123
 124 /**
 125  * g_socket_connectable_proxy_enumerate:
 126  * @connectable: a #GSocketConnectable
 127  *
 128  * Creates a #GSocketAddressEnumerator for @connectable that will
 129  * return #GProxyAddress<!-- -->es for addresses that you must connect
 130  * to via a proxy.
 131  *
 132  * If @connectable does not implement
 133  * g_socket_connectable_proxy_enumerate(), this will fall back to
 134  * calling g_socket_connectable_enumerate().
 135  *
 136  * Return value: (transfer full): a new #GSocketAddressEnumerator.
 137  *
 138  * Since: 2.26
 139  */
 140 GSocketAddressEnumerator *
 141 g_socket_connectable_proxy_enumerate (GSocketConnectable *connectable)
 142 {
 143   GSocketConnectableIface *iface;
 144
 145   g_return_val_if_fail (G_IS_SOCKET_CONNECTABLE (connectable), NULL);
 146
 147   iface = G_SOCKET_CONNECTABLE_GET_IFACE (connectable);
 148
 149   if (iface->proxy_enumerate)
 150     return (* iface->proxy_enumerate) (connectable);
 151   else
 152     return (* iface->enumerate) (connectable);
 153 }