libpurple/network.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_NETWORK_H
  23 #define PURPLE_NETWORK_H
  24 /**
  25  * SECTION:network
  26  * @section_id: libpurple-network
  27  * @short_description: <filename>network.h</filename>
  28  * @title: Network API
  29  */
  30
  31 #include <glib.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**************************************************************************/
  36 /* Network API                                                            */
  37 /**************************************************************************/
  38
  39 typedef struct _PurpleNetworkListenData PurpleNetworkListenData;
  40
  41 typedef void (*PurpleNetworkListenCallback) (int listenfd, gpointer data);
  42
  43 /**
  44  * purple_network_set_public_ip:
  45  * @ip: The local IP address.
  46  *
  47  * Sets the IP address of the local system in preferences.  This
  48  * is the IP address that should be used for incoming connections
  49  * (file transfer, direct IM, etc.) and should therefore be
  50  * publicly accessible.
  51  */
  52 void purple_network_set_public_ip(const char *ip);
  53
  54 /**
  55  * purple_network_get_public_ip:
  56  *
  57  * Returns the IP address of the local system set in preferences.
  58  *
  59  * This returns the value set via purple_network_set_public_ip().
  60  * You probably want to use purple_network_get_my_ip() instead.
  61  *
  62  * Returns: The local IP address set in preferences.
  63  */
  64 const char *purple_network_get_public_ip(void);
  65
  66 /**
  67  * purple_network_get_local_system_ip:
  68  * @fd: The fd to use to help figure out the IP, or else -1.
  69  *
  70  * Returns the IP address of the local system.
  71  *
  72  * You probably want to use purple_network_get_my_ip() instead.
  73  *
  74  * Note: The returned string is a pointer to a static buffer. If this
  75  *       function is called twice, it may be important to make a copy
  76  *       of the returned string.
  77  *
  78  * Returns: The local IP address.
  79  */
  80 const char *purple_network_get_local_system_ip(int fd);
  81
  82 /**
  83  * purple_network_get_all_local_system_ips:
  84  *
  85  * Returns all IP addresses of the local system.
  86  *
  87  * Note: The caller must free this list.  If libpurple was built with
  88  *       support for it, this function also enumerates IPv6 addresses.
  89  *
  90  * Returns: (element-type utf8) (transfer full): A list of local IP addresses.
  91  */
  92 GList *purple_network_get_all_local_system_ips(void);
  93
  94 /**
  95  * purple_network_get_my_ip:
  96  * @fd: The fd to use to help figure out the IP, or -1.
  97  *
  98  * Returns the IP address that should be used anywhere a
  99  * public IP addresses is needed (listening for an incoming
 100  * file transfer, etc).
 101  *
 102  * If the user has manually specified an IP address via
 103  * preferences, then this IP is returned.  Otherwise the
 104  * IP address returned by purple_network_get_local_system_ip()
 105  * is returned.
 106  *
 107  * Note: The returned string is a pointer to a static buffer. If this
 108  *       function is called twice, it may be important to make a copy
 109  *       of the returned string.
 110  *
 111  * Returns: The local IP address to be used.
 112  */
 113 const char *purple_network_get_my_ip(int fd);
 114
 115 /**
 116  * purple_network_listen:
 117  * @port: The port number to bind to.  Must be greater than 0.
 118  * @socket_family: The protocol family of the socket.  This should be
 119  *                 AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
 120  *                 may or may not be able to accept IPv4 connections
 121  *                 based on the system configuration (use
 122  *                 purple_socket_speaks_ipv4 to check).  If an IPv6
 123  *                 socket doesn't accept V4-mapped addresses, you will
 124  *                 need a second listener to support both v4 and v6.
 125  * @socket_type: The type of socket to open for listening.
 126  *               This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
 127  * @map_external: Should the open port be mapped externally using
 128  *                NAT-PNP or UPnP?  (default should be %TRUE)
 129  * @cb: (scope call): The callback to be invoked when the port to listen on is
 130  *      available. The file descriptor of the listening socket will be
 131  *      specified in this callback, or -1 if no socket could be established.
 132  * @cb_data: extra data to be returned when cb is called
 133  *
 134  * Attempts to open a listening port ONLY on the specified port number.
 135  * You probably want to use purple_network_listen_range() instead of this.
 136  * This function is useful, for example, if you wanted to write a telnet
 137  * server as a Purple plugin, and you HAD to listen on port 23.  Why anyone
 138  * would want to do that is beyond me.
 139  *
 140  * This opens a listening port. The caller will want to set up a watcher
 141  * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
 142  * accept in the watcher callback, and then possibly remove the watcher and
 143  * close the listening socket, and add a new watcher on the new socket accept
 144  * returned.
 145  *
 146  * Libpurple does not currently do any port mapping (stateful firewall hole
 147  * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
 148  * addresses, a mapping is done).
 149  *
 150  * Returns: A pointer to a data structure that can be used to cancel
 151  *          the pending listener, or %NULL if unable to obtain a local
 152  *          socket to listen on.
 153  */
 154 PurpleNetworkListenData *purple_network_listen(unsigned short port,
 155         int socket_family, int socket_type, gboolean map_external,
 156         PurpleNetworkListenCallback cb, gpointer cb_data);
 157
 158 /**
 159  * purple_network_listen_range:
 160  * @start: The port number to bind to, or 0 to pick a random port.
 161  *         Users are allowed to override this arg in prefs.
 162  * @end: The highest possible port in the range of ports to listen on,
 163  *       or 0 to pick a random port.  Users are allowed to override this
 164  *       arg in prefs.
 165  * @socket_family: The protocol family of the socket.  This should be
 166  *                 AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
 167  *                 may or may not be able to accept IPv4 connections
 168  *                 based on the system configuration (use
 169  *                 purple_socket_speaks_ipv4 to check).  If an IPv6
 170  *                 socket doesn't accept V4-mapped addresses, you will
 171  *                 need a second listener to support both v4 and v6.
 172  * @socket_type: The type of socket to open for listening.
 173  *               This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
 174  * @map_external: Should the open port be mapped externally using
 175  *                NAT-PNP or UPnP?  (default should be %TRUE)
 176  * @cb: (scope call): The callback to be invoked when the port to listen on is
 177  *      available. The file descriptor of the listening socket will be
 178  *      specified in this callback, or -1 if no socket could be established.
 179  * @cb_data: extra data to be returned when cb is called
 180  *
 181  * Opens a listening port selected from a range of ports.  The range of
 182  * ports used is chosen in the following manner:
 183  * If a range is specified in preferences, these values are used.
 184  * If a non-0 values are passed to the function as parameters, these
 185  * values are used.
 186  * Otherwise a port is chosen at random by the operating system.
 187  *
 188  * This opens a listening port. The caller will want to set up a watcher
 189  * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
 190  * accept in the watcher callback, and then possibly remove the watcher and close
 191  * the listening socket, and add a new watcher on the new socket accept
 192  * returned.
 193  *
 194  * Libpurple does not currently do any port mapping (stateful firewall hole
 195  * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
 196  * addresses, a mapping is done).
 197  *
 198  * Returns: A pointer to a data structure that can be used to cancel
 199  *          the pending listener, or %NULL if unable to obtain a local
 200  *          socket to listen on.
 201  */
 202 PurpleNetworkListenData *purple_network_listen_range(
 203         unsigned short start, unsigned short end, int socket_family,
 204         int socket_type, gboolean map_external,
 205         PurpleNetworkListenCallback cb, gpointer cb_data);
 206
 207 /**
 208  * purple_network_listen_cancel:
 209  * @listen_data: This listener attempt will be cancelled and
 210  *        the struct will be freed.
 211  *
 212  * This can be used to cancel any in-progress listener connection
 213  * by passing in the return value from either purple_network_listen()
 214  * or purple_network_listen_range().
 215  */
 216 void purple_network_listen_cancel(PurpleNetworkListenData *listen_data);
 217
 218 /**
 219  * purple_network_get_port_from_fd:
 220  * @fd: The file descriptor. This should be a tcp socket. The current
 221  *           implementation probably dies on anything but IPv4. Perhaps this
 222  *           possible bug will inspire new and valuable contributors to Purple.
 223  *
 224  * Gets a port number from a file descriptor.
 225  *
 226  * Returns: The port number, in host byte order.
 227  */
 228 unsigned short purple_network_get_port_from_fd(int fd);
 229
 230 /**
 231  * purple_network_is_available:
 232  *
 233  * Detects if there is an available network connection.
 234  *
 235  * Returns: TRUE if the network is available
 236  */
 237 gboolean purple_network_is_available(void);
 238
 239 /**
 240  * purple_network_force_online:
 241  *
 242  * Makes purple_network_is_available() always return %TRUE.
 243  *
 244  * This is what backs the --force-online command line argument in Pidgin,
 245  * for example.  This is useful for offline testing, especially when
 246  * combined with nullprotocol.
 247  */
 248 void purple_network_force_online(void);
 249
 250 /**
 251  * purple_network_get_handle:
 252  *
 253  * Get the handle for the network system
 254  *
 255  * Returns: the handle to the network system
 256  */
 257 void *purple_network_get_handle(void);
 258
 259 /**
 260  * purple_network_set_stun_server:
 261  * @stun_server: The host name of the STUN server to set
 262  *
 263  * Update the STUN server IP given the host name
 264  * Will result in a DNS query being executed asynchronous
 265  */
 266 void purple_network_set_stun_server(const gchar *stun_server);
 267
 268 /**
 269  * purple_network_get_stun_ip:
 270  *
 271  * Get the IP address of the STUN server as a string representation
 272  *
 273  * Returns: the IP address
 274  */
 275 const gchar *purple_network_get_stun_ip(void);
 276
 277 /**
 278  * purple_network_set_turn_server:
 279  * @turn_server: The host name of the TURN server to set
 280  *
 281  * Update the TURN server IP given the host name
 282  * Will result in a DNS query being executed asynchronous
 283  */
 284 void purple_network_set_turn_server(const gchar *turn_server);
 285
 286 /**
 287  * purple_network_get_turn_ip:
 288  *
 289  * Get the IP address of the TURN server as a string representation
 290  *
 291  * Returns: the IP address
 292  */
 293 const gchar *purple_network_get_turn_ip(void);
 294
 295 /**
 296  * purple_network_remove_port_mapping:
 297  * @fd: Socket to remove the port mapping for
 298  *
 299  * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
 300  */
 301 void purple_network_remove_port_mapping(gint fd);
 302
 303 /**
 304  * purple_network_init:
 305  *
 306  * Initializes the network subsystem.
 307  */
 308 void purple_network_init(void);
 309
 310 /**
 311  * purple_network_uninit:
 312  *
 313  * Shuts down the network subsystem.
 314  */
 315 void purple_network_uninit(void);
 316
 317 G_END_DECLS
 318
 319 #endif /* PURPLE_NETWORK_H */