gio/gproxyresolver.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.1 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 "gproxyresolver.h"
  24
  25 #include <glib.h>
  26 #include "glibintl.h"
  27
  28 #include "gasyncresult.h"
  29 #include "gcancellable.h"
  30 #include "gtask.h"
  31 #include "giomodule.h"
  32 #include "gioerror.h"
  33 #include "giomodule-priv.h"
  34 #include "gnetworkingprivate.h"
  35
  36 /**
  37  * SECTION:gproxyresolver
  38  * @short_description: Asynchronous and cancellable network proxy resolver
  39  * @include: gio/gio.h
  40  *
  41  * #GProxyResolver provides synchronous and asynchronous network proxy
  42  * resolution. #GProxyResolver is used within #GSocketClient through
  43  * the method g_socket_connectable_proxy_enumerate().
  44  *
  45  * Implementations of #GProxyResolver based on libproxy and GNOME settings can
  46  * be found in glib-networking. GIO comes with an implementation for use inside
  47  * Flatpak portals.
  48  */
  49
  50 /**
  51  * GProxyResolverInterface:
  52  * @g_iface: The parent interface.
  53  * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported()
  54  * @lookup: the virtual function pointer for g_proxy_resolver_lookup()
  55  * @lookup_async: the virtual function pointer for
  56  *  g_proxy_resolver_lookup_async()
  57  * @lookup_finish: the virtual function pointer for
  58  *  g_proxy_resolver_lookup_finish()
  59  *
  60  * The virtual function table for #GProxyResolver.
  61  */
  62
  63 G_DEFINE_INTERFACE (GProxyResolver, g_proxy_resolver, G_TYPE_OBJECT)
  64
  65 static void
  66 g_proxy_resolver_default_init (GProxyResolverInterface *iface)
  67 {
  68 }
  69
  70 /**
  71  * g_proxy_resolver_get_default:
  72  *
  73  * Gets the default #GProxyResolver for the system.
  74  *
  75  * Returns: (transfer none): the default #GProxyResolver.
  76  *
  77  * Since: 2.26
  78  */
  79 GProxyResolver *
  80 g_proxy_resolver_get_default (void)
  81 {
  82   return _g_io_module_get_default (G_PROXY_RESOLVER_EXTENSION_POINT_NAME,
  83                                    "GIO_USE_PROXY_RESOLVER",
  84                                    (GIOModuleVerifyFunc)g_proxy_resolver_is_supported);
  85 }
  86
  87 /**
  88  * g_proxy_resolver_is_supported:
  89  * @resolver: a #GProxyResolver
  90  *
  91  * Checks if @resolver can be used on this system. (This is used
  92  * internally; g_proxy_resolver_get_default() will only return a proxy
  93  * resolver that returns %TRUE for this method.)
  94  *
  95  * Returns: %TRUE if @resolver is supported.
  96  *
  97  * Since: 2.26
  98  */
  99 gboolean
 100 g_proxy_resolver_is_supported (GProxyResolver *resolver)
 101 {
 102   GProxyResolverInterface *iface;
 103
 104   g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver), FALSE);
 105
 106   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 107
 108   return (* iface->is_supported) (resolver);
 109 }
 110
 111 /**
 112  * g_proxy_resolver_lookup:
 113  * @resolver: a #GProxyResolver
 114  * @uri: a URI representing the destination to connect to
 115  * @cancellable: (nullable): a #GCancellable, or %NULL
 116  * @error: return location for a #GError, or %NULL
 117  *
 118  * Looks into the system proxy configuration to determine what proxy,
 119  * if any, to use to connect to @uri. The returned proxy URIs are of
 120  * the form `<protocol>://[user[:password]@]host:port` or
 121  * `direct://`, where <protocol> could be http, rtsp, socks
 122  * or other proxying protocol.
 123  *
 124  * If you don't know what network protocol is being used on the
 125  * socket, you should use `none` as the URI protocol.
 126  * In this case, the resolver might still return a generic proxy type
 127  * (such as SOCKS), but would not return protocol-specific proxy types
 128  * (such as http).
 129  *
 130  * `direct://` is used when no proxy is needed.
 131  * Direct connection should not be attempted unless it is part of the
 132  * returned array of proxies.
 133  *
 134  * Returns: (transfer full) (array zero-terminated=1): A
 135  *               NULL-terminated array of proxy URIs. Must be freed
 136  *               with g_strfreev().
 137  *
 138  * Since: 2.26
 139  */
 140 gchar **
 141 g_proxy_resolver_lookup (GProxyResolver  *resolver,
 142                          const gchar     *uri,
 143                          GCancellable    *cancellable,
 144                          GError         **error)
 145 {
 146   GProxyResolverInterface *iface;
 147
 148   g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver), NULL);
 149   g_return_val_if_fail (uri != NULL, NULL);
 150
 151   if (!g_uri_is_valid (uri, G_URI_FLAGS_NONE, NULL))
 152     {
 153       g_set_error (error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
 154                    "Invalid URI ‘%s’", uri);
 155       return NULL;
 156     }
 157
 158   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 159
 160   return (* iface->lookup) (resolver, uri, cancellable, error);
 161 }
 162
 163 /**
 164  * g_proxy_resolver_lookup_async:
 165  * @resolver: a #GProxyResolver
 166  * @uri: a URI representing the destination to connect to
 167  * @cancellable: (nullable): a #GCancellable, or %NULL
 168  * @callback: (scope async): callback to call after resolution completes
 169  * @user_data: (closure): data for @callback
 170  *
 171  * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
 172  * details.
 173  *
 174  * Since: 2.26
 175  */
 176 void
 177 g_proxy_resolver_lookup_async (GProxyResolver      *resolver,
 178                                const gchar         *uri,
 179                                GCancellable        *cancellable,
 180                                GAsyncReadyCallback  callback,
 181                                gpointer             user_data)
 182 {
 183   GProxyResolverInterface *iface;
 184   GError *error = NULL;
 185
 186   g_return_if_fail (G_IS_PROXY_RESOLVER (resolver));
 187   g_return_if_fail (uri != NULL);
 188
 189   if (!g_uri_is_valid (uri, G_URI_FLAGS_NONE, NULL))
 190     {
 191       g_set_error (&error, G_IO_ERROR, G_IO_ERROR_INVALID_ARGUMENT,
 192                    "Invalid URI ‘%s’", uri);
 193       g_task_report_error (resolver, callback, user_data,
 194                            g_proxy_resolver_lookup_async,
 195                            g_steal_pointer (&error));
 196       return;
 197     }
 198
 199   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 200
 201   (* iface->lookup_async) (resolver, uri, cancellable, callback, user_data);
 202 }
 203
 204 /**
 205  * g_proxy_resolver_lookup_finish:
 206  * @resolver: a #GProxyResolver
 207  * @result: the result passed to your #GAsyncReadyCallback
 208  * @error: return location for a #GError, or %NULL
 209  *
 210  * Call this function to obtain the array of proxy URIs when
 211  * g_proxy_resolver_lookup_async() is complete. See
 212  * g_proxy_resolver_lookup() for more details.
 213  *
 214  * Returns: (transfer full) (array zero-terminated=1): A
 215  *               NULL-terminated array of proxy URIs. Must be freed
 216  *               with g_strfreev().
 217  *
 218  * Since: 2.26
 219  */
 220 gchar **
 221 g_proxy_resolver_lookup_finish (GProxyResolver     *resolver,
 222                                 GAsyncResult       *result,
 223                                 GError            **error)
 224 {
 225   GProxyResolverInterface *iface;
 226
 227   g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver), NULL);
 228
 229   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 230
 231   return (* iface->lookup_finish) (resolver, result, error);
 232 }