Merge remote-tracking branch 'gvdb/master'
[platform/upstream/glib.git] / 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 #GAsyncResult
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 }