Merge branch 'test-ip_mreq_source-android-only' into 'master'
[glib.git] / gio / gproxy.c
blobb7e32210107d40f0dbd4c0ee94a89d31b2c5aee0
1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2010 Collabora Ltd.
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.1 of the License, or (at your option) any later version.
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.
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/>.
18 * Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
21 #include "config.h"
23 #include "gproxy.h"
25 #include "giomodule.h"
26 #include "giomodule-priv.h"
27 #include "glibintl.h"
29 /**
30 * SECTION:gproxy
31 * @short_description: Interface for proxy handling
32 * @include: gio/gio.h
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().
41 * Since: 2.26
42 **/
44 G_DEFINE_INTERFACE (GProxy, g_proxy, G_TYPE_OBJECT)
46 static void
47 g_proxy_default_init (GProxyInterface *iface)
51 /**
52 * g_proxy_get_default_for_protocol:
53 * @protocol: the proxy protocol name (e.g. http, socks, etc)
55 * Lookup "gio-proxy" extension point for a proxy implementation that supports
56 * specified protocol.
58 * Returns: (transfer full): return a #GProxy or NULL if protocol
59 * is not supported.
61 * Since: 2.26
62 **/
63 GProxy *
64 g_proxy_get_default_for_protocol (const gchar *protocol)
66 GIOExtensionPoint *ep;
67 GIOExtension *extension;
69 /* Ensure proxy modules loaded */
70 _g_io_modules_ensure_loaded ();
72 ep = g_io_extension_point_lookup (G_PROXY_EXTENSION_POINT_NAME);
74 extension = g_io_extension_point_get_extension_by_name (ep, protocol);
76 if (extension)
77 return g_object_new (g_io_extension_get_type (extension), NULL);
79 return NULL;
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
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.
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.
99 * Since: 2.26
101 GIOStream *
102 g_proxy_connect (GProxy *proxy,
103 GIOStream *connection,
104 GProxyAddress *proxy_address,
105 GCancellable *cancellable,
106 GError **error)
108 GProxyInterface *iface;
110 g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
112 iface = G_PROXY_GET_IFACE (proxy);
114 return (* iface->connect) (proxy,
115 connection,
116 proxy_address,
117 cancellable,
118 error);
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: (closure): callback data
130 * Asynchronous version of g_proxy_connect().
132 * Since: 2.26
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)
142 GProxyInterface *iface;
144 g_return_if_fail (G_IS_PROXY (proxy));
146 iface = G_PROXY_GET_IFACE (proxy);
148 (* iface->connect_async) (proxy,
149 connection,
150 proxy_address,
151 cancellable,
152 callback,
153 user_data);
157 * g_proxy_connect_finish:
158 * @proxy: a #GProxy
159 * @result: a #GAsyncResult
160 * @error: return #GError
162 * See g_proxy_connect().
164 * Returns: (transfer full): a #GIOStream.
166 * Since: 2.26
168 GIOStream *
169 g_proxy_connect_finish (GProxy *proxy,
170 GAsyncResult *result,
171 GError **error)
173 GProxyInterface *iface;
175 g_return_val_if_fail (G_IS_PROXY (proxy), NULL);
177 iface = G_PROXY_GET_IFACE (proxy);
179 return (* iface->connect_finish) (proxy, result, error);
183 * g_proxy_supports_hostname:
184 * @proxy: a #GProxy
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().
194 * Returns: %TRUE if hostname resolution is supported.
196 * Since: 2.26
198 gboolean
199 g_proxy_supports_hostname (GProxy *proxy)
201 GProxyInterface *iface;
203 g_return_val_if_fail (G_IS_PROXY (proxy), FALSE);
205 iface = G_PROXY_GET_IFACE (proxy);
207 return (* iface->supports_hostname) (proxy);