network.h File Reference

Network API. More...

Go to the source code of this file.

Network API

typedef struct
_PurpleNetworkListenData 
PurpleNetworkListenData
typedef void(* PurpleNetworkListenCallback )(int listenfd, gpointer data)
const unsigned char * purple_network_ip_atoi (const char *ip)
 Converts a dot-decimal IP address to an array of unsigned chars.
void purple_network_set_public_ip (const char *ip)
 Sets the IP address of the local system in preferences.
const char * purple_network_get_public_ip (void)
 Returns the IP address of the local system set in preferences.
const char * purple_network_get_local_system_ip (int fd)
 Returns the IP address of the local system.
GList * purple_network_get_all_local_system_ips (void)
 Returns all IP addresses of the local system.
const char * purple_network_get_my_ip (int fd)
 Returns the IP address that should be used anywhere a public IP addresses is needed (listening for an incoming file transfer, etc).
void purple_network_listen_map_external (gboolean map_external)
 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.
PurpleNetworkListenData * purple_network_listen (unsigned short port, int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data)
 Attempts to open a listening port ONLY on the specified port number.
PurpleNetworkListenData * purple_network_listen_family (unsigned short port, int socket_family, int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data)
 Attempts to open a listening port ONLY on the specified port number.
PurpleNetworkListenData * purple_network_listen_range (unsigned short start, unsigned short end, int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data)
 Opens a listening port selected from a range of ports.
PurpleNetworkListenData * purple_network_listen_range_family (unsigned short start, unsigned short end, int socket_family, int socket_type, PurpleNetworkListenCallback cb, gpointer cb_data)
 Opens a listening port selected from a range of ports.
void purple_network_listen_cancel (PurpleNetworkListenData *listen_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().
unsigned short purple_network_get_port_from_fd (int fd)
 Gets a port number from a file descriptor.
gboolean purple_network_is_available (void)
 Detects if there is an available network connection.
void purple_network_force_online (void)
 Makes purple_network_is_available() always return TRUE.
void * purple_network_get_handle (void)
 Get the handle for the network system.
void purple_network_set_stun_server (const gchar *stun_server)
 Update the STUN server IP given the host name Will result in a DNS query being executed asynchronous.
const gchar * purple_network_get_stun_ip (void)
 Get the IP address of the STUN server as a string representation.
void purple_network_set_turn_server (const gchar *turn_server)
 Update the TURN server IP given the host name Will result in a DNS query being executed asynchronous.
const gchar * purple_network_get_turn_ip (void)
 Get the IP address of the TURN server as a string representation.
void purple_network_remove_port_mapping (gint fd)
 Remove a port mapping (UPnP or NAT-PMP) associated with listening socket.
int purple_network_convert_idn_to_ascii (const gchar *in, gchar **out)
 Convert a UTF-8 domain name to ASCII in accordance with the IDNA specification.
void purple_network_init (void)
 Initializes the network subsystem.
void purple_network_uninit (void)
 Shuts down the network subsystem.

Detailed Description

Network API.

Definition in file network.h.

Function Documentation

int purple_network_convert_idn_to_ascii ( const gchar *  in,
gchar **  out 
)

Convert a UTF-8 domain name to ASCII in accordance with the IDNA specification.

If libpurple is compiled without IDN support, this function copies the input into the output buffer.

Because this function is used by DNS resolver child/threads, it uses no other libpurple API and is threadsafe.

In general, a buffer of about 512 bytes is the appropriate size to use.

Parameters
inThe hostname to be converted.
outThe output buffer where an allocated string will be returned. 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
void purple_network_force_online ( void  )

Makes purple_network_is_available() always return TRUE.

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
GList* purple_network_get_all_local_system_ips ( void  )

Returns all IP addresses of the local system.

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
Returns
A list of local IP addresses.
void* purple_network_get_handle ( void  )

Get the handle for the network system.

Returns
the handle to the network system
const char* purple_network_get_local_system_ip ( int  fd)

Returns the IP address of the local system.

You probably want to use purple_network_get_my_ip() instead.

Note
The returned string is a pointer to a static buffer. If this function is called twice, it may be important to make a copy of the returned string.
Parameters
fdThe fd to use to help figure out the IP, or else -1.
Returns
The local IP address.
const char* purple_network_get_my_ip ( int  fd)

Returns the IP address that should be used anywhere a public IP addresses is needed (listening for an incoming file transfer, etc).

If the user has manually specified an IP address via preferences, then this IP is returned. Otherwise the IP address returned by purple_network_get_local_system_ip() is returned.

Note
The returned string is a pointer to a static buffer. If this function is called twice, it may be important to make a copy of the returned string.
Parameters
fdThe fd to use to help figure out the IP, or -1.
Returns
The local IP address to be used.
unsigned short purple_network_get_port_from_fd ( int  fd)

Gets a port number from a file descriptor.

Parameters
fdThe file descriptor. This should be a tcp socket. The current implementation probably dies on anything but IPv4. Perhaps this possible bug will inspire new and valuable contributors to Purple.
Returns
The port number, in host byte order.
const char* purple_network_get_public_ip ( void  )

Returns the IP address of the local system set in preferences.

This returns the value set via purple_network_set_public_ip(). You probably want to use purple_network_get_my_ip() instead.

Returns
The local IP address set in preferences.
const gchar* purple_network_get_stun_ip ( void  )

Get the IP address of the STUN server as a string representation.

Returns
the IP address
Since
2.6.0
const gchar* purple_network_get_turn_ip ( void  )

Get the IP address of the TURN server as a string representation.

Returns
the IP address
Since
2.6.0
const unsigned char* purple_network_ip_atoi ( const char *  ip)

Converts a dot-decimal IP address to an array of unsigned chars.

For example, converts 192.168.0.1 to a 4 byte array containing 192, 168, 0 and 1.

Parameters
ipAn IP address in dot-decimal notiation.
Returns
An array of 4 bytes containing an IP addresses equivalent to the given parameter, or NULL if the given IP address is invalid. This value is statically allocated and should not be freed.
gboolean purple_network_is_available ( void  )

Detects if there is an available network connection.

Returns
TRUE if the network is available
PurpleNetworkListenData* purple_network_listen ( unsigned short  port,
int  socket_type,
PurpleNetworkListenCallback  cb,
gpointer  cb_data 
)

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 server as a Purple plugin, and you HAD to listen on port 23. Why anyone would want to do that is beyond me.

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 returned.

Parameters
portThe port number to bind to. Must be greater than 0.
socket_typeThe type of socket to open for listening. This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
cbThe 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.
cb_dataextra data to be returned when cb is called
Returns
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.
void purple_network_listen_cancel ( PurpleNetworkListenData *  listen_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().

Parameters
listen_dataThis listener attempt will be cancelled and the struct will be freed.
PurpleNetworkListenData* purple_network_listen_family ( unsigned short  port,
int  socket_family,
int  socket_type,
PurpleNetworkListenCallback  cb,
gpointer  cb_data 
)

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 server as a Purple plugin, and you HAD to listen on port 23. Why anyone would want to do that is beyond me.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 returned.

Parameters
portThe port number to bind to. Must be greater than 0.
socket_typeThe type of socket to open for listening. This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
cbThe 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.
cb_dataextra data to be returned when cb is called
Returns
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.

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).

Parameters
socket_familyThe 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.
void purple_network_listen_map_external ( gboolean  map_external)

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.

Parameters
map_externalShould 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
PurpleNetworkListenData* purple_network_listen_range ( unsigned short  start,
unsigned short  end,
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. If a non-0 values are passed to the function as parameters, these values are used. Otherwise a port is chosen at random by the operating system.

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 returned.

Parameters
startThe port number to bind to, or 0 to pick a random port. Users are allowed to override this arg in prefs.
endThe 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.
socket_typeThe type of socket to open for listening. This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
cbThe 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.
cb_dataextra data to be returned when cb is called
Returns
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.
PurpleNetworkListenData* purple_network_listen_range_family ( unsigned short  start,
unsigned short  end,
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. If a non-0 values are passed to the function as parameters, these values are used. Otherwise a port is chosen at random by the operating system.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 returned.

Parameters
startThe port number to bind to, or 0 to pick a random port. Users are allowed to override this arg in prefs.
endThe 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.
socket_typeThe type of socket to open for listening. This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
cbThe 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.
cb_dataextra data to be returned when cb is called
Returns
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.

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).

Parameters
socket_familyThe 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.
void purple_network_remove_port_mapping ( gint  fd)

Remove a port mapping (UPnP or NAT-PMP) associated with listening socket.

Parameters
fdSocket to remove the port mapping for
Since
2.6.0
void purple_network_set_public_ip ( const char *  ip)

Sets the IP address of the local system in preferences.

This is the IP address that should be used for incoming connections (file transfer, direct IM, etc.) and should therefore be publicly accessible.

Parameters
ipThe local IP address.
void purple_network_set_stun_server ( const gchar *  stun_server)

Update the STUN server IP given the host name Will result in a DNS query being executed asynchronous.

Parameters
stun_serverThe host name of the STUN server to set
Since
2.6.0
void purple_network_set_turn_server ( const gchar *  turn_server)

Update the TURN server IP given the host name Will result in a DNS query being executed asynchronous.

Parameters
turn_serverThe host name of the TURN server to set
Since
2.6.0
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!