diff libpurple/network.h @ 29741:35a1cf247168

Add network listen functions that accept a family argument (AF_INET(6?)). These allow code to portably support IPv6 for listeners (mostly file transfers and Bonjour). Callers should use the purple_socket_speaks_ipv4 to determine whether they need two sockets or just an IPv6 one. I used GIO's g_socket_speaks_ipv4 as the inspiration for that.

--- a/libpurple/network.h	Fri Apr 16 03:44:18 2010 +0000
+++ b/libpurple/network.h	Sat Apr 17 01:27:04 2010 +0000
@@ -138,8 +138,8 @@
  *
  * This opens a listening port. The caller will want to set up a watcher
  * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
- * accept in the watcher callback, and then possibly remove the watcher and close
- * the listening socket, and add a new watcher on the new socket accept
+ * accept in the watcher callback, and then possibly remove the watcher and
+ * close the listening socket, and add a new watcher on the new socket accept
  * returned.
  *
  * @param port The port number to bind to.  Must be greater than 0.
@@ -158,6 +158,27 @@
 		int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data);
 
 /**
+ * \copydoc purple_network_listen
+ *
+ * Libpurple does not currently do any port mapping (stateful firewall hole
+ * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
+ * addresses, a mapping is done).
+ * 
+ * @param socket_family The protocol family of the socket.  This should be
+ *                      AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
+ *                      may or may not be able to accept IPv4 connections
+ *                      based on the system configuration (use
+ *                      purple_socket_speaks_ipv4 to check).  If an IPv6
+ *                      socket doesn't accept V4-mapped addresses, you will
+ *                      need a second listener to support both v4 and v6.
+ * @since 2.7.0
+ * @deprecated This function will be renamed to purple_network_listen in 3.0.0.
+ */
+PurpleNetworkListenData *purple_network_listen_family(unsigned short port,
+	int socket_family, int socket_type, PurpleNetworkListenCallback cb,
+	gpointer cb_data);
+
+/**
  * Opens a listening port selected from a range of ports.  The range of
  * ports used is chosen in the following manner:
  * If a range is specified in preferences, these values are used.
@@ -192,6 +213,28 @@
 		PurpleNetworkListenCallback cb, gpointer cb_data);
 
 /**
+ * \copydoc purple_network_listen_range
+ * 
+ * Libpurple does not currently do any port mapping (stateful firewall hole
+ * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
+ * addresses, a mapping is done).
+ * 
+ * @param socket_family The protocol family of the socket.  This should be
+ *                      AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
+ *                      may or may not be able to accept IPv4 connections
+ *                      based on the system configuration (use
+ *                      purple_socket_speaks_ipv4 to check).  If an IPv6
+ *                      socket doesn't accept V4-mapped addresses, you will
+ *                      need a second listener to support both v4 and v6.
+ * @since 2.7.0
+ * @deprecated This function will be renamed to purple_network_listen_range
+ *             in 3.0.0.
+ */
+PurpleNetworkListenData *purple_network_listen_range_family(
+	unsigned short start, unsigned short end, int socket_family,
+	int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data);
+
+/**
  * This can be used to cancel any in-progress listener connection
  * by passing in the return value from either purple_network_listen()
  * or purple_network_listen_range().