gio/gproxy.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2010 Collabora Ltd.
   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  * Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
  21  */
  22
  23 #include "config.h"
  24
  25 #include "gproxy.h"
  26
  27 #include "giomodule.h"
  28 #include "giomodule-priv.h"
  29 #include "glibintl.h"
  30
  31 /**
  32  * SECTION:gproxy
  33  * @short_description: Interface for proxy handling
  34  *
  35  * A #GProxy handles connecting to a remote host via a given type of
  36  * proxy server. It is implemented by the 'gio-proxy' extension point.
  37  * The extensions are named after their proxy protocol name. As an
  38  * example, a SOCKS5 proxy implementation can be retrieved with the
  39  * name 'socks5' using the function
  40  * g_io_extension_point_get_extension_by_name().
  41  *
  42  * Since: 2.26
  43  **/
  44
  45 G_DEFINE_INTERFACE (GProxy, g_proxy, G_TYPE_OBJECT)
  46
  47 static void
  48 g_proxy_default_init (GProxyInterface *iface)
  49 {
  50 }
  51
  52 /**
  53  * g_proxy_get_default_for_protocol:
  54  * @protocol: the proxy protocol name (e.g. http, socks, etc)
  55  *
  56  * Lookup "gio-proxy" extension point for a proxy implementation that supports
  57  * specified protocol.
  58  *
  59  * Return value: (transfer full): return a #GProxy or NULL if protocol
  60  *               is not supported.
  61  *
  62  * Since: 2.26
  63  **/
  64 GProxy *
  65 g_proxy_get_default_for_protocol (const gchar *protocol)
  66 {
  67   GIOExtensionPoint *ep;
  68   GIOExtension *extension;
  69
  70   /* Ensure proxy modules loaded */
  71   _g_io_modules_ensure_loaded ();
  72
  73   ep = g_io_extension_point_lookup (G_PROXY_EXTENSION_POINT_NAME);
  74
  75   extension = g_io_extension_point_get_extension_by_name (ep, protocol);
  76
  77   if (extension)
  78       return g_object_new (g_io_extension_get_type (extension), NULL);
  79
  80   return NULL;
  81 }
  82
  83 /**
  84  * g_proxy_connect:
  85  * @proxy: a #GProxy
  86  * @connection: a #GIOStream
  87  * @proxy_address: a #GProxyAddress
  88  * @cancellable: (allow-none): a #GCancellable
  89  * @error: return #GError
  90  *
  91  * Given @connection to communicate with a proxy (eg, a
  92  * #GSocketConnection that is connected to the proxy server), this
  93  * does the necessary handshake to connect to @proxy_address, and if
  94  * required, wraps the #GIOStream to handle proxy payload.
  95  *
  96  * Return value: (transfer full): a #GIOStream that will replace @connection. This might
  97  *               be the same as @connection, in which case a reference
  98  *               will be added.
  99  *
 100  * Since: 2.26
 101  */
 102 GIOStream *
 103 g_proxy_connect (GProxy            *proxy,
 104                  GIOStream         *connection,
 105                  GProxyAddress     *proxy_address,
 106                  GCancellable      *cancellable,
 107                  GError           **error)
 108 {
 109   GProxyInterface *iface;
 110
 111   g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
 112
 113   iface = G_PROXY_GET_IFACE (proxy);
 114
 115   return (* iface->connect) (proxy,
 116                              connection,
 117                              proxy_address,
 118                              cancellable,
 119                              error);
 120 }
 121
 122 /**
 123  * g_proxy_connect_async:
 124  * @proxy: a #GProxy
 125  * @connection: a #GIOStream
 126  * @proxy_address: a #GProxyAddress
 127  * @cancellable: (allow-none): a #GCancellable
 128  * @callback: (scope async): a #GAsyncReadyCallback
 129  * @user_data: (closure): callback data
 130  *
 131  * Asynchronous version of g_proxy_connect().
 132  *
 133  * Since: 2.26
 134  */
 135 void
 136 g_proxy_connect_async (GProxy               *proxy,
 137                        GIOStream            *connection,
 138                        GProxyAddress        *proxy_address,
 139                        GCancellable         *cancellable,
 140                        GAsyncReadyCallback   callback,
 141                        gpointer              user_data)
 142 {
 143   GProxyInterface *iface;
 144
 145   g_return_if_fail (G_IS_PROXY (proxy));
 146
 147   iface = G_PROXY_GET_IFACE (proxy);
 148
 149   (* iface->connect_async) (proxy,
 150                             connection,
 151                             proxy_address,
 152                             cancellable,
 153                             callback,
 154                             user_data);
 155 }
 156
 157 /**
 158  * g_proxy_connect_finish:
 159  * @proxy: a #GProxy
 160  * @result: a #GAsyncRetult
 161  * @error: return #GError
 162  *
 163  * See g_proxy_connect().
 164  *
 165  * Return value: (transfer full): a #GIOStream.
 166  *
 167  * Since: 2.26
 168  */
 169 GIOStream *
 170 g_proxy_connect_finish (GProxy       *proxy,
 171                         GAsyncResult *result,
 172                         GError      **error)
 173 {
 174   GProxyInterface *iface;
 175
 176   g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
 177
 178   iface = G_PROXY_GET_IFACE (proxy);
 179
 180   return (* iface->connect_finish) (proxy, result, error);
 181 }
 182
 183 /**
 184  * g_proxy_supports_hostname:
 185  * @proxy: a #GProxy
 186  *
 187  * Some proxy protocols expect to be passed a hostname, which they
 188  * will resolve to an IP address themselves. Others, like SOCKS4, do
 189  * not allow this. This function will return %FALSE if @proxy is
 190  * implementing such a protocol. When %FALSE is returned, the caller
 191  * should resolve the destination hostname first, and then pass a
 192  * #GProxyAddress containing the stringified IP address to
 193  * g_proxy_connect() or g_proxy_connect_async().
 194  *
 195  * Return value: %TRUE if hostname resolution is supported.
 196  *
 197  * Since: 2.26
 198  */
 199 gboolean
 200 g_proxy_supports_hostname (GProxy *proxy)
 201 {
 202   GProxyInterface *iface;
 203
 204   g_return_val_if_fail (G_IS_PROXY (proxy), FALSE);
 205
 206   iface = G_PROXY_GET_IFACE (proxy);
 207
 208   return (* iface->supports_hostname) (proxy);
 209 }