Mercurial > pidgin
diff libpurple/util.h @ 32819:2c6510167895 default tip
propagate from branch 'im.pidgin.pidgin.2.x.y' (head 3315c5dfbd0ad16511bdcf865e5b07c02d07df24)
to branch 'im.pidgin.pidgin' (head cbd1eda6bcbf0565ae7766396bb8f6f419cb6a9a)
author | Elliott Sales de Andrade <qulogic@pidgin.im> |
---|---|
date | Sat, 02 Jun 2012 02:30:49 +0000 |
parents | 98520ee78f12 |
children |
line wrap: on
line diff
--- a/libpurple/util.h Sat Jun 02 02:30:13 2012 +0000 +++ b/libpurple/util.h Sat Jun 02 02:30:49 2012 +0000 @@ -36,9 +36,20 @@ * the request. */ typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData; -/** @copydoc _PurpleMenuAction */ + +/** + * 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; -/** @copydoc _PurpleKeyValuePair */ + +/** + * 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" @@ -47,26 +58,8 @@ #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; @@ -74,6 +67,8 @@ }; +G_BEGIN_DECLS + /** * Creates a new PurpleMenuAction. * @@ -96,12 +91,79 @@ 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. - * @since 2.4.0 */ void purple_util_set_current_song(const char *title, const char *artist, const char *album); @@ -115,7 +177,6 @@ * @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); @@ -127,15 +188,11 @@ /** * 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); @@ -429,8 +486,6 @@ * 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); @@ -531,7 +586,6 @@ * this string when finished with it. * * @see purple_unescape_html() - * @since 2.7.0 */ char *purple_unescape_text(const char *text); @@ -624,8 +678,6 @@ * @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); @@ -826,7 +878,6 @@ * * @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); @@ -838,7 +889,6 @@ * * @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); @@ -860,8 +910,6 @@ * @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); @@ -1041,7 +1089,7 @@ * * @return The string in units form. This must be freed. */ -char *purple_str_size_to_units(size_t size); +char *purple_str_size_to_units(goffset size); /** * Converts seconds into a human-readable form. @@ -1117,75 +1165,17 @@ * 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, \ +#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 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 url The URL. * @param full TRUE if this is the full URL, or FALSE if it's a @@ -1199,9 +1189,8 @@ * @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( +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, @@ -1247,14 +1236,15 @@ gboolean purple_email_is_valid(const char *address); /** - * Checks if the given IP address is a syntactically valid IPv4 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. - * @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); @@ -1264,7 +1254,6 @@ * @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); @@ -1274,7 +1263,6 @@ * @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); @@ -1342,7 +1330,6 @@ * @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); @@ -1354,9 +1341,8 @@ * @param errnum The error code. * * @return The UTF-8 error message. - * @since 2.4.0 */ -G_CONST_RETURN gchar *purple_gai_strerror(gint errnum); +const gchar *purple_gai_strerror(gint errnum); /** * Compares two UTF-8 strings case-insensitively. This comparison is @@ -1450,16 +1436,6 @@ 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. @@ -1478,12 +1454,9 @@ * 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 +G_END_DECLS #endif /* _PURPLE_UTIL_H_ */