diff src/proxy.h @ 14089:10e8eb6a4910

[gaim-migrate @ 16712] Pretty large commit here. Basically I got sick of having to verify that gc is still valid on all the callback functions for gaim_proxy_connect(). The fix for this for gaim_proxy_connect() to return something that allows the connection attempt to be canceled. It's not quite there yet, but this is a good first step. I changed gaim_proxy_connect() to return a reference to a new GaimProxyConnectInfo (this used to be called PHB). Eventually this can be passed to a function that'll cancel the connection attempt. I also decided to add an error_cb instead of using connect_cb and passing a file descriptor of -1. And proxy.c will also pass an error message to callers which should explain the reason that the connection attempt failed. Oh, and proxy.c now never calls gaim_connection_error() committer: Tailor Script <[e-mail]>

--- a/src/proxy.h	Sat Aug 12 10:06:15 2006 +0000
+++ b/src/proxy.h	Sat Aug 12 10:12:43 2006 +0000
@@ -56,6 +56,17 @@
 
 } GaimProxyInfo;
 
+typedef struct PBH GaimProxyConnectInfo;
+
+typedef void (*GaimProxyConnectFunction)(gpointer data, gint source);
+typedef void (*GaimProxyErrorFunction)(gpointer dat, const gchar *error_message);
+
+/**
+ * The "hosts" parameter is a linked list containing pairs of
+ * one size_t addrlen and one struct sockaddr *addr.
+ */
+typedef void (*GaimProxyDnsConnectFunction)(GSList *hosts, gpointer data, const char *error_message);
+
 
 #include "account.h"
 
@@ -69,13 +80,6 @@
 /*@{*/
 
 /**
- * Get the handle for the proxy system.
- *
- * @return the handle to the proxy system
- */
-void *gaim_proxy_get_handle(void);
-
-/**
  * Creates a proxy information structure.
  *
  * @return The proxy information structure.
@@ -196,11 +200,23 @@
 /*@{*/
 
 /**
+ * Returns the proxy subsystem handle.
+ *
+ * @return The proxy subsystem handle.
+ */
+void *gaim_proxy_get_handle(void);
+
+/**
  * Initializes the proxy subsystem.
  */
 void gaim_proxy_init(void);
 
 /**
+ * Uninitializes the proxy subsystem.
+ */
+void gaim_proxy_uninit(void);
+
+/**
  * Returns configuration of a proxy.
  *
  * @param account The account for which the configuration is needed.
@@ -210,35 +226,50 @@
 GaimProxyInfo *gaim_proxy_get_setup(GaimAccount *account);
 
 /**
- * Makes a connection to the specified host and port.
+ * Makes a connection to the specified host and port.  Note that this
+ * function name can be misleading--although it is called "proxy
+ * connect," it is used for establishing any outgoing TCP connection,
+ * whether through a proxy or not.
  *
- * @param account The account making the connection.
- * @param host    The destination host.
- * @param port    The destination port.
- * @param func    The input handler function.
- * @param data    User-defined data.
+ * @param account    The account making the connection.
+ * @param host       The destination host.
+ * @param port       The destination port.
+ * @param connect_cb The function to call when the connection is
+ *                   established.
+ * @param error_cb   The function to call if there is an error while
+ *                   establishing the connection.
+ * @param data       User-defined data.
  *
- * @return Zero indicates the connection is pending. Any other value indicates failure.
+ * @return NULL if there was an error, or a reference to a data
+ *         structure that can be used to cancel the pending
+ *         connection, if needed.
  */
-int gaim_proxy_connect(GaimAccount *account, const char *host, int port,
-					   GaimInputFunction func, gpointer data);
+GaimProxyConnectInfo *gaim_proxy_connect(GaimAccount *account,
+			const char *host, int port,
+			GaimProxyConnectFunction connect_cb,
+			GaimProxyErrorFunction error_cb, gpointer data);
 
 /**
  * Makes a connection through a SOCKS5 proxy.
  *
- * @param gpi     The GaimProxyInfo specifying the proxy settings
- * @param host    The destination host.
- * @param port    The destination port.
- * @param func    The input handler function.
- * @param data    User-defined data.
+ * @param gpi        The GaimProxyInfo specifying the proxy settings
+ * @param host       The destination host.
+ * @param port       The destination port.
+ * @param connect_cb The function to call when the connection is
+ *                   established.
+ * @param error_cb   The function to call if there is an error while
+ *                   establishing the connection.
+ * @param data       User-defined data.
  *
- * @return Zero indicates the connection is pending. Any other value indicates failure.
+ * @return NULL if there was an error, or a reference to a data
+ *         structure that can be used to cancel the pending
+ *         connection, if needed.
  */
-int gaim_proxy_connect_socks5(GaimProxyInfo *gpi, const char *host, int port,
-					   GaimInputFunction func, gpointer data);
+GaimProxyConnectInfo *gaim_proxy_connect_socks5(GaimProxyInfo *gpi,
+			const char *host, int port,
+			GaimProxyConnectFunction connect_cb,
+			GaimProxyErrorFunction error_cb, gpointer data);
 
-typedef void (*dns_callback_t)(GSList *hosts, gpointer data,
-		const char *error_message);
 /**
  * Do an async dns query
  *
@@ -249,7 +280,7 @@
  *
  * @return Zero indicates the connection is pending. Any other value indicates failure.
  */
-int gaim_gethostbyname_async(const char *hostname, int port, dns_callback_t callback, gpointer data);
+int gaim_gethostbyname_async(const char *hostname, int port, GaimProxyDnsConnectFunction callback, gpointer data);
 
 /*@}*/