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