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