comparison libpurple/util.h @ 32815:3d6528f36877

propagate from branch 'im.pidgin.pidgin.2.x.y' (head 5ca378b115ef36cfafb203fb88623734a7c6bb23) to branch 'im.pidgin.pidgin' (head ccfb262bb9e313a5281f05015530ef94fc58a573)

32814:626c339b60ae

/**
  * An opaque structure representing a URL request. Can be used to cancel
  * the request.
  */
typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData;
/** @copydoc _PurpleMenuAction */
typedef struct _PurpleMenuAction PurpleMenuAction;
/** @copydoc _PurpleKeyValuePair */
typedef struct _PurpleKeyValuePair PurpleKeyValuePair;

#include "account.h"
#include "signals.h"
#include "xmlnode.h"
#include "notify.h"


#ifdef __cplusplus
extern "C" {
#endif

struct _PurpleMenuAction
{
	char *label;
	PurpleCallback callback;
	gpointer data;
	GList *children;
};

typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);

/**
 * A key-value pair.
 *
 * This is used by, among other things, purple_gtk_combo* functions to pass in a
 * list of key-value pairs so it can display a user-friendly value.
 */
struct _PurpleKeyValuePair
{
	gchar *key;
	void *value;

};

/**
 * Creates a new PurpleMenuAction.
 *
 * @param label    The text label to display for this action.

 * @param act The PurpleMenuAction to free.
 */
void purple_menu_action_free(PurpleMenuAction *act);

/**
 * Set the appropriate presence values for the currently playing song.
 *
 * @param title     The title of the song, @c NULL to unset the value.
 * @param artist    The artist of the song, can be @c NULL.
 * @param album     The album of the song, can be @c NULL.
 * @since 2.4.0
 */
void purple_util_set_current_song(const char *title, const char *artist,
		const char *album);

/**

 * @param artist    The artist of the song, can be @c NULL.
 * @param album     The album of the song, can be @c NULL.
 * @param unused    Currently unused, must be @c NULL.
 *
 * @return   The formatted string. The caller must g_free the returned string.
 * @since 2.4.0
 */
char * purple_util_format_song_info(const char *title, const char *artist,
		const char *album, gpointer unused);

/**************************************************************************/

/**************************************************************************/
/*@{*/

/**
 * Initializes the utility subsystem.
 *
 * @since 2.3.0
 */
void purple_util_init(void);

/**
 * Uninitializes the util subsystem.
 *
 * @since 2.3.0
 */
void purple_util_uninit(void);

/*@}*/

 * replaced with <
 *
 * This is exactly the same as g_markup_escape_text(), except that it
 * does not change ' to ' because ' is not a valid HTML 4 entity,
 * and is displayed literally in IE7.
 *
 * @since 2.6.0
 */
gchar *purple_markup_escape_text(const gchar *text, gssize length);

/**
 * Finds an HTML tag matching the given name.

 *
 * @return The text with HTML entities literalized.  You must g_free
 *         this string when finished with it.
 *
 * @see purple_unescape_html()
 * @since 2.7.0
 */
char *purple_unescape_text(const char *text);

/**
 * Unescapes HTML entities to their literal characters and converts

 * Check if the given HTML contains RTL text.
 *
 * @param html  The HTML text.
 *
 * @return  TRUE if the text contains RTL text, FALSE otherwise.
 *
 * @since 2.6.0
 */
gboolean purple_markup_is_rtl(const char *html);

/*@}*/

 *
 * @param fd The socket file descriptor.
 *
 * @return The address family of the socket (AF_INET, AF_INET6, etc) or -1
 *         on error.
 * @since 2.7.0
 */
int purple_socket_get_family(int fd);

/**
 * Returns TRUE if a socket is capable of speaking IPv4.

 * This is the case for IPv4 sockets and, on some systems, IPv6 sockets
 * (due to the IPv4-mapped address functionality).
 *
 * @param fd The socket file descriptor
 * @return TRUE if a socket can speak IPv4.
 * @since 2.7.0
 */
gboolean purple_socket_speaks_ipv4(int fd);

/*@}*/

 *
 * @param left	A string
 * @param right A string to compare with left
 *
 * @return @c TRUE if the strings are the same, else @c FALSE.
 *
 * @since 2.6.0
 */
gboolean purple_strequal(const gchar *left, const gchar *right);

/**
 * Normalizes a string, so that it is suitable for comparison.

 *
 * @param size The size
 *
 * @return The string in units form. This must be freed.
 */
char *purple_str_size_to_units(size_t size);

/**
 * Converts seconds into a human-readable form.
 *
 * @param sec The seconds.

 * @param url        The URL.
 * @param full       TRUE if this is the full URL, or FALSE if it's a
 *                   partial URL.
 * @param user_agent The user agent field to use, or NULL.
 * @param http11     TRUE if HTTP/1.1 should be used to download the file.
 * @param cb         The callback function.
 * @param data       The user data to pass to the callback function.
 */
#define purple_util_fetch_url(url, full, user_agent, http11, cb, data) \
	purple_util_fetch_url_request(url, full, user_agent, http11, NULL, \
		FALSE, cb, data);

/**
 * Fetches the data from a URL, and passes it to a callback function.
 *
 * @param url        The URL.
 * @param full       TRUE if this is the full URL, or FALSE if it's a
 *                   partial URL.
 * @param user_agent The user agent field to use, or NULL.
 * @param http11     TRUE if HTTP/1.1 should be used to download the file.
 * @param max_len    The maximum number of bytes to retrieve (-1 for unlimited)
 * @param cb         The callback function.
 * @param data       The user data to pass to the callback function.
 * @deprecated       In 3.0.0, we'll rename this to "purple_util_fetch_url" and get rid of the old one
 */
#define purple_util_fetch_url_len(url, full, user_agent, http11, max_len, cb, data) \
	purple_util_fetch_url_request_len(url, full, user_agent, http11, NULL, \
		FALSE, max_len, cb, data);

/**
 * Fetches the data from a URL, and passes it to a callback function.
 *
 * @param url        The URL.
 * @param full       TRUE if this is the full URL, or FALSE if it's a
 *                   partial URL.
 * @param user_agent The user agent field to use, or NULL.
 * @param http11     TRUE if HTTP/1.1 should be used to download the file.
 * @param request    A HTTP request to send to the server instead of the
 *                   standard GET
 * @param include_headers
 *                   If TRUE, include the HTTP headers in the response.
 * @param callback   The callback function.
 * @param data       The user data to pass to the callback function.
 */
PurpleUtilFetchUrlData *purple_util_fetch_url_request(const gchar *url,
		gboolean full, const gchar *user_agent, gboolean http11,
		const gchar *request, gboolean include_headers,
		PurpleUtilFetchUrlCallback callback, gpointer data);

/**
 * Fetches the data from a URL, and passes it to a callback function.
 *
 * @param url        The URL.
 * @param full       TRUE if this is the full URL, or FALSE if it's a
 *                   partial URL.
 * @param user_agent The user agent field to use, or NULL.
 * @param http11     TRUE if HTTP/1.1 should be used to download the file.
 * @param request    A HTTP request to send to the server instead of the
 *                   standard GET
 * @param include_headers
 *                   If TRUE, include the HTTP headers in the response.
 * @param max_len    The maximum number of bytes to retrieve (-1 for unlimited)
 * @param callback   The callback function.
 * @param data       The user data to pass to the callback function.
 * @deprecated       In 3.0.0, this will go away.
 */
PurpleUtilFetchUrlData *purple_util_fetch_url_request_len(const gchar *url,
		gboolean full, const gchar *user_agent, gboolean http11,
		const gchar *request, gboolean include_headers, gssize max_len,
		PurpleUtilFetchUrlCallback callback, gpointer data);

/**
 * Fetches the data from a URL, and passes it to a callback function.
 *
 * @param account    The account for which the request is needed, or NULL.

 * @param include_headers
 *                   If TRUE, include the HTTP headers in the response.
 * @param max_len    The maximum number of bytes to retrieve (-1 for unlimited)
 * @param callback   The callback function.
 * @param data       The user data to pass to the callback function.
 * @deprecated       In 3.0.0, we'll rename this to "purple_util_fetch_url_request" and get rid of the old one
 */
PurpleUtilFetchUrlData *purple_util_fetch_url_request_len_with_account(
		PurpleAccount *account, const gchar *url,
		gboolean full, const gchar *user_agent, gboolean http11,
		const gchar *request, gboolean include_headers, gssize max_len,
		PurpleUtilFetchUrlCallback callback, gpointer data);

 * @return True if the email address is syntactically correct.
 */
gboolean purple_email_is_valid(const char *address);

/**
 * Checks if the given IP address is a syntactically valid IPv4 address.
 *
 * @param ip The IP address to validate.
 *
 * @return True if the IP address is syntactically correct.
 * @deprecated This function will be replaced with one that validates
 *             as either IPv4 or IPv6 in 3.0.0. If you don't want this,
 *             behavior, use one of the more specific functions.
 */
gboolean purple_ip_address_is_valid(const char *ip);

/**
 * Checks if the given IP address is a syntactically valid IPv4 address.
 *
 * @param ip The IP address to validate.
 *
 * @return True if the IP address is syntactically correct.
 * @since 2.6.0
 */
gboolean purple_ipv4_address_is_valid(const char *ip);

/**
 * Checks if the given IP address is a syntactically valid IPv6 address.
 *
 * @param ip The IP address to validate.
 *
 * @return True if the IP address is syntactically correct.
 * @since 2.6.0
 */
gboolean purple_ipv6_address_is_valid(const char *ip);

/**
 * This function extracts a list of URIs from the a "text/uri-list"

 * The returned string must be freed by the caller.
 *
 * @param str A valid UTF-8 string.
 *
 * @return A newly allocated UTF-8 string without the unprintable characters.
 * @since 2.6.0
 */
gchar *purple_utf8_strip_unprintables(const gchar *str);

/**
 * Return the UTF-8 version of gai_strerror().  It calls gai_strerror()

 * g_strerror().
 *
 * @param errnum The error code.
 *
 * @return The UTF-8 error message.
 * @since 2.4.0
 */
G_CONST_RETURN gchar *purple_gai_strerror(gint errnum);

/**
 * Compares two UTF-8 strings case-insensitively.  This comparison is
 * more expensive than a simple g_utf8_collate() comparison because
 * it calls g_utf8_casefold() on each string, which allocates new

 * @return The resulting string.
 */
const char *purple_escape_filename(const char *str);

/**
 * This is added temporarily to assist the split of oscar into aim and icq.
 * This should not be used by plugins.
 *
 * @deprecated This function should not be used in new code and should be
 *             removed in 3.0.0.  The aim/icq prpl split happened a long
 *             time ago, and we don't need to keep migrating old data.
 */
const char *_purple_oscar_convert(const char *act, const char *protocol);

/**
 * Restore default signal handlers for signals which might reasonably have
 * handlers. This should be called by a fork()'d child process, since child processes
 * inherit the handlers of the parent.
 */
void purple_restore_default_signal_handlers(void);

/**
 * Returns a type 4 (random) UUID
 *
 * @return A UUID, caller is responsible for freeing it
 * @since 2.7.0
 */
gchar *purple_uuid_random(void);

#ifdef __cplusplus
}
#endif

#endif /* _PURPLE_UTIL_H_ */

32815:3d6528f36877

/**
  * An opaque structure representing a URL request. Can be used to cancel
  * the request.
  */
typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData;

/**
 * A generic structure that contains information about an "action."  One
 * place this is is used is by PRPLs to tell the core the list of available
 * right-click actions for a buddy list row.
 */
typedef struct _PurpleMenuAction PurpleMenuAction;

/**
 * A key-value pair.
 *
 * This is used by, among other things, purple_gtk_combo* functions to pass in a
 * list of key-value pairs so it can display a user-friendly value.
 */
typedef struct _PurpleKeyValuePair PurpleKeyValuePair;

#include "account.h"
#include "signals.h"
#include "xmlnode.h"
#include "notify.h"


typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);

struct _PurpleKeyValuePair
{
	gchar *key;
	void *value;

};

G_BEGIN_DECLS

/**
 * Creates a new PurpleMenuAction.
 *
 * @param label    The text label to display for this action.

 * @param act The PurpleMenuAction to free.
 */
void purple_menu_action_free(PurpleMenuAction *act);

/**
 * Returns the label of the PurpleMenuAction.
 *
 * @param act	The PurpleMenuAction.
 *
 * @return The label string.
 */
char * purple_menu_action_get_label(const PurpleMenuAction *act);

/**
 * Returns the callback of the PurpleMenuAction.
 *
 * @param act	The PurpleMenuAction.
 *
 * @return The callback function.
 */
PurpleCallback purple_menu_action_get_callback(const PurpleMenuAction *act);

/**
 * Returns the data stored in the PurpleMenuAction.
 *
 * @param act	The PurpleMenuAction.
 *
 * @return The data.
 */
gpointer purple_menu_action_get_data(const PurpleMenuAction *act);

/**
 * Returns the children of the PurpleMenuAction.
 *
 * @param act	The PurpleMenuAction.
 *
 * @return The  GList of children.
 */
GList* purple_menu_action_get_children(const PurpleMenuAction *act);

/**
 * Set the label to the PurpleMenuAction.
 *
 * @param act   The menu action.
 * @param label The label for the menu action.
 */
void purple_menu_action_set_label(PurpleMenuAction *act, char *label);

/**
 * Set the callback that will be used by the PurpleMenuAction.
 *
 * @param act        The menu action.
 * @param callback   The callback.
 */
void purple_menu_action_set_callback(PurpleMenuAction *act, PurpleCallback callback);

/**
 * Set the label to the PurpleMenuAction.
 *
 * @param act   The menu action.
 * @param data  The data used by this PurpleMenuAction
 */
void purple_menu_action_set_data(PurpleMenuAction *act, gpointer data);

/**
 * Set the children of the PurpleMenuAction.
 *
 * @param act       The menu action.
 * @param children  The PurpleMenuAtion children
 */
void purple_menu_action_set_children(PurpleMenuAction *act, GList *children);

/**
 * Set the appropriate presence values for the currently playing song.
 *
 * @param title     The title of the song, @c NULL to unset the value.
 * @param artist    The artist of the song, can be @c NULL.
 * @param album     The album of the song, can be @c NULL.
 */
void purple_util_set_current_song(const char *title, const char *artist,
		const char *album);

/**

 * @param artist    The artist of the song, can be @c NULL.
 * @param album     The album of the song, can be @c NULL.
 * @param unused    Currently unused, must be @c NULL.
 *
 * @return   The formatted string. The caller must g_free the returned string.
 */
char * purple_util_format_song_info(const char *title, const char *artist,
		const char *album, gpointer unused);

/**************************************************************************/

/**************************************************************************/
/*@{*/

/**
 * Initializes the utility subsystem.
 */
void purple_util_init(void);

/**
 * Uninitializes the util subsystem.
 */
void purple_util_uninit(void);

/*@}*/

 * replaced with <
 *
 * This is exactly the same as g_markup_escape_text(), except that it
 * does not change ' to ' because ' is not a valid HTML 4 entity,
 * and is displayed literally in IE7.
 */
gchar *purple_markup_escape_text(const gchar *text, gssize length);

/**
 * Finds an HTML tag matching the given name.

 *
 * @return The text with HTML entities literalized.  You must g_free
 *         this string when finished with it.
 *
 * @see purple_unescape_html()
 */
char *purple_unescape_text(const char *text);

/**
 * Unescapes HTML entities to their literal characters and converts

 * Check if the given HTML contains RTL text.
 *
 * @param html  The HTML text.
 *
 * @return  TRUE if the text contains RTL text, FALSE otherwise.
 */
gboolean purple_markup_is_rtl(const char *html);

/*@}*/

 *
 * @param fd The socket file descriptor.
 *
 * @return The address family of the socket (AF_INET, AF_INET6, etc) or -1
 *         on error.
 */
int purple_socket_get_family(int fd);

/**
 * Returns TRUE if a socket is capable of speaking IPv4.

 * This is the case for IPv4 sockets and, on some systems, IPv6 sockets
 * (due to the IPv4-mapped address functionality).
 *
 * @param fd The socket file descriptor
 * @return TRUE if a socket can speak IPv4.
 */
gboolean purple_socket_speaks_ipv4(int fd);

/*@}*/

 *
 * @param left	A string
 * @param right A string to compare with left
 *
 * @return @c TRUE if the strings are the same, else @c FALSE.
 */
gboolean purple_strequal(const gchar *left, const gchar *right);

/**
 * Normalizes a string, so that it is suitable for comparison.

 *
 * @param size The size
 *
 * @return The string in units form. This must be freed.
 */
char *purple_str_size_to_units(goffset size);

/**
 * Converts seconds into a human-readable form.
 *
 * @param sec The seconds.

 * @param url        The URL.
 * @param full       TRUE if this is the full URL, or FALSE if it's a
 *                   partial URL.
 * @param user_agent The user agent field to use, or NULL.
 * @param http11     TRUE if HTTP/1.1 should be used to download the file.
 * @param max_len    The maximum number of bytes to retrieve (-1 for unlimited)
 * @param cb         The callback function.
 * @param data       The user data to pass to the callback function.
 */
#define purple_util_fetch_url(url, full, user_agent, http11, max_len, cb, data) \
	purple_util_fetch_url_request(NULL, url, full, user_agent, http11, NULL, \
		FALSE, max_len, cb, data);

/**
 * Fetches the data from a URL, and passes it to a callback function.
 *
 * @param account    The account for which the request is needed, or NULL.

 * @param include_headers
 *                   If TRUE, include the HTTP headers in the response.
 * @param max_len    The maximum number of bytes to retrieve (-1 for unlimited)
 * @param callback   The callback function.
 * @param data       The user data to pass to the callback function.
 */
PurpleUtilFetchUrlData *purple_util_fetch_url_request(
		PurpleAccount *account, const gchar *url,
		gboolean full, const gchar *user_agent, gboolean http11,
		const gchar *request, gboolean include_headers, gssize max_len,
		PurpleUtilFetchUrlCallback callback, gpointer data);

 * @return True if the email address is syntactically correct.
 */
gboolean purple_email_is_valid(const char *address);

/**
 * Checks if the given IP address is a syntactically valid IPv4 or
 * IPv6 address.
 * If you specifically want to check for an IPv4 address use
 * purple_ipv4_address_is_valid(), or for an IPv6 address use
 * purple_ipv6_address_is_valid().
 *
 * @param ip The IP address to validate.
 *
 * @return True if the IP address is syntactically correct.
 */
gboolean purple_ip_address_is_valid(const char *ip);

/**
 * Checks if the given IP address is a syntactically valid IPv4 address.
 *
 * @param ip The IP address to validate.
 *
 * @return True if the IP address is syntactically correct.
 */
gboolean purple_ipv4_address_is_valid(const char *ip);

/**
 * Checks if the given IP address is a syntactically valid IPv6 address.
 *
 * @param ip The IP address to validate.
 *
 * @return True if the IP address is syntactically correct.
 */
gboolean purple_ipv6_address_is_valid(const char *ip);

/**
 * This function extracts a list of URIs from the a "text/uri-list"

 * The returned string must be freed by the caller.
 *
 * @param str A valid UTF-8 string.
 *
 * @return A newly allocated UTF-8 string without the unprintable characters.
 */
gchar *purple_utf8_strip_unprintables(const gchar *str);

/**
 * Return the UTF-8 version of gai_strerror().  It calls gai_strerror()

 * g_strerror().
 *
 * @param errnum The error code.
 *
 * @return The UTF-8 error message.
 */
const gchar *purple_gai_strerror(gint errnum);

/**
 * Compares two UTF-8 strings case-insensitively.  This comparison is
 * more expensive than a simple g_utf8_collate() comparison because
 * it calls g_utf8_casefold() on each string, which allocates new

 * @return The resulting string.
 */
const char *purple_escape_filename(const char *str);

/**
 * Restore default signal handlers for signals which might reasonably have
 * handlers. This should be called by a fork()'d child process, since child processes
 * inherit the handlers of the parent.
 */
void purple_restore_default_signal_handlers(void);

/**
 * Returns a type 4 (random) UUID
 *
 * @return A UUID, caller is responsible for freeing it
 */
gchar *purple_uuid_random(void);

G_END_DECLS

#endif /* _PURPLE_UTIL_H_ */