1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/proxy.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,338 @@
1.4 +/**
1.5 + * @file proxy.h Proxy API
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + */
1.29 +#ifndef _PURPLE_PROXY_H_
1.30 +#define _PURPLE_PROXY_H_
1.31 +
1.32 +#include <glib.h>
1.33 +#include "eventloop.h"
1.34 +
1.35 +/**
1.36 + * A type of proxy connection.
1.37 + */
1.38 +typedef enum
1.39 +{
1.40 + PURPLE_PROXY_USE_GLOBAL = -1, /**< Use the global proxy information. */
1.41 + PURPLE_PROXY_NONE = 0, /**< No proxy. */
1.42 + PURPLE_PROXY_HTTP, /**< HTTP proxy. */
1.43 + PURPLE_PROXY_SOCKS4, /**< SOCKS 4 proxy. */
1.44 + PURPLE_PROXY_SOCKS5, /**< SOCKS 5 proxy. */
1.45 + PURPLE_PROXY_USE_ENVVAR /**< Use environmental settings. */
1.46 +
1.47 +} PurpleProxyType;
1.48 +
1.49 +/**
1.50 + * Information on proxy settings.
1.51 + */
1.52 +typedef struct
1.53 +{
1.54 + PurpleProxyType type; /**< The proxy type. */
1.55 +
1.56 + char *host; /**< The host. */
1.57 + int port; /**< The port number. */
1.58 + char *username; /**< The username. */
1.59 + char *password; /**< The password. */
1.60 +
1.61 +} PurpleProxyInfo;
1.62 +
1.63 +typedef struct _PurpleProxyConnectData PurpleProxyConnectData;
1.64 +
1.65 +typedef void (*PurpleProxyConnectFunction)(gpointer data, gint source, const gchar *error_message);
1.66 +
1.67 +
1.68 +#include "account.h"
1.69 +
1.70 +#ifdef __cplusplus
1.71 +extern "C" {
1.72 +#endif
1.73 +
1.74 +/**************************************************************************/
1.75 +/** @name Proxy structure API */
1.76 +/**************************************************************************/
1.77 +/*@{*/
1.78 +
1.79 +/**
1.80 + * Creates a proxy information structure.
1.81 + *
1.82 + * @return The proxy information structure.
1.83 + */
1.84 +PurpleProxyInfo *purple_proxy_info_new(void);
1.85 +
1.86 +/**
1.87 + * Destroys a proxy information structure.
1.88 + *
1.89 + * @param info The proxy information structure to destroy.
1.90 + */
1.91 +void purple_proxy_info_destroy(PurpleProxyInfo *info);
1.92 +
1.93 +/**
1.94 + * Sets the type of proxy.
1.95 + *
1.96 + * @param info The proxy information.
1.97 + * @param type The proxy type.
1.98 + */
1.99 +void purple_proxy_info_set_type(PurpleProxyInfo *info, PurpleProxyType type);
1.100 +
1.101 +/**
1.102 + * Sets the proxy host.
1.103 + *
1.104 + * @param info The proxy information.
1.105 + * @param host The host.
1.106 + */
1.107 +void purple_proxy_info_set_host(PurpleProxyInfo *info, const char *host);
1.108 +
1.109 +/**
1.110 + * Sets the proxy port.
1.111 + *
1.112 + * @param info The proxy information.
1.113 + * @param port The port.
1.114 + */
1.115 +void purple_proxy_info_set_port(PurpleProxyInfo *info, int port);
1.116 +
1.117 +/**
1.118 + * Sets the proxy username.
1.119 + *
1.120 + * @param info The proxy information.
1.121 + * @param username The username.
1.122 + */
1.123 +void purple_proxy_info_set_username(PurpleProxyInfo *info, const char *username);
1.124 +
1.125 +/**
1.126 + * Sets the proxy password.
1.127 + *
1.128 + * @param info The proxy information.
1.129 + * @param password The password.
1.130 + */
1.131 +void purple_proxy_info_set_password(PurpleProxyInfo *info, const char *password);
1.132 +
1.133 +/**
1.134 + * Returns the proxy's type.
1.135 + *
1.136 + * @param info The proxy information.
1.137 + *
1.138 + * @return The type.
1.139 + */
1.140 +PurpleProxyType purple_proxy_info_get_type(const PurpleProxyInfo *info);
1.141 +
1.142 +/**
1.143 + * Returns the proxy's host.
1.144 + *
1.145 + * @param info The proxy information.
1.146 + *
1.147 + * @return The host.
1.148 + */
1.149 +const char *purple_proxy_info_get_host(const PurpleProxyInfo *info);
1.150 +
1.151 +/**
1.152 + * Returns the proxy's port.
1.153 + *
1.154 + * @param info The proxy information.
1.155 + *
1.156 + * @return The port.
1.157 + */
1.158 +int purple_proxy_info_get_port(const PurpleProxyInfo *info);
1.159 +
1.160 +/**
1.161 + * Returns the proxy's username.
1.162 + *
1.163 + * @param info The proxy information.
1.164 + *
1.165 + * @return The username.
1.166 + */
1.167 +const char *purple_proxy_info_get_username(const PurpleProxyInfo *info);
1.168 +
1.169 +/**
1.170 + * Returns the proxy's password.
1.171 + *
1.172 + * @param info The proxy information.
1.173 + *
1.174 + * @return The password.
1.175 + */
1.176 +const char *purple_proxy_info_get_password(const PurpleProxyInfo *info);
1.177 +
1.178 +/*@}*/
1.179 +
1.180 +/**************************************************************************/
1.181 +/** @name Global Proxy API */
1.182 +/**************************************************************************/
1.183 +/*@{*/
1.184 +
1.185 +/**
1.186 + * Returns purple's global proxy information.
1.187 + *
1.188 + * @return The global proxy information.
1.189 + */
1.190 +PurpleProxyInfo *purple_global_proxy_get_info(void);
1.191 +
1.192 +/**
1.193 + * Set purple's global proxy information.
1.194 + *
1.195 + * @param info The proxy information.
1.196 + * @since 2.6.0
1.197 + */
1.198 +void purple_global_proxy_set_info(PurpleProxyInfo *info);
1.199 +
1.200 +/*@}*/
1.201 +
1.202 +/**************************************************************************/
1.203 +/** @name Proxy API */
1.204 +/**************************************************************************/
1.205 +/*@{*/
1.206 +
1.207 +/**
1.208 + * Returns the proxy subsystem handle.
1.209 + *
1.210 + * @return The proxy subsystem handle.
1.211 + */
1.212 +void *purple_proxy_get_handle(void);
1.213 +
1.214 +/**
1.215 + * Initializes the proxy subsystem.
1.216 + */
1.217 +void purple_proxy_init(void);
1.218 +
1.219 +/**
1.220 + * Uninitializes the proxy subsystem.
1.221 + */
1.222 +void purple_proxy_uninit(void);
1.223 +
1.224 +/**
1.225 + * Returns configuration of a proxy.
1.226 + *
1.227 + * @param account The account for which the configuration is needed.
1.228 + *
1.229 + * @return The configuration of a proxy.
1.230 + */
1.231 +PurpleProxyInfo *purple_proxy_get_setup(PurpleAccount *account);
1.232 +
1.233 +/**
1.234 + * Makes a connection to the specified host and port. Note that this
1.235 + * function name can be misleading--although it is called "proxy
1.236 + * connect," it is used for establishing any outgoing TCP connection,
1.237 + * whether through a proxy or not.
1.238 + *
1.239 + * @param handle A handle that should be associated with this
1.240 + * connection attempt. The handle can be used
1.241 + * to cancel the connection attempt using the
1.242 + * purple_proxy_connect_cancel_with_handle()
1.243 + * function.
1.244 + * @param account The account making the connection.
1.245 + * @param host The destination host.
1.246 + * @param port The destination port.
1.247 + * @param connect_cb The function to call when the connection is
1.248 + * established. If the connection failed then
1.249 + * fd will be -1 and error message will be set
1.250 + * to something descriptive (hopefully).
1.251 + * @param data User-defined data.
1.252 + *
1.253 + * @return NULL if there was an error, or a reference to an
1.254 + * opaque data structure that can be used to cancel
1.255 + * the pending connection, if needed.
1.256 + */
1.257 +PurpleProxyConnectData *purple_proxy_connect(void *handle,
1.258 + PurpleAccount *account,
1.259 + const char *host, int port,
1.260 + PurpleProxyConnectFunction connect_cb, gpointer data);
1.261 +
1.262 +/**
1.263 + * Makes a connection to the specified host and port. Note that this
1.264 + * function name can be misleading--although it is called "proxy
1.265 + * connect," it is used for establishing any outgoing UDP connection,
1.266 + * whether through a proxy or not.
1.267 + *
1.268 + * @param handle A handle that should be associated with this
1.269 + * connection attempt. The handle can be used
1.270 + * to cancel the connection attempt using the
1.271 + * purple_proxy_connect_cancel_with_handle()
1.272 + * function.
1.273 + * @param account The account making the connection.
1.274 + * @param host The destination host.
1.275 + * @param port The destination port.
1.276 + * @param connect_cb The function to call when the connection is
1.277 + * established. If the connection failed then
1.278 + * fd will be -1 and error message will be set
1.279 + * to something descriptive (hopefully).
1.280 + * @param data User-defined data.
1.281 + *
1.282 + * @return NULL if there was an error, or a reference to an
1.283 + * opaque data structure that can be used to cancel
1.284 + * the pending connection, if needed.
1.285 + */
1.286 +PurpleProxyConnectData *purple_proxy_connect_udp(void *handle,
1.287 + PurpleAccount *account,
1.288 + const char *host, int port,
1.289 + PurpleProxyConnectFunction connect_cb, gpointer data);
1.290 +
1.291 +/**
1.292 + * Makes a connection through a SOCKS5 proxy.
1.293 + *
1.294 + * @param handle A handle that should be associated with this
1.295 + * connection attempt. The handle can be used
1.296 + * to cancel the connection attempt using the
1.297 + * purple_proxy_connect_cancel_with_handle()
1.298 + * function.
1.299 + * @param gpi The PurpleProxyInfo specifying the proxy settings
1.300 + * @param host The destination host.
1.301 + * @param port The destination port.
1.302 + * @param connect_cb The function to call when the connection is
1.303 + * established. If the connection failed then
1.304 + * fd will be -1 and error message will be set
1.305 + * to something descriptive (hopefully).
1.306 + * @param data User-defined data.
1.307 + *
1.308 + * @return NULL if there was an error, or a reference to an
1.309 + * opaque data structure that can be used to cancel
1.310 + * the pending connection, if needed.
1.311 + */
1.312 +PurpleProxyConnectData *purple_proxy_connect_socks5(void *handle,
1.313 + PurpleProxyInfo *gpi,
1.314 + const char *host, int port,
1.315 + PurpleProxyConnectFunction connect_cb, gpointer data);
1.316 +
1.317 +/**
1.318 + * Cancel an in-progress connection attempt. This should be called
1.319 + * by the PRPL if the user disables an account while it is still
1.320 + * performing the initial sign on. Or when establishing a file
1.321 + * transfer, if we attempt to connect to a remote user but they
1.322 + * are behind a firewall then the PRPL can cancel the connection
1.323 + * attempt early rather than just letting the OS's TCP/IP stack
1.324 + * time-out the connection.
1.325 + */
1.326 +void purple_proxy_connect_cancel(PurpleProxyConnectData *connect_data);
1.327 +
1.328 +/*
1.329 + * Closes all proxy connections registered with the specified handle.
1.330 + *
1.331 + * @param handle The handle.
1.332 + */
1.333 +void purple_proxy_connect_cancel_with_handle(void *handle);
1.334 +
1.335 +/*@}*/
1.336 +
1.337 +#ifdef __cplusplus
1.338 +}
1.339 +#endif
1.340 +
1.341 +#endif /* _PURPLE_PROXY_H_ */