libpurple/proxy.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef _PURPLE_PROXY_H_
  23 #define _PURPLE_PROXY_H_
  24 /**
  25  * SECTION:proxy
  26  * @section_id: libpurple-proxy
  27  * @short_description: <filename>proxy.h</filename>
  28  * @title: Proxy API
  29  */
  30
  31 #include <glib.h>
  32 #include <gio/gio.h>
  33 #include "eventloop.h"
  34
  35 /**
  36  * PurpleProxyType:
  37  * @PURPLE_PROXY_USE_GLOBAL: Use the global proxy information.
  38  * @PURPLE_PROXY_NONE:       No proxy.
  39  * @PURPLE_PROXY_HTTP:       HTTP proxy.
  40  * @PURPLE_PROXY_SOCKS4:     SOCKS 4 proxy.
  41  * @PURPLE_PROXY_SOCKS5:     SOCKS 5 proxy.
  42  * @PURPLE_PROXY_USE_ENVVAR: Use environmental settings.
  43  * @PURPLE_PROXY_TOR:        Use a Tor proxy (SOCKS 5 really).
  44  *
  45  * A type of proxy connection.
  46  */
  47 typedef enum
  48 {
  49         PURPLE_PROXY_USE_GLOBAL = -1,
  50         PURPLE_PROXY_NONE = 0,
  51         PURPLE_PROXY_HTTP,
  52         PURPLE_PROXY_SOCKS4,
  53         PURPLE_PROXY_SOCKS5,
  54         PURPLE_PROXY_USE_ENVVAR,
  55         PURPLE_PROXY_TOR
  56
  57 } PurpleProxyType;
  58
  59 /**
  60  * PurpleProxyInfo:
  61  *
  62  * Information on proxy settings.
  63  */
  64 typedef struct _PurpleProxyInfo PurpleProxyInfo;
  65
  66 typedef struct _PurpleProxyConnectData PurpleProxyConnectData;
  67
  68 typedef void (*PurpleProxyConnectFunction)(gpointer data, gint source, const gchar *error_message);
  69
  70
  71 #include "account.h"
  72
  73 G_BEGIN_DECLS
  74
  75 /**************************************************************************/
  76 /* Proxy structure API                                                    */
  77 /**************************************************************************/
  78
  79 /**
  80  * purple_proxy_info_new:
  81  *
  82  * Creates a proxy information structure.
  83  *
  84  * Returns: The proxy information structure.
  85  */
  86 PurpleProxyInfo *purple_proxy_info_new(void);
  87
  88 /**
  89  * purple_proxy_info_destroy:
  90  * @info: The proxy information structure to destroy.
  91  *
  92  * Destroys a proxy information structure.
  93  */
  94 void purple_proxy_info_destroy(PurpleProxyInfo *info);
  95
  96 /**
  97  * purple_proxy_info_set_proxy_type:
  98  * @info: The proxy information.
  99  * @type: The proxy type.
 100  *
 101  * Sets the type of proxy.
 102  */
 103 void purple_proxy_info_set_proxy_type(PurpleProxyInfo *info, PurpleProxyType type);
 104
 105 /**
 106  * purple_proxy_info_set_host:
 107  * @info: The proxy information.
 108  * @host: The host.
 109  *
 110  * Sets the proxy host.
 111  */
 112 void purple_proxy_info_set_host(PurpleProxyInfo *info, const char *host);
 113
 114 /**
 115  * purple_proxy_info_set_port:
 116  * @info: The proxy information.
 117  * @port: The port.
 118  *
 119  * Sets the proxy port.
 120  */
 121 void purple_proxy_info_set_port(PurpleProxyInfo *info, int port);
 122
 123 /**
 124  * purple_proxy_info_set_username:
 125  * @info:     The proxy information.
 126  * @username: The username.
 127  *
 128  * Sets the proxy username.
 129  */
 130 void purple_proxy_info_set_username(PurpleProxyInfo *info, const char *username);
 131
 132 /**
 133  * purple_proxy_info_set_password:
 134  * @info:     The proxy information.
 135  * @password: The password.
 136  *
 137  * Sets the proxy password.
 138  */
 139 void purple_proxy_info_set_password(PurpleProxyInfo *info, const char *password);
 140
 141 /**
 142  * purple_proxy_info_get_proxy_type:
 143  * @info: The proxy information.
 144  *
 145  * Returns the proxy's type.
 146  *
 147  * Returns: The type.
 148  */
 149 PurpleProxyType purple_proxy_info_get_proxy_type(const PurpleProxyInfo *info);
 150
 151 /**
 152  * purple_proxy_info_get_host:
 153  * @info: The proxy information.
 154  *
 155  * Returns the proxy's host.
 156  *
 157  * Returns: The host.
 158  */
 159 const char *purple_proxy_info_get_host(const PurpleProxyInfo *info);
 160
 161 /**
 162  * purple_proxy_info_get_port:
 163  * @info: The proxy information.
 164  *
 165  * Returns the proxy's port.
 166  *
 167  * Returns: The port.
 168  */
 169 int purple_proxy_info_get_port(const PurpleProxyInfo *info);
 170
 171 /**
 172  * purple_proxy_info_get_username:
 173  * @info: The proxy information.
 174  *
 175  * Returns the proxy's username.
 176  *
 177  * Returns: The username.
 178  */
 179 const char *purple_proxy_info_get_username(const PurpleProxyInfo *info);
 180
 181 /**
 182  * purple_proxy_info_get_password:
 183  * @info: The proxy information.
 184  *
 185  * Returns the proxy's password.
 186  *
 187  * Returns: The password.
 188  */
 189 const char *purple_proxy_info_get_password(const PurpleProxyInfo *info);
 190
 191 /**************************************************************************/
 192 /* Global Proxy API                                                       */
 193 /**************************************************************************/
 194
 195 /**
 196  * purple_global_proxy_get_info:
 197  *
 198  * Returns purple's global proxy information.
 199  *
 200  * Returns: The global proxy information.
 201  */
 202 PurpleProxyInfo *purple_global_proxy_get_info(void);
 203
 204 /**
 205  * purple_global_proxy_set_info:
 206  * @info:     The proxy information.
 207  *
 208  * Set purple's global proxy information.
 209  */
 210 void purple_global_proxy_set_info(PurpleProxyInfo *info);
 211
 212 /**************************************************************************/
 213 /* Proxy API                                                              */
 214 /**************************************************************************/
 215
 216 /**
 217  * purple_proxy_get_handle:
 218  *
 219  * Returns the proxy subsystem handle.
 220  *
 221  * Returns: The proxy subsystem handle.
 222  */
 223 void *purple_proxy_get_handle(void);
 224
 225 /**
 226  * purple_proxy_init:
 227  *
 228  * Initializes the proxy subsystem.
 229  */
 230 void purple_proxy_init(void);
 231
 232 /**
 233  * purple_proxy_uninit:
 234  *
 235  * Uninitializes the proxy subsystem.
 236  */
 237 void purple_proxy_uninit(void);
 238
 239 /**
 240  * purple_proxy_get_setup:
 241  * @account: The account for which the configuration is needed.
 242  *
 243  * Returns configuration of a proxy.
 244  *
 245  * Returns: The configuration of a proxy.
 246  */
 247 PurpleProxyInfo *purple_proxy_get_setup(PurpleAccount *account);
 248
 249 /**
 250  * purple_proxy_connect:
 251  * @handle:     A handle that should be associated with this
 252  *              connection attempt.  The handle can be used
 253  *              to cancel the connection attempt using the
 254  *              purple_proxy_connect_cancel_with_handle()
 255  *              function.
 256  * @account:    The account making the connection.
 257  * @host:       The destination host.
 258  * @port:       The destination port.
 259  * @connect_cb: (scope call): The function to call when the connection is
 260  *              established.  If the connection failed then
 261  *              fd will be -1 and error message will be set
 262  *              to something descriptive (hopefully).
 263  * @data:       User-defined data.
 264  *
 265  * Makes a connection to the specified host and port.  Note that this
 266  * function name can be misleading--although it is called "proxy
 267  * connect," it is used for establishing any outgoing TCP connection,
 268  * whether through a proxy or not.
 269  *
 270  * Returns: NULL if there was an error, or a reference to an
 271  *         opaque data structure that can be used to cancel
 272  *         the pending connection, if needed.
 273  */
 274 PurpleProxyConnectData *purple_proxy_connect(void *handle,
 275                         PurpleAccount *account,
 276                         const char *host, int port,
 277                         PurpleProxyConnectFunction connect_cb, gpointer data);
 278
 279 /**
 280  * purple_proxy_connect_socks5_account:
 281  * @handle:     A handle that should be associated with this
 282  *              connection attempt.  The handle can be used
 283  *              to cancel the connection attempt using the
 284  *              purple_proxy_connect_cancel_with_handle()
 285  *              function.
 286  * @account:    The account making the connection.
 287  * @gpi:        The PurpleProxyInfo specifying the proxy settings
 288  * @host:       The destination host.
 289  * @port:       The destination port.
 290  * @connect_cb: (scope call): The function to call when the connection is
 291  *              established.  If the connection failed then
 292  *              fd will be -1 and error message will be set
 293  *              to something descriptive (hopefully).
 294  * @data:       User-defined data.
 295  *
 296  * Makes a connection through a SOCKS5 proxy.
 297  *
 298  * Note that if the account that is making the connection uses a proxy, this
 299  * connection to a SOCKS5 proxy will be made through the account proxy.
 300  *
 301  * Returns: NULL if there was an error, or a reference to an
 302  *         opaque data structure that can be used to cancel
 303  *         the pending connection, if needed.
 304  */
 305 PurpleProxyConnectData *purple_proxy_connect_socks5_account(void *handle,
 306                         PurpleAccount *account, PurpleProxyInfo *gpi,
 307                         const char *host, int port,
 308                         PurpleProxyConnectFunction connect_cb, gpointer data);
 309
 310 /**
 311  * purple_proxy_connect_cancel:
 312  * @connect_data: The #PurpleProxyConnectData to cancel.
 313  *
 314  * Cancel an in-progress connection attempt.  This should be called
 315  * by the protocol if the user disables an account while it is still
 316  * performing the initial sign on.  Or when establishing a file
 317  * transfer, if we attempt to connect to a remote user but they
 318  * are behind a firewall then the protocol can cancel the connection
 319  * attempt early rather than just letting the OS's TCP/IP stack
 320  * time-out the connection.
 321  */
 322 void purple_proxy_connect_cancel(PurpleProxyConnectData *connect_data);
 323
 324 /**
 325  * purple_proxy_connect_cancel_with_handle:
 326  * @handle: The handle.
 327  *
 328  * Closes all proxy connections registered with the specified handle.
 329  */
 330 void purple_proxy_connect_cancel_with_handle(void *handle);
 331
 332 /**
 333  * purple_proxy_get_proxy_resolver:
 334  * @account: The account for which to get the proxy resolver.
 335  * @error: Return location for a GError, or NULL.
 336  *
 337  * Returns a #GProxyResolver capable of resolving which proxy
 338  * to use for this account, if any. This object can be given to a
 339  * #GSocketClient for automatic proxy handling or can be used
 340  * directly if desired.
 341  *
 342  * Returns: (transfer full): NULL if there was an error with the
 343  *         account's (or system) proxy settings, or a reference to
 344  *         a #GProxyResolver on success.
 345  */
 346 GProxyResolver *purple_proxy_get_proxy_resolver(PurpleAccount *account,
 347                 GError **error);
 348
 349 G_END_DECLS
 350
 351 #endif /* _PURPLE_PROXY_H_ */