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, this function currently only
  94  *       handles IPv4 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 above functions to
 127  *             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 close
 142  * 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  * Opens a listening port selected from a range of ports.  The range of
 162  * ports used is chosen in the following manner:
 163  * If a range is specified in preferences, these values are used.
 164  * If a non-0 values are passed to the function as parameters, these
 165  * values are used.
 166  * Otherwise a port is chosen at random by the operating system.
 167  *
 168  * This opens a listening port. The caller will want to set up a watcher
 169  * of type PURPLE_INPUT_READ on the fd returned in cb. It will probably call
 170  * accept in the watcher callback, and then possibly remove the watcher and close
 171  * the listening socket, and add a new watcher on the new socket accept
 172  * returned.
 173  *
 174  * @param start The port number to bind to, or 0 to pick a random port.
 175  *              Users are allowed to override this arg in prefs.
 176  * @param end The highest possible port in the range of ports to listen on,
 177  *            or 0 to pick a random port.  Users are allowed to override this
 178  *            arg in prefs.
 179  * @param socket_type The type of socket to open for listening.
 180  *   This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
 181  * @param cb The callback to be invoked when the port to listen on is available.
 182  *           The file descriptor of the listening socket will be specified in
 183  *           this callback, or -1 if no socket could be established.
 184  * @param cb_data extra data to be returned when cb is called
 185  *
 186  * @return A pointer to a data structure that can be used to cancel
 187  *         the pending listener, or NULL if unable to obtain a local
 188  *         socket to listen on.
 189  */
 190 PurpleNetworkListenData *purple_network_listen_range(unsigned short start,
 191                 unsigned short end, int socket_type,
 192                 PurpleNetworkListenCallback cb, gpointer cb_data);
 193
 194 /**
 195  * This can be used to cancel any in-progress listener connection
 196  * by passing in the return value from either purple_network_listen()
 197  * or purple_network_listen_range().
 198  *
 199  * @param listen_data This listener attempt will be canceled and
 200  *        the struct will be freed.
 201  */
 202 void purple_network_listen_cancel(PurpleNetworkListenData *listen_data);
 203
 204 /**
 205  * Gets a port number from a file descriptor.
 206  *
 207  * @param fd The file descriptor. This should be a tcp socket. The current
 208  *           implementation probably dies on anything but IPv4. Perhaps this
 209  *           possible bug will inspire new and valuable contributors to Purple.
 210  * @return The port number, in host byte order.
 211  */
 212 unsigned short purple_network_get_port_from_fd(int fd);
 213
 214 /**
 215  * Detects if there is an available network connection.
 216  *
 217  * @return TRUE if the network is available
 218  */
 219 gboolean purple_network_is_available(void);
 220
 221 /**
 222  * Makes purple_network_is_available() always return @c TRUE.
 223  *
 224  * This is what backs the --force-online command line argument in Pidgin,
 225  * for example.  This is useful for offline testing, especially when
 226  * combined with nullprpl.
 227  *
 228  * @since 2.6.0
 229  */
 230 void purple_network_force_online(void);
 231
 232 /**
 233  * Get the handle for the network system
 234  *
 235  * @return the handle to the network system
 236  */
 237 void *purple_network_get_handle(void);
 238
 239 /**
 240  * Update the STUN server IP given the host name
 241  * Will result in a DNS query being executed asynchronous
 242  *
 243  * @param stun_server The host name of the STUN server to set
 244  * @since 2.6.0
 245  */
 246 void purple_network_set_stun_server(const gchar *stun_server);
 247
 248 /**
 249  * Get the IP address of the STUN server as a string representation
 250  *
 251  * @return the IP address
 252  * @since 2.6.0
 253  */
 254 const gchar *purple_network_get_stun_ip(void);
 255
 256 /**
 257  * Update the TURN server IP given the host name
 258  * Will result in a DNS query being executed asynchronous
 259  *
 260  * @param turn_server The host name of the TURN server to set
 261  * @since 2.6.0
 262  */
 263 void purple_network_set_turn_server(const gchar *turn_server);
 264
 265 /**
 266  * Get the IP address of the STUN server as a string representation
 267  *
 268  * @return the IP address
 269  * @since 2.6.0
 270  */
 271 const gchar *purple_network_get_turn_ip(void);
 272
 273 /**
 274  * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
 275  *
 276  * @param fd Socket to remove the port mapping for
 277  * @since 2.6.0
 278  */
 279 void purple_network_remove_port_mapping(gint fd);
 280
 281 /**
 282  * Convert a UTF-8 domain name to ASCII in accordance with the IDNA
 283  * specification. If libpurple is compiled without IDN support, this function
 284  * copies the input into the output buffer.
 285  *
 286  * Because this function is used by DNS resolver child/threads, it uses no
 287  * other libpurple API and is threadsafe.
 288  *
 289  * In general, a buffer of about 512 bytes is the appropriate size to use.
 290  *
 291  * @param in      The hostname to be converted.
 292  * @param out     The output buffer where an allocated string will be returned.
 293  *                The caller is responsible for freeing this.
 294  * @returns       0 on success, -1 if the out is NULL, or an error code
 295  *                that currently corresponds to the Idna_rc enum in libidn.
 296  * @since 2.6.0
 297  */
 298 int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out);
 299
 300 /**
 301  * Initializes the network subsystem.
 302  */
 303 void purple_network_init(void);
 304
 305 /**
 306  * Shuts down the network subsystem.
 307  */
 308 void purple_network_uninit(void);
 309
 310 /*@}*/
 311
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 #endif /* _PURPLE_NETWORK_H_ */