2 * @file proxy.h Proxy API
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_
30 #include "eventloop.h"
33 * A type of proxy connection.
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) */
48 * Information on proxy settings.
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. */
61 typedef struct _PurpleProxyConnectData PurpleProxyConnectData
;
63 typedef void (*PurpleProxyConnectFunction
)(gpointer data
, gint source
, const gchar
*error_message
);
72 /**************************************************************************/
73 /** @name Proxy structure API */
74 /**************************************************************************/
78 * Creates a proxy information structure.
80 * @return The proxy information structure.
82 PurpleProxyInfo
*purple_proxy_info_new(void);
85 * Destroys a proxy information structure.
87 * @param info The proxy information structure to destroy.
89 void purple_proxy_info_destroy(PurpleProxyInfo
*info
);
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
);
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.
138 PurpleProxyType
purple_proxy_info_get_type(const PurpleProxyInfo
*info
);
141 * Returns the proxy's host.
143 * @param info The proxy information.
147 const char *purple_proxy_info_get_host(const PurpleProxyInfo
*info
);
150 * Returns the proxy's port.
152 * @param info The proxy information.
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
);
178 /**************************************************************************/
179 /** @name Global Proxy API */
180 /**************************************************************************/
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.
196 void purple_global_proxy_set_info(PurpleProxyInfo
*info
);
200 /**************************************************************************/
201 /** @name Proxy API */
202 /**************************************************************************/
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()
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()
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()
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()
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
);
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
);
372 #endif /* _PURPLE_PROXY_H_ */