libpurple/network.h

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