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 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, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
25 #include "gproxyresolver.h"
30 #include "gasyncresult.h"
31 #include "gcancellable.h"
32 #include "giomodule.h"
33 #include "giomodule-priv.h"
34 #include "gsimpleasyncresult.h"
37 * SECTION:gproxyresolver
38 * @short_description: Asynchronous and cancellable network proxy resolver
41 * #GProxyResolver provides synchronous and asynchronous network proxy
42 * resolution. #GProxyResolver is used within #GSocketClient through
43 * the method g_socket_connectable_proxy_enumerate().
46 G_DEFINE_INTERFACE (GProxyResolver
, g_proxy_resolver
, G_TYPE_OBJECT
)
49 g_proxy_resolver_default_init (GProxyResolverInterface
*iface
)
54 * g_proxy_resolver_get_default:
56 * Gets the default #GProxyResolver for the system.
58 * Return value: (transfer none): the default #GProxyResolver.
63 g_proxy_resolver_get_default (void)
65 return _g_io_module_get_default (G_PROXY_RESOLVER_EXTENSION_POINT_NAME
,
66 "GIO_USE_PROXY_RESOLVER",
67 (GIOModuleVerifyFunc
)g_proxy_resolver_is_supported
);
71 * g_proxy_resolver_is_supported:
72 * @resolver: a #GProxyResolver
74 * Checks if @resolver can be used on this system. (This is used
75 * internally; g_proxy_resolver_get_default() will only return a proxy
76 * resolver that returns %TRUE for this method.)
78 * Return value: %TRUE if @resolver is supported.
83 g_proxy_resolver_is_supported (GProxyResolver
*resolver
)
85 GProxyResolverInterface
*iface
;
87 g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver
), FALSE
);
89 iface
= G_PROXY_RESOLVER_GET_IFACE (resolver
);
91 return (* iface
->is_supported
) (resolver
);
95 * g_proxy_resolver_lookup:
96 * @resolver: a #GProxyResolver
97 * @uri: a URI representing the destination to connect to
98 * @cancellable: (allow-none): a #GCancellable, or %NULL
99 * @error: return location for a #GError, or %NULL
101 * Looks into the system proxy configuration to determine what proxy,
102 * if any, to use to connect to @uri. The returned proxy URIs are of the
103 * form <literal><protocol>://[user[:password]@]host:port</literal>
104 * or <literal>direct://</literal>, where <protocol> could be
105 * http, rtsp, socks or other proxying protocol.
107 * If you don't know what network protocol is being used on the
108 * socket, you should use <literal>none</literal> as the URI protocol.
109 * In this case, the resolver might still return a generic proxy type
110 * (such as SOCKS), but would not return protocol-specific proxy types
113 * <literal>direct://</literal> is used when no proxy is needed.
114 * Direct connection should not be attempted unless it is part of the
115 * returned array of proxies.
117 * Return value: (transfer full) (array zero-terminated=1): A
118 * NULL-terminated array of proxy URIs. Must be freed
124 g_proxy_resolver_lookup (GProxyResolver
*resolver
,
126 GCancellable
*cancellable
,
129 GProxyResolverInterface
*iface
;
131 g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver
), NULL
);
132 g_return_val_if_fail (uri
!= NULL
, NULL
);
134 iface
= G_PROXY_RESOLVER_GET_IFACE (resolver
);
136 return (* iface
->lookup
) (resolver
, uri
, cancellable
, error
);
140 * g_proxy_resolver_lookup_async:
141 * @resolver: a #GProxyResolver
142 * @uri: a URI representing the destination to connect to
143 * @cancellable: (allow-none): a #GCancellable, or %NULL
144 * @callback: (scope async): callback to call after resolution completes
145 * @user_data: (closure): data for @callback
147 * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
153 g_proxy_resolver_lookup_async (GProxyResolver
*resolver
,
155 GCancellable
*cancellable
,
156 GAsyncReadyCallback callback
,
159 GProxyResolverInterface
*iface
;
161 g_return_if_fail (G_IS_PROXY_RESOLVER (resolver
));
162 g_return_if_fail (uri
!= NULL
);
164 iface
= G_PROXY_RESOLVER_GET_IFACE (resolver
);
166 (* iface
->lookup_async
) (resolver
, uri
, cancellable
, callback
, user_data
);
170 * g_proxy_resolver_lookup_finish:
171 * @resolver: a #GProxyResolver
172 * @result: the result passed to your #GAsyncReadyCallback
173 * @error: return location for a #GError, or %NULL
175 * Call this function to obtain the array of proxy URIs when
176 * g_proxy_resolver_lookup_async() is complete. See
177 * g_proxy_resolver_lookup() for more details.
179 * Return value: (transfer full) (array zero-terminated=1): A
180 * NULL-terminated array of proxy URIs. Must be freed
186 g_proxy_resolver_lookup_finish (GProxyResolver
*resolver
,
187 GAsyncResult
*result
,
190 GProxyResolverInterface
*iface
;
192 g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver
), NULL
);
194 iface
= G_PROXY_RESOLVER_GET_IFACE (resolver
);
196 return (* iface
->lookup_finish
) (resolver
, result
, error
);