diff libgaim/network.h @ 14267:645598a4ec04

[gaim-migrate @ 16949] Change gaim_network_listen() and gaim_network_listen_range() to be cancelable. This doesn't actually help anything yet, since the gaim_upnp_functions() are not yet cancelable. But the framework is there, and the PRPLs shouldn't need any additional changes. Still to go: gaim_upnp_everything() gaim_url_fetch() gaim_srv_resolve() Let me know if there are others committer: Tailor Script <[e-mail]>

--- a/libgaim/network.h	Mon Aug 21 07:44:31 2006 +0000
+++ b/libgaim/network.h	Mon Aug 21 07:47:03 2006 +0000
@@ -25,11 +25,6 @@
 #ifndef _GAIM_NETWORK_H_
 #define _GAIM_NETWORK_H_
 
-/*
- * TODO: This API needs a way to cancel pending calls to
- *       gaim_network_listen_range() and company.
- */
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -39,6 +34,8 @@
 /**************************************************************************/
 /*@{*/
 
+typedef struct _GaimNetworkListenData GaimNetworkListenData;
+
 typedef void (*GaimNetworkListenCallback) (int listenfd, gpointer data);
 
 /**
@@ -129,11 +126,12 @@
  *           this callback, or -1 if no socket could be established.
  * @param cb_data extra data to be returned when cb is called
  *
- * @return TRUE if the callback will be invoked, or FALSE if unable to obtain
- *              a local socket to listen on.
+ * @return A pointer to a data structure that can be used to cancel
+ *         the pending listener, or NULL if unable to obtain a local
+ *         socket to listen on.
  */
-gboolean gaim_network_listen(unsigned short port, int socket_type,
-	GaimNetworkListenCallback cb, gpointer cb_data);
+GaimNetworkListenData *gaim_network_listen(unsigned short port,
+		int socket_type, GaimNetworkListenCallback cb, gpointer cb_data);
 
 /**
  * Opens a listening port selected from a range of ports.  The range of
@@ -161,11 +159,23 @@
  *           this callback, or -1 if no socket could be established.
  * @param cb_data extra data to be returned when cb is called
  *
- * @return TRUE if the callback will be invoked, or FALSE if unable to obtain
- *              a local socket to listen on.
+ * @return A pointer to a data structure that can be used to cancel
+ *         the pending listener, or NULL if unable to obtain a local
+ *         socket to listen on.
  */
-gboolean gaim_network_listen_range(unsigned short start, unsigned short end,
-	int socket_type, GaimNetworkListenCallback cb, gpointer cb_data);
+GaimNetworkListenData *gaim_network_listen_range(unsigned short start,
+		unsigned short end, int socket_type,
+		GaimNetworkListenCallback cb, gpointer cb_data);
+
+/**
+ * This can be used to cancel any in-progress listener connection
+ * by passing in the return value from either gaim_network_listen()
+ * or gaim_network_listen_range().
+ *
+ * @param listen_data This listener attempt will be canceled and
+ *        the struct will be freed.
+ */
+void gaim_network_listen_cancel(GaimNetworkListenData *listen_data);
 
 /**
  * Gets a port number from a file descriptor.