--- a/libpurple/network.h Mon Aug 22 22:46:08 2011 +0000
+++ b/libpurple/network.h Fri Dec 23 08:21:58 2011 +0000
@@ -92,7 +92,6 @@
*
* @note The caller must free this list. If libpurple was built with
* support for it, this function also enumerates IPv6 addresses.
- * @since 2.7.0
*
* @return A list of local IP addresses.
*/
@@ -118,18 +117,6 @@
const char *purple_network_get_my_ip(int fd);
/**
- * Should calls to purple_network_listen() and purple_network_listen_range()
- * map the port externally using NAT-PMP or UPnP?
- * The default value is TRUE
- *
- * @param map_external Should the open port be mapped externally?
- * @deprecated In 3.0.0 a boolean will be added to the functions mentioned
- * above to perform the same function.
- * @since 2.3.0
- */
-void purple_network_listen_map_external(gboolean map_external);
-
-/**
* Attempts to open a listening port ONLY on the specified port number.
* You probably want to use purple_network_listen_range() instead of this.
* This function is useful, for example, if you wanted to write a telnet
@@ -142,9 +129,22 @@
* close the listening socket, and add a new watcher on the new socket accept
* returned.
*
+ * 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 port The port number to bind to. Must be greater than 0.
+ * @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.
* @param socket_type The type of socket to open for listening.
* This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
+ * @param map_external Should the open port be mapped externally using
+ * NAT-PNP or UPnP? (default should be TRUE)
* @param cb The callback to be invoked when the port to listen on is available.
* The file descriptor of the listening socket will be specified in
* this callback, or -1 if no socket could be established.
@@ -155,28 +155,8 @@
* socket to listen on.
*/
PurpleNetworkListenData *purple_network_listen(unsigned short port,
- 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);
+ int socket_family, int socket_type, gboolean map_external,
+ PurpleNetworkListenCallback cb, gpointer cb_data);
/**
* Opens a listening port selected from a range of ports. The range of
@@ -192,13 +172,26 @@
* the listening socket, and add a new watcher on the new socket accept
* returned.
*
+ * 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 start The port number to bind to, or 0 to pick a random port.
* Users are allowed to override this arg in prefs.
* @param end The highest possible port in the range of ports to listen on,
* or 0 to pick a random port. Users are allowed to override this
* arg in prefs.
+ * @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.
* @param socket_type The type of socket to open for listening.
* This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
+ * @param map_external Should the open port be mapped externally using
+ * NAT-PNP or UPnP? (default should be TRUE)
* @param cb The callback to be invoked when the port to listen on is available.
* The file descriptor of the listening socket will be specified in
* this callback, or -1 if no socket could be established.
@@ -208,31 +201,10 @@
* the pending listener, or NULL if unable to obtain a local
* socket to listen on.
*/
-PurpleNetworkListenData *purple_network_listen_range(unsigned short start,
- unsigned short end, int socket_type,
- 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(
+PurpleNetworkListenData *purple_network_listen_range(
unsigned short start, unsigned short end, int socket_family,
- int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data);
+ int socket_type, gboolean map_external,
+ PurpleNetworkListenCallback cb, gpointer cb_data);
/**
* This can be used to cancel any in-progress listener connection
@@ -267,8 +239,6 @@
* This is what backs the --force-online command line argument in Pidgin,
* for example. This is useful for offline testing, especially when
* combined with nullprpl.
- *
- * @since 2.6.0
*/
void purple_network_force_online(void);
@@ -284,7 +254,6 @@
* Will result in a DNS query being executed asynchronous
*
* @param stun_server The host name of the STUN server to set
- * @since 2.6.0
*/
void purple_network_set_stun_server(const gchar *stun_server);
@@ -292,7 +261,6 @@
* Get the IP address of the STUN server as a string representation
*
* @return the IP address
- * @since 2.6.0
*/
const gchar *purple_network_get_stun_ip(void);
@@ -301,7 +269,6 @@
* Will result in a DNS query being executed asynchronous
*
* @param turn_server The host name of the TURN server to set
- * @since 2.6.0
*/
void purple_network_set_turn_server(const gchar *turn_server);
@@ -309,7 +276,6 @@
* Get the IP address of the TURN server as a string representation
*
* @return the IP address
- * @since 2.6.0
*/
const gchar *purple_network_get_turn_ip(void);
@@ -317,7 +283,6 @@
* Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
*
* @param fd Socket to remove the port mapping for
- * @since 2.6.0
*/
void purple_network_remove_port_mapping(gint fd);
@@ -336,7 +301,6 @@
* The caller is responsible for freeing this.
* @returns 0 on success, -1 if the out is NULL, or an error code
* that currently corresponds to the Idna_rc enum in libidn.
- * @since 2.6.0
*/
int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out);
