diff src/upnp.h @ 12909:8e3b85fe4a55

[gaim-migrate @ 15262] Make UPnP truly asynchronous. There are probably still a couple socket calls that should be made nonblocking, but I wanted to commit this before it became even bigger. This contains a number of probable leak fixes in the upnp stuff. The UPnP stuff has been updated to use gaim_url_fetch_request() instead of the specific implementation. To make this all work, I had to make gaim_network_listen() and gaim_network_listen_range() also asynchronous - seems to work just fine apart from the UPnP calls seeming to take longer than they should (I'm planning to look into this). I also triggered a STUN and UPnP discovery on startup so that we hopefully have the information when we need it. committer: Tailor Script <[e-mail]>

--- a/src/upnp.h	Tue Jan 17 05:20:38 2006 +0000
+++ b/src/upnp.h	Tue Jan 17 05:48:51 2006 +0000
@@ -27,13 +27,6 @@
 #define _GAIM_UPNP_H_
 
 
-typedef struct
-{
-  gchar* controlURL;
-  gchar* serviceType;
-} GaimUPnPControlInfo;
-
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -43,27 +36,42 @@
 /**************************************************************************/
 /*@{*/
 
+
+typedef void (*GaimUPnPCallback) (gboolean success, gpointer data);
+
 /**
  * Sends a discovery request to search for a UPnP enabled IGD that
  * contains the WANIPConnection service that will allow us to recieve the
  * public IP address of the IGD, and control it for forwarding ports.
+ * The result will be cached for further use.
  *
+ * @param cb an optional callback function to be notified when the UPnP
+ *           discovery is complete
+ * @param cb_data Extra data to be passed to the callback
+ */
+void gaim_upnp_discover(GaimUPnPCallback cb, gpointer cb_data);
+
+#if 0
+/**
+ * Retrieve the current UPnP control info, if there is any available.
+ * This will only be filled in if gaim_upnp_discover() had been called,
+ * and finished discovering.
+ * 
  * @return The control URL for the IGD we'll use to use the IGD services
  */
-GaimUPnPControlInfo* gaim_upnp_discover(void);
-
+const GaimUPnPControlInfo* gaim_upnp_get_control_info(void);
+#endif
 
 
 /**
  * Gets the IP address from a UPnP enabled IGD that sits on the local
  * network, so when getting the network IP, instead of returning the
- * local network IP, the public IP is retrieved.
- *
- * @param controlInfo The control URL retrieved from gaim_upnp_discover.
+ * local network IP, the public IP is retrieved.  This is a cached value from
+ * the time of the UPnP discovery.
  *
  * @return The IP address of the network, or NULL if something went wrong
  */
-gchar* gaim_upnp_get_public_ip(const GaimUPnPControlInfo* controlInfo);
+const gchar* gaim_upnp_get_public_ip(void);
 
 
 /**
@@ -71,15 +79,14 @@
  * this gaim client. Essentially, this function takes care of the port
  * forwarding so things like file transfers can work behind NAT firewalls
  *
- * @param controlInfo The control URL retrieved from gaim_upnp_discover.
- * @param portMap The port to map to this client
+ * @param portmap The port to map to this client
  * @param protocol The protocol to map, either "TCP" or "UDP"
- *
- * @return TRUE if success, FALSE if something went wrong.
+ * @param cb an optional callback function to be notified when the mapping
+ *           addition is complete
+ * @param cb_data Extra data to be passed to the callback
  */
-gboolean gaim_upnp_set_port_mapping(const GaimUPnPControlInfo* controlInfo, 
-                                    unsigned short portMap,
-                                    const gchar* protocol);
+void gaim_upnp_set_port_mapping(unsigned short portmap, const gchar* protocol,
+		GaimUPnPCallback cb, gpointer cb_data);
 
 /**
  * Deletes a port mapping in a UPnP enabled IGD that sits on the local network
@@ -87,19 +94,16 @@
  * port forwarding after they have completed a connection so another client on
  * the local network can take advantage of the port forwarding
  *
- * @param controlInfo The control URL retrieved from gaim_upnp_discover.
- * @param portMap The port to delete the mapping for
+ * @param portmap The port to delete the mapping for
  * @param protocol The protocol to map to. Either "TCP" or "UDP"
- *
- * @return TRUE if success, FALSE if something went wrong.
+ * @param cb an optional callback function to be notified when the mapping
+ *           removal is complete
+ * @param cb_data Extra data to be passed to the callback
  */
-gboolean 
-gaim_upnp_remove_port_mapping(const GaimUPnPControlInfo* controlInfo,
-                              unsigned short portMap,
-                              const gchar* protocol);
+void gaim_upnp_remove_port_mapping(unsigned short portmap,
+		const gchar* protocol, GaimUPnPCallback cb, gpointer cb_data);
 /*@}*/
 
-
 #ifdef __cplusplus
 }
 #endif