--- a/libpurple/util.h Mon Aug 22 22:46:08 2011 +0000
+++ b/libpurple/util.h Fri Dec 23 08:21:58 2011 +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"
@@ -51,22 +62,8 @@
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;
@@ -96,12 +93,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 +179,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 +190,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 +488,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 +588,6 @@
* this string when finished with it.
*
* @see purple_unescape_html()
- * @since 2.7.0
*/
char *purple_unescape_text(const char *text);
@@ -624,8 +680,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 +880,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 +891,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 +912,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 +1091,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,53 +1167,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(NULL, 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 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
@@ -1177,9 +1191,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(
+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,
@@ -1225,14 +1238,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);
@@ -1242,7 +1256,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);
@@ -1252,7 +1265,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);
@@ -1320,7 +1332,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);
@@ -1332,9 +1343,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
@@ -1446,7 +1456,6 @@
* Returns a type 4 (random) UUID
*
* @return A UUID, caller is responsible for freeing it
- * @since 2.7.0
*/
gchar *purple_uuid_random(void);
