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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  *
  20  * Author: Nicolas Dufresne <nicolas.dufresne@collabora.co.uk>
  21  */
  22
  23 #include "config.h"
  24
  25 #include "gproxyresolver.h"
  26
  27 #include <glib.h>
  28 #include "glibintl.h"
  29
  30 #include "gasyncresult.h"
  31 #include "gcancellable.h"
  32 #include "giomodule.h"
  33 #include "giomodule-priv.h"
  34 #include "gsimpleasyncresult.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
  46 G_DEFINE_INTERFACE (GProxyResolver, g_proxy_resolver, G_TYPE_OBJECT)
  47
  48 static void
  49 g_proxy_resolver_default_init (GProxyResolverInterface *iface)
  50 {
  51 }
  52
  53 /**
  54  * g_proxy_resolver_get_default:
  55  *
  56  * Gets the default #GProxyResolver for the system.
  57  *
  58  * Return value: (transfer none): the default #GProxyResolver.
  59  *
  60  * Since: 2.26
  61  */
  62 GProxyResolver *
  63 g_proxy_resolver_get_default (void)
  64 {
  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);
  68 }
  69
  70 /**
  71  * g_proxy_resolver_is_supported:
  72  * @resolver: a #GProxyResolver
  73  *
  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.)
  77  *
  78  * Return value: %TRUE if @resolver is supported.
  79  *
  80  * Since: 2.26
  81  */
  82 gboolean
  83 g_proxy_resolver_is_supported (GProxyResolver *resolver)
  84 {
  85   GProxyResolverInterface *iface;
  86
  87   g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver), FALSE);
  88
  89   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
  90
  91   return (* iface->is_supported) (resolver);
  92 }
  93
  94 /**
  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
 100  *
 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>&lt;protocol&gt;://[user[:password]@]host:port</literal>
 104  * or <literal>direct://</literal>, where &lt;protocol&gt; could be
 105  * http, rtsp, socks or other proxying protocol.
 106  *
 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
 111  * (such as http).
 112  *
 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.
 116  *
 117  * Return value: (transfer full) (array zero-terminated=1): A
 118  *               NULL-terminated array of proxy URIs. Must be freed
 119  *               with g_strfreev().
 120  *
 121  * Since: 2.26
 122  */
 123 gchar **
 124 g_proxy_resolver_lookup (GProxyResolver  *resolver,
 125                          const gchar     *uri,
 126                          GCancellable    *cancellable,
 127                          GError         **error)
 128 {
 129   GProxyResolverInterface *iface;
 130
 131   g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver), NULL);
 132   g_return_val_if_fail (uri != NULL, NULL);
 133
 134   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 135
 136   return (* iface->lookup) (resolver, uri, cancellable, error);
 137 }
 138
 139 /**
 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
 146  *
 147  * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more
 148  * details.
 149  *
 150  * Since: 2.26
 151  */
 152 void
 153 g_proxy_resolver_lookup_async (GProxyResolver      *resolver,
 154                                const gchar         *uri,
 155                                GCancellable        *cancellable,
 156                                GAsyncReadyCallback  callback,
 157                                gpointer             user_data)
 158 {
 159   GProxyResolverInterface *iface;
 160
 161   g_return_if_fail (G_IS_PROXY_RESOLVER (resolver));
 162   g_return_if_fail (uri != NULL);
 163
 164   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 165
 166   (* iface->lookup_async) (resolver, uri, cancellable, callback, user_data);
 167 }
 168
 169 /**
 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
 174  *
 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.
 178  *
 179  * Return value: (transfer full) (array zero-terminated=1): A
 180  *               NULL-terminated array of proxy URIs. Must be freed
 181  *               with g_strfreev().
 182  *
 183  * Since: 2.26
 184  */
 185 gchar **
 186 g_proxy_resolver_lookup_finish (GProxyResolver     *resolver,
 187                                 GAsyncResult       *result,
 188                                 GError            **error)
 189 {
 190   GProxyResolverInterface *iface;
 191
 192   g_return_val_if_fail (G_IS_PROXY_RESOLVER (resolver), NULL);
 193
 194   iface = G_PROXY_RESOLVER_GET_IFACE (resolver);
 195
 196   return (* iface->lookup_finish) (resolver, result, error);
 197 }