Remove useless comparison
[pidgin-git.git] / libpurple / proxy.h
blobcf91ee8c713c34aed3e0123131b120cf06353953
1 /**
2 * @file proxy.h Proxy API
3 * @ingroup core
4 */
6 /* purple
8 * Purple is the legal property of its developers, whose names are too numerous
9 * to list here. Please refer to the COPYRIGHT file distributed with this
10 * source distribution.
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU General Public License as published by
14 * the Free Software Foundation; either version 2 of the License, or
15 * (at your option) any later version.
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU General Public License for more details.
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, write to the Free Software
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
26 #ifndef _PURPLE_PROXY_H_
27 #define _PURPLE_PROXY_H_
29 #include <glib.h>
30 #include "eventloop.h"
32 /**
33 * A type of proxy connection.
35 typedef enum
37 PURPLE_PROXY_USE_GLOBAL = -1, /**< Use the global proxy information. */
38 PURPLE_PROXY_NONE = 0, /**< 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) */
45 } PurpleProxyType;
47 /**
48 * Information on proxy settings.
50 typedef struct
52 PurpleProxyType type; /**< The proxy type. */
54 char *host; /**< The host. */
55 int port; /**< The port number. */
56 char *username; /**< The username. */
57 char *password; /**< The password. */
59 } PurpleProxyInfo;
61 typedef struct _PurpleProxyConnectData PurpleProxyConnectData;
63 typedef void (*PurpleProxyConnectFunction)(gpointer data, gint source, const gchar *error_message);
66 #include "account.h"
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
72 /**************************************************************************/
73 /** @name Proxy structure API */
74 /**************************************************************************/
75 /*@{*/
77 /**
78 * Creates a proxy information structure.
80 * @return The proxy information structure.
82 PurpleProxyInfo *purple_proxy_info_new(void);
84 /**
85 * Destroys a proxy information structure.
87 * @param info The proxy information structure to destroy.
89 void purple_proxy_info_destroy(PurpleProxyInfo *info);
91 /**
92 * Sets the type of proxy.
94 * @param info The proxy information.
95 * @param type The proxy type.
97 void purple_proxy_info_set_type(PurpleProxyInfo *info, PurpleProxyType type);
99 /**
100 * Sets the proxy host.
102 * @param info The proxy information.
103 * @param host The host.
105 void purple_proxy_info_set_host(PurpleProxyInfo *info, const char *host);
108 * Sets the proxy port.
110 * @param info The proxy information.
111 * @param port The port.
113 void purple_proxy_info_set_port(PurpleProxyInfo *info, int port);
116 * Sets the proxy username.
118 * @param info The proxy information.
119 * @param username The username.
121 void purple_proxy_info_set_username(PurpleProxyInfo *info, const char *username);
124 * Sets the proxy password.
126 * @param info The proxy information.
127 * @param password The password.
129 void purple_proxy_info_set_password(PurpleProxyInfo *info, const char *password);
132 * Returns the proxy's type.
134 * @param info The proxy information.
136 * @return The type.
138 PurpleProxyType purple_proxy_info_get_type(const PurpleProxyInfo *info);
141 * Returns the proxy's host.
143 * @param info The proxy information.
145 * @return The host.
147 const char *purple_proxy_info_get_host(const PurpleProxyInfo *info);
150 * Returns the proxy's port.
152 * @param info The proxy information.
154 * @return The port.
156 int purple_proxy_info_get_port(const PurpleProxyInfo *info);
159 * Returns the proxy's username.
161 * @param info The proxy information.
163 * @return The username.
165 const char *purple_proxy_info_get_username(const PurpleProxyInfo *info);
168 * Returns the proxy's password.
170 * @param info The proxy information.
172 * @return The password.
174 const char *purple_proxy_info_get_password(const PurpleProxyInfo *info);
176 /*@}*/
178 /**************************************************************************/
179 /** @name Global Proxy API */
180 /**************************************************************************/
181 /*@{*/
184 * Returns purple's global proxy information.
186 * @return The global proxy information.
188 PurpleProxyInfo *purple_global_proxy_get_info(void);
191 * Set purple's global proxy information.
193 * @param info The proxy information.
194 * @since 2.6.0
196 void purple_global_proxy_set_info(PurpleProxyInfo *info);
198 /*@}*/
200 /**************************************************************************/
201 /** @name Proxy API */
202 /**************************************************************************/
203 /*@{*/
206 * Returns the proxy subsystem handle.
208 * @return The proxy subsystem handle.
210 void *purple_proxy_get_handle(void);
213 * Initializes the proxy subsystem.
215 void purple_proxy_init(void);
218 * Uninitializes the proxy subsystem.
220 void purple_proxy_uninit(void);
223 * Returns configuration of a proxy.
225 * @param account The account for which the configuration is needed.
227 * @return The configuration of a proxy.
229 PurpleProxyInfo *purple_proxy_get_setup(PurpleAccount *account);
232 * Makes a connection to the specified host and port. Note that this
233 * function name can be misleading--although it is called "proxy
234 * connect," it is used for establishing any outgoing TCP connection,
235 * whether through a proxy or not.
237 * @param handle A handle that should be associated with this
238 * connection attempt. The handle can be used
239 * to cancel the connection attempt using the
240 * purple_proxy_connect_cancel_with_handle()
241 * function.
242 * @param account The account making the connection.
243 * @param host The destination host.
244 * @param port The destination port.
245 * @param connect_cb The function to call when the connection is
246 * established. If the connection failed then
247 * fd will be -1 and error message will be set
248 * to something descriptive (hopefully).
249 * @param data User-defined data.
251 * @return NULL if there was an error, or a reference to an
252 * opaque data structure that can be used to cancel
253 * the pending connection, if needed.
255 PurpleProxyConnectData *purple_proxy_connect(void *handle,
256 PurpleAccount *account,
257 const char *host, int port,
258 PurpleProxyConnectFunction connect_cb, gpointer data);
261 * Makes a connection to the specified host and port. Note that this
262 * function name can be misleading--although it is called "proxy
263 * connect," it is used for establishing any outgoing UDP connection,
264 * whether through a proxy or not.
266 * @param handle A handle that should be associated with this
267 * connection attempt. The handle can be used
268 * to cancel the connection attempt using the
269 * purple_proxy_connect_cancel_with_handle()
270 * function.
271 * @param account The account making the connection.
272 * @param host The destination host.
273 * @param port The destination port.
274 * @param connect_cb The function to call when the connection is
275 * established. If the connection failed then
276 * fd will be -1 and error message will be set
277 * to something descriptive (hopefully).
278 * @param data User-defined data.
280 * @return NULL if there was an error, or a reference to an
281 * opaque data structure that can be used to cancel
282 * the pending connection, if needed.
284 PurpleProxyConnectData *purple_proxy_connect_udp(void *handle,
285 PurpleAccount *account,
286 const char *host, int port,
287 PurpleProxyConnectFunction connect_cb, gpointer data);
290 * Makes a connection through a SOCKS5 proxy.
292 * Note that if the account that is making the connection uses a proxy, this
293 * connection to a SOCKS5 proxy will be made through the account proxy.
295 * @param handle A handle that should be associated with this
296 * connection attempt. The handle can be used
297 * to cancel the connection attempt using the
298 * purple_proxy_connect_cancel_with_handle()
299 * function.
300 * @param account The account making the connection.
301 * @param gpi The PurpleProxyInfo specifying the proxy settings
302 * @param host The destination host.
303 * @param port The destination port.
304 * @param connect_cb The function to call when the connection is
305 * established. If the connection failed then
306 * fd will be -1 and error message will be set
307 * to something descriptive (hopefully).
308 * @param data User-defined data.
310 * @return NULL if there was an error, or a reference to an
311 * opaque data structure that can be used to cancel
312 * the pending connection, if needed.
314 PurpleProxyConnectData *purple_proxy_connect_socks5_account(void *handle,
315 PurpleAccount *account, PurpleProxyInfo *gpi,
316 const char *host, int port,
317 PurpleProxyConnectFunction connect_cb, gpointer data);
319 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PROXY_C_)
321 * Makes a connection through a SOCKS5 proxy.
323 * @param handle A handle that should be associated with this
324 * connection attempt. The handle can be used
325 * to cancel the connection attempt using the
326 * purple_proxy_connect_cancel_with_handle()
327 * function.
328 * @param gpi The PurpleProxyInfo specifying the proxy settings
329 * @param host The destination host.
330 * @param port The destination port.
331 * @param connect_cb The function to call when the connection is
332 * established. If the connection failed then
333 * fd will be -1 and error message will be set
334 * to something descriptive (hopefully).
335 * @param data User-defined data.
337 * @return NULL if there was an error, or a reference to an
338 * opaque data structure that can be used to cancel
339 * the pending connection, if needed.
340 * @deprecated Use purple_proxy_connect_socks5_account instead
342 PurpleProxyConnectData *purple_proxy_connect_socks5(void *handle,
343 PurpleProxyInfo *gpi,
344 const char *host, int port,
345 PurpleProxyConnectFunction connect_cb, gpointer data);
346 #endif
349 * Cancel an in-progress connection attempt. This should be called
350 * by the PRPL if the user disables an account while it is still
351 * performing the initial sign on. Or when establishing a file
352 * transfer, if we attempt to connect to a remote user but they
353 * are behind a firewall then the PRPL can cancel the connection
354 * attempt early rather than just letting the OS's TCP/IP stack
355 * time-out the connection.
357 void purple_proxy_connect_cancel(PurpleProxyConnectData *connect_data);
360 * Closes all proxy connections registered with the specified handle.
362 * @param handle The handle.
364 void purple_proxy_connect_cancel_with_handle(void *handle);
366 /*@}*/
368 #ifdef __cplusplus
370 #endif
372 #endif /* _PURPLE_PROXY_H_ */