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