Added GProxy interface for proxy extension point

Implement an extension point for proxy protocol implementation. This
is mainly useful for socket-based proxy where it is possible to use the
proxied socket the same way it would for other stream based socket.

Reviewed-by: Dan Winship <danw@gnome.org>

docs/reference/gio/gio-docs.xml

@@ -109,6 +109,7 @@
       <xi:include href="xml/gunixfdmessage.xml"/>
       <xi:include href="xml/gcredentials.xml"/>
       <xi:include href="xml/gunixcredentialsmessage.xml"/>
+      <xi:include href="xml/gproxy.xml"/>
       <xi:include href="xml/gproxyaddress.xml"/>
     </chapter>
     <chapter id="highlevel-socket">

docs/reference/gio/gio-sections.txt

@@ -2811,3 +2811,22 @@ G_TYPE_PROXY_ADDRESS
 GProxyAddressPrivate
 g_proxy_address_get_type
 </SECTION>
+
+<SECTION>
+<FILE>gproxy</FILE>
+<TITLE>GProxy</TITLE>
+GProxy
+GProxyIface
+g_proxy_connect
+g_proxy_connect_async
+g_proxy_connect_finish
+g_proxy_get_default_for_protocol
+<SUBSECTION Standard>
+G_PROXY
+G_PROXY_EXTENSION_POINT_NAME
+G_PROXY_GET_IFACE
+G_IS_PROXY
+G_TYPE_PROXY
+<SUBSECTION Private>
+g_proxy_get_type
+</SECTION>

docs/reference/gio/gio.types

@@ -76,6 +76,7 @@ g_output_stream_splice_flags_get_type
 g_password_save_get_type
 g_permission_get_type
 g_proxy_address_get_type
+g_proxy_get_type
 g_proxy_resolver_get_type
 g_resolver_error_get_type
 g_resolver_get_type

gio/Makefile.am

@@ -350,6 +350,7 @@ libgio_2_0_la_SOURCES =		\
 	gsocketlistener.c	\
 	gsocketoutputstream.c	\
 	gsocketoutputstream.h	\
+	gproxy.c		\
 	gproxyaddress.c         \
 	gsocketservice.c	\
 	gsrvtarget.c		\
@@ -483,6 +484,7 @@ gio_headers =			\
 	goutputstream.h 	\
 	gpermission.h 		\
 	gproxyaddress.h         \
+	gproxy.h		\
 	gproxyresolver.h	\
 	gresolver.h		\
 	gseekable.h 		\

gio/gio.h

@@ -92,6 +92,7 @@
 #include <gio/gnetworkservice.h>
 #include <gio/goutputstream.h>
 #include <gio/gpermission.h>
+#include <gio/gproxy.h>
 #include <gio/gproxyaddress.h>
 #include <gio/gproxyresolver.h>
 #include <gio/gresolver.h>

gio/gio.symbols

@@ -1128,6 +1128,17 @@ g_socket_address_to_native
 #endif
 #endif
 
+#if IN_HEADER(__G_PROXY_H__)
+#if IN_FILE(__G_PROXY_C__)
+g_proxy_get_type
+g_proxy_get_default_for_protocol
+g_proxy_connect
+g_proxy_connect_async
+g_proxy_connect_finish
+g_proxy_supports_hostname
+#endif
+#endif
+
 #if IN_HEADER(__G_PROXY_RESOLVER_H__)
 #if IN_FILE(__G_PROXY_RESOLVER_C__)
 g_proxy_resolver_get_default

gio/giomodule.c

@@ -31,6 +31,7 @@
 #include "glocaldirectorymonitor.h"
 #include "gnativevolumemonitor.h"
 #include "gproxyresolver.h"
+#include "gproxy.h"
 #include "gvfs.h"
 #ifdef G_OS_UNIX
 #include "gdesktopappinfo.h"
@@ -540,6 +541,9 @@ _g_io_modules_ensure_extension_points_registered (void)
 
       ep = g_io_extension_point_register (G_PROXY_RESOLVER_EXTENSION_POINT_NAME);
       g_io_extension_point_set_required_type (ep, G_TYPE_PROXY_RESOLVER);
+
+      ep = g_io_extension_point_register (G_PROXY_EXTENSION_POINT_NAME);
+      g_io_extension_point_set_required_type (ep, G_TYPE_PROXY);
     }
   
   G_UNLOCK (registered_extensions);

gio/giotypes.h

@@ -206,6 +206,7 @@ typedef struct _GVfs                          GVfs; /* Dummy typedef */
  * Since: 2.26
  **/
 typedef struct _GProxyResolver                GProxyResolver;
+typedef struct _GProxy			      GProxy;
 typedef struct _GProxyAddress		      GProxyAddress;
 
 /**

gio/gproxy.c

@@ -0,0 +1,208 @@
+/* GIO - GLib Input, Output and Streaming Library
+ *
+ * Copyright (C) 2010 Collabora Ltd.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General
+ * Public License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
+ */
+
+#include "config.h"
+
+#include "gproxy.h"
+
+#include "giomodule.h"
+#include "giomodule-priv.h"
+#include "glibintl.h"
+
+/**
+ * SECTION:gproxy
+ * @short_description: Interface for proxy handling
+ *
+ * A #GProxy handles connecting to a remote host via a given type of
+ * proxy server. It is implemented by the 'gio-proxy' extension point.
+ * The extensions are named after their proxy protocol name. As an
+ * example, a SOCKS5 proxy implementation can be retrieved with the
+ * name 'socks5' using the function
+ * g_io_extension_point_get_extension_by_name().
+ *
+ * Since: 2.26
+ **/
+
+G_DEFINE_INTERFACE (GProxy, g_proxy, G_TYPE_OBJECT)
+
+static void
+g_proxy_default_init (GProxyInterface *iface)
+{
+}
+
+/**
+ * g_proxy_get_default_for_protocol:
+ * @protocol: the proxy protocol name (e.g. http, socks, etc)
+ *
+ * Lookup "gio-proxy" extension point for a proxy implementation that supports
+ * specified protocol.
+ *
+ * Return value: return a #GProxy or NULL if protocol is not supported.
+ *
+ * Since: 2.26
+ **/
+GProxy *
+g_proxy_get_default_for_protocol (const gchar *protocol)
+{
+  GIOExtensionPoint *ep;
+  GIOExtension *extension;
+
+  /* Ensure proxy modules loaded */
+  _g_io_modules_ensure_loaded ();
+
+  ep = g_io_extension_point_lookup (G_PROXY_EXTENSION_POINT_NAME);
+
+  extension = g_io_extension_point_get_extension_by_name (ep, protocol);
+
+  if (extension)
+      return g_object_new (g_io_extension_get_type (extension), NULL);
+
+  return NULL;
+}
+
+/**
+ * g_proxy_connect:
+ * @proxy: a #GProxy
+ * @io_stream: a #GIOStream
+ * @proxy_address: a #GProxyAddress
+ * @cancellable: a #GCancellable
+ * @error: return #GError
+ *
+ * Given @io_stream to communicate with a proxy (eg, a
+ * #GSocketConnection that is connected to the proxy server), this
+ * does the necessary handshake to connect to @proxy_address, and if
+ * required, wraps the #GIOStream to handle proxy payload.
+ *
+ * Return value: a #GIOStream that will replace @io_stream. This might
+ *               be the same as @io_stream, in which case a reference
+ *               will be added.
+ *
+ * Since: 2.26
+ */
+GIOStream *
+g_proxy_connect (GProxy            *proxy,
+		 GIOStream         *io_stream,
+		 GProxyAddress     *proxy_address,
+		 GCancellable      *cancellable,
+		 GError           **error)
+{
+  GProxyInterface *iface;
+
+  g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
+
+  iface = G_PROXY_GET_IFACE (proxy);
+
+  return (* iface->connect) (proxy,
+			     io_stream,
+			     proxy_address,
+			     cancellable,
+			     error);
+}
+
+/**
+ * g_proxy_connect_async:
+ * @proxy: a #GProxy
+ * @io-stream: a #GIOStream
+ * @proxy_address: a #GProxyAddress
+ * @cancellable: a #GCancellable
+ * @callback: a #GAsyncReadyCallback
+ * @user_data: callback data
+ *
+ * Asynchronous version of g_proxy_connect().
+ *
+ * Since: 2.26
+ */
+void
+g_proxy_connect_async (GProxy               *proxy,
+		       GIOStream            *io_stream,
+		       GProxyAddress        *proxy_address,
+		       GCancellable         *cancellable,
+		       GAsyncReadyCallback   callback,
+		       gpointer              user_data)
+{
+  GProxyInterface *iface;
+
+  g_return_if_fail (G_IS_PROXY (proxy));
+
+  iface = G_PROXY_GET_IFACE (proxy);
+
+  (* iface->connect_async) (proxy,
+			    io_stream,
+			    proxy_address,
+			    cancellable,
+			    callback,
+			    user_data);
+}
+
+/**
+ * g_proxy_connect_finish:
+ * @proxy: a #GProxy
+ * @result: a #GAsyncRetult
+ * @error: return #GError
+ *
+ * See g_proxy_connect().
+ *
+ * Return value: a #GIOStream.
+ *
+ * Since: 2.26
+ */
+GIOStream *
+g_proxy_connect_finish (GProxy       *proxy,
+			GAsyncResult *result,
+			GError      **error)
+{
+  GProxyInterface *iface;
+
+  g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
+
+  iface = G_PROXY_GET_IFACE (proxy);
+
+  return (* iface->connect_finish) (proxy, result, error);
+}
+
+/**
+ * g_proxy_supports_hostname:
+ * @proxy: a #GProxy
+ *
+ * Some proxy protocols expect to be passed a hostname, which they
+ * will resolve to an IP address themselves. Others, like SOCKS4, do
+ * not allow this. This function will return %FALSE if @proxy is
+ * implementing such a protocol. When %FALSE is returned, the caller
+ * should resolve the destination hostname first, and then pass a
+ * #GProxyAddress containing the stringified IP address to
+ * g_proxy_connect() or g_proxy_connect_async().
+ *
+ * Return value: %TRUE if hostname resolution is supported.
+ *
+ * Since: 2.26
+ */
+gboolean
+g_proxy_supports_hostname (GProxy *proxy)
+{
+  GProxyInterface *iface;
+
+  g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
+
+  iface = G_PROXY_GET_IFACE (proxy);
+
+  return (* iface->supports_hostname) (proxy);
+}

gio/gproxy.h

@@ -0,0 +1,123 @@
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
+
+/* GIO - GLib Input, Output and Streaming Library
+ *
+ * Copyright (C) 2010 Collabora Ltd.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General
+ * Public License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
+ */
+
+#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
+#error "Only <gio/gio.h> can be included directly."
+#endif
+
+#ifndef __G_PROXY_H__
+#define __G_PROXY_H__
+
+#include <gio/giotypes.h>
+
+G_BEGIN_DECLS
+
+#define G_TYPE_PROXY		(g_proxy_get_type ())
+#define G_PROXY(o)		(G_TYPE_CHECK_INSTANCE_CAST ((o), G_TYPE_PROXY, GProxy))
+#define G_IS_PROXY(o)		(G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_PROXY))
+#define G_PROXY_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_PROXY, GProxyInterface))
+
+/**
+ * G_PROXY_EXTENSION_POINT_NAME:
+ *
+ * Extension point for proxy functionality.
+ * See <link linkend="extending-gio">Extending GIO</link>.
+ *
+ * Since: 2.26
+ */
+#define G_PROXY_EXTENSION_POINT_NAME "gio-proxy"
+
+/**
+ * GProxy:
+ *
+ * Interface that handles proxy connection and payload.
+ *
+ * Since: 2.26
+ */
+typedef struct _GProxyInterface GProxyInterface;
+
+/**
+ * GProxyInterface:
+ * @g_iface: The parent interface.
+ * @connect: Connect to proxy server and wrap (if required) the #connection
+ *           to handle payload.
+ * @connect_async: Same has connect() but asynchronous.
+ * @connect_finish: Returns the result of connect_async()
+ *
+ * Provides an interface for handling proxy connection and payload.
+ *
+ * Since: 2.26
+ */
+struct _GProxyInterface
+{
+  GTypeInterface g_iface;
+
+  /* Virtual Table */
+
+  GIOStream * (* connect)           (GProxy               *proxy,
+				     GIOStream            *connection,
+				     GProxyAddress        *proxy_address,
+				     GCancellable         *cancellable,
+				     GError              **error);
+
+  void        (* connect_async)     (GProxy               *proxy,
+				     GIOStream            *connection,
+				     GProxyAddress	  *proxy_address,
+				     GCancellable         *cancellable,
+				     GAsyncReadyCallback   callback,
+				     gpointer              user_data);
+
+  GIOStream * (* connect_finish)    (GProxy               *proxy,
+				     GAsyncResult         *result,
+				     GError              **error);
+
+  gboolean    (* supports_hostname) (GProxy             *proxy);
+};
+
+GType      g_proxy_get_type                 (void) G_GNUC_CONST;
+
+GProxy    *g_proxy_get_default_for_protocol (const gchar *protocol);
+
+GIOStream *g_proxy_connect           (GProxy               *proxy,
+				      GIOStream            *connection,
+				      GProxyAddress        *proxy_address,
+				      GCancellable         *cancellable,
+				      GError              **error);
+
+void       g_proxy_connect_async     (GProxy               *proxy,
+				      GIOStream            *connection,
+				      GProxyAddress        *proxy_address,
+				      GCancellable         *cancellable,
+				      GAsyncReadyCallback   callback,
+				      gpointer              user_data);
+
+GIOStream *g_proxy_connect_finish    (GProxy               *proxy,
+				      GAsyncResult         *result,
+				      GError              **error);
+
+gboolean   g_proxy_supports_hostname (GProxy               *proxy);
+
+G_END_DECLS
+
+#endif /* __G_PROXY_H__ */