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