1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright (C) 2010 Collabora Ltd.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
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 * GProxy:
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 * [method@Gio.IOExtensionPoint.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 * Find the `gio-proxy` extension point for a proxy implementation that supports
56 * the specified protocol.
57 *
58 * Returns: (nullable) (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: (nullable): 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: (nullable): a #GCancellable
127 * @callback: (scope async): a #GAsyncReadyCallback
128 * @user_data: 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 }