Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/network.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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_ */