comparison libgaim/network.h @ 14267:645598a4ec04

[gaim-migrate @ 16949] Change gaim_network_listen() and gaim_network_listen_range() to be cancelable. This doesn't actually help anything yet, since the gaim_upnp_functions() are not yet cancelable. But the framework is there, and the PRPLs shouldn't need any additional changes. Still to go: gaim_upnp_everything() gaim_url_fetch() gaim_srv_resolve() Let me know if there are others committer: Tailor Script <[e-mail]>

14266:63ef6342db05

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef _GAIM_NETWORK_H_
#define _GAIM_NETWORK_H_

/*
 * TODO: This API needs a way to cancel pending calls to
 *       gaim_network_listen_range() and company.
 */

#ifdef __cplusplus
extern "C" {
#endif

/**************************************************************************/
/** @name Network API                                                     */
/**************************************************************************/
/*@{*/

typedef void (*GaimNetworkListenCallback) (int listenfd, gpointer data);

/**
 * Converts a dot-decimal IP address to an array of unsigned

 * @param cb The 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.
 * @param cb_data extra data to be returned when cb is called
 *
 * @return TRUE if the callback will be invoked, or FALSE if unable to obtain
 *              a local socket to listen on.
 */
gboolean gaim_network_listen(unsigned short port, int socket_type,
	GaimNetworkListenCallback 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.

 * @param cb The 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.
 * @param cb_data extra data to be returned when cb is called
 *
 * @return TRUE if the callback will be invoked, or FALSE if unable to obtain
 *              a local socket to listen on.
 */
gboolean gaim_network_listen_range(unsigned short start, unsigned short end,
	int socket_type, GaimNetworkListenCallback cb, gpointer cb_data);

/**
 * Gets a port number from a file descriptor.
 *
 * @param fd The file descriptor. This should be a tcp socket. The current

14267:645598a4ec04

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef _GAIM_NETWORK_H_
#define _GAIM_NETWORK_H_

#ifdef __cplusplus
extern "C" {
#endif

/**************************************************************************/
/** @name Network API                                                     */
/**************************************************************************/
/*@{*/

typedef struct _GaimNetworkListenData GaimNetworkListenData;

typedef void (*GaimNetworkListenCallback) (int listenfd, gpointer data);

/**
 * Converts a dot-decimal IP address to an array of unsigned

 * @param cb The 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.
 * @param cb_data extra data to be returned when cb is called
 *
 * @return 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.
 */
GaimNetworkListenData *gaim_network_listen(unsigned short port,
		int socket_type, GaimNetworkListenCallback 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.

 * @param cb The 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.
 * @param cb_data extra data to be returned when cb is called
 *
 * @return 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.
 */
GaimNetworkListenData *gaim_network_listen_range(unsigned short start,
		unsigned short end, int socket_type,
		GaimNetworkListenCallback cb, gpointer cb_data);

/**
 * This can be used to cancel any in-progress listener connection
 * by passing in the return value from either gaim_network_listen()
 * or gaim_network_listen_range().
 *
 * @param listen_data This listener attempt will be canceled and
 *        the struct will be freed.
 */
void gaim_network_listen_cancel(GaimNetworkListenData *listen_data);

/**
 * Gets a port number from a file descriptor.
 *
 * @param fd The file descriptor. This should be a tcp socket. The current