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