Mercurial > pidgin.yaz
comparison libpurple/util.h @ 32692:0f94ec89f0bc
merged from im.pidgin.pidgin
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Mon, 26 Sep 2011 14:57:21 +0900 |
parents | 9aee8493db7f 4c64383f05cc |
children | 4a34689eeb33 |
comparison
equal
deleted
inserted
replaced
32438:55e678325bda | 32692:0f94ec89f0bc |
---|---|
34 /** | 34 /** |
35 * An opaque structure representing a URL request. Can be used to cancel | 35 * An opaque structure representing a URL request. Can be used to cancel |
36 * the request. | 36 * the request. |
37 */ | 37 */ |
38 typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData; | 38 typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData; |
39 /** @copydoc _PurpleMenuAction */ | 39 |
40 /** | |
41 * A generic structure that contains information about an "action." One | |
42 * place this is is used is by PRPLs to tell the core the list of available | |
43 * right-click actions for a buddy list row. | |
44 */ | |
40 typedef struct _PurpleMenuAction PurpleMenuAction; | 45 typedef struct _PurpleMenuAction PurpleMenuAction; |
41 /** @copydoc _PurpleKeyValuePair */ | 46 |
47 /** | |
48 * A key-value pair. | |
49 * | |
50 * This is used by, among other things, purple_gtk_combo* functions to pass in a | |
51 * list of key-value pairs so it can display a user-friendly value. | |
52 */ | |
42 typedef struct _PurpleKeyValuePair PurpleKeyValuePair; | 53 typedef struct _PurpleKeyValuePair PurpleKeyValuePair; |
43 | 54 |
44 #include "account.h" | 55 #include "account.h" |
45 #include "signals.h" | 56 #include "signals.h" |
46 #include "xmlnode.h" | 57 #include "xmlnode.h" |
49 | 60 |
50 #ifdef __cplusplus | 61 #ifdef __cplusplus |
51 extern "C" { | 62 extern "C" { |
52 #endif | 63 #endif |
53 | 64 |
54 struct _PurpleMenuAction | |
55 { | |
56 char *label; | |
57 PurpleCallback callback; | |
58 gpointer data; | |
59 GList *children; | |
60 }; | |
61 | |
62 typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len); | 65 typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len); |
63 | 66 |
64 /** | |
65 * A key-value pair. | |
66 * | |
67 * This is used by, among other things, purple_gtk_combo* functions to pass in a | |
68 * list of key-value pairs so it can display a user-friendly value. | |
69 */ | |
70 struct _PurpleKeyValuePair | 67 struct _PurpleKeyValuePair |
71 { | 68 { |
72 gchar *key; | 69 gchar *key; |
73 void *value; | 70 void *value; |
74 | 71 |
94 * @param act The PurpleMenuAction to free. | 91 * @param act The PurpleMenuAction to free. |
95 */ | 92 */ |
96 void purple_menu_action_free(PurpleMenuAction *act); | 93 void purple_menu_action_free(PurpleMenuAction *act); |
97 | 94 |
98 /** | 95 /** |
96 * Returns the label of the PurpleMenuAction. | |
97 * | |
98 * @param act The PurpleMenuAction. | |
99 * | |
100 * @return The label string. | |
101 */ | |
102 char * purple_menu_action_get_label(const PurpleMenuAction *act); | |
103 | |
104 /** | |
105 * Returns the callback of the PurpleMenuAction. | |
106 * | |
107 * @param act The PurpleMenuAction. | |
108 * | |
109 * @return The callback function. | |
110 */ | |
111 PurpleCallback purple_menu_action_get_callback(const PurpleMenuAction *act); | |
112 | |
113 /** | |
114 * Returns the data stored in the PurpleMenuAction. | |
115 * | |
116 * @param act The PurpleMenuAction. | |
117 * | |
118 * @return The data. | |
119 */ | |
120 gpointer purple_menu_action_get_data(const PurpleMenuAction *act); | |
121 | |
122 /** | |
123 * Returns the children of the PurpleMenuAction. | |
124 * | |
125 * @param act The PurpleMenuAction. | |
126 * | |
127 * @return The GList of children. | |
128 */ | |
129 GList* purple_menu_action_get_children(const PurpleMenuAction *act); | |
130 | |
131 /** | |
132 * Set the label to the PurpleMenuAction. | |
133 * | |
134 * @param act The menu action. | |
135 * @param label The label for the menu action. | |
136 */ | |
137 void purple_menu_action_set_label(PurpleMenuAction *act, char *label); | |
138 | |
139 /** | |
140 * Set the callback that will be used by the PurpleMenuAction. | |
141 * | |
142 * @param act The menu action. | |
143 * @param callback The callback. | |
144 */ | |
145 void purple_menu_action_set_callback(PurpleMenuAction *act, PurpleCallback callback); | |
146 | |
147 /** | |
148 * Set the label to the PurpleMenuAction. | |
149 * | |
150 * @param act The menu action. | |
151 * @param data The data used by this PurpleMenuAction | |
152 */ | |
153 void purple_menu_action_set_data(PurpleMenuAction *act, gpointer data); | |
154 | |
155 /** | |
156 * Set the children of the PurpleMenuAction. | |
157 * | |
158 * @param act The menu action. | |
159 * @param children The PurpleMenuAtion children | |
160 */ | |
161 void purple_menu_action_set_children(PurpleMenuAction *act, GList *children); | |
162 | |
163 /** | |
99 * Set the appropriate presence values for the currently playing song. | 164 * Set the appropriate presence values for the currently playing song. |
100 * | 165 * |
101 * @param title The title of the song, @c NULL to unset the value. | 166 * @param title The title of the song, @c NULL to unset the value. |
102 * @param artist The artist of the song, can be @c NULL. | 167 * @param artist The artist of the song, can be @c NULL. |
103 * @param album The album of the song, can be @c NULL. | 168 * @param album The album of the song, can be @c NULL. |
104 * @since 2.4.0 | |
105 */ | 169 */ |
106 void purple_util_set_current_song(const char *title, const char *artist, | 170 void purple_util_set_current_song(const char *title, const char *artist, |
107 const char *album); | 171 const char *album); |
108 | 172 |
109 /** | 173 /** |
113 * @param artist The artist of the song, can be @c NULL. | 177 * @param artist The artist of the song, can be @c NULL. |
114 * @param album The album of the song, can be @c NULL. | 178 * @param album The album of the song, can be @c NULL. |
115 * @param unused Currently unused, must be @c NULL. | 179 * @param unused Currently unused, must be @c NULL. |
116 * | 180 * |
117 * @return The formatted string. The caller must g_free the returned string. | 181 * @return The formatted string. The caller must g_free the returned string. |
118 * @since 2.4.0 | |
119 */ | 182 */ |
120 char * purple_util_format_song_info(const char *title, const char *artist, | 183 char * purple_util_format_song_info(const char *title, const char *artist, |
121 const char *album, gpointer unused); | 184 const char *album, gpointer unused); |
122 | 185 |
123 /**************************************************************************/ | 186 /**************************************************************************/ |
125 /**************************************************************************/ | 188 /**************************************************************************/ |
126 /*@{*/ | 189 /*@{*/ |
127 | 190 |
128 /** | 191 /** |
129 * Initializes the utility subsystem. | 192 * Initializes the utility subsystem. |
130 * | |
131 * @since 2.3.0 | |
132 */ | 193 */ |
133 void purple_util_init(void); | 194 void purple_util_init(void); |
134 | 195 |
135 /** | 196 /** |
136 * Uninitializes the util subsystem. | 197 * Uninitializes the util subsystem. |
137 * | |
138 * @since 2.3.0 | |
139 */ | 198 */ |
140 void purple_util_uninit(void); | 199 void purple_util_uninit(void); |
141 | 200 |
142 /*@}*/ | 201 /*@}*/ |
143 | 202 |
427 * replaced with < | 486 * replaced with < |
428 * | 487 * |
429 * This is exactly the same as g_markup_escape_text(), except that it | 488 * This is exactly the same as g_markup_escape_text(), except that it |
430 * does not change ' to ' because ' is not a valid HTML 4 entity, | 489 * does not change ' to ' because ' is not a valid HTML 4 entity, |
431 * and is displayed literally in IE7. | 490 * and is displayed literally in IE7. |
432 * | |
433 * @since 2.6.0 | |
434 */ | 491 */ |
435 gchar *purple_markup_escape_text(const gchar *text, gssize length); | 492 gchar *purple_markup_escape_text(const gchar *text, gssize length); |
436 | 493 |
437 /** | 494 /** |
438 * Finds an HTML tag matching the given name. | 495 * Finds an HTML tag matching the given name. |
529 * | 586 * |
530 * @return The text with HTML entities literalized. You must g_free | 587 * @return The text with HTML entities literalized. You must g_free |
531 * this string when finished with it. | 588 * this string when finished with it. |
532 * | 589 * |
533 * @see purple_unescape_html() | 590 * @see purple_unescape_html() |
534 * @since 2.7.0 | |
535 */ | 591 */ |
536 char *purple_unescape_text(const char *text); | 592 char *purple_unescape_text(const char *text); |
537 | 593 |
538 /** | 594 /** |
539 * Unescapes HTML entities to their literal characters and converts | 595 * Unescapes HTML entities to their literal characters and converts |
622 * Check if the given HTML contains RTL text. | 678 * Check if the given HTML contains RTL text. |
623 * | 679 * |
624 * @param html The HTML text. | 680 * @param html The HTML text. |
625 * | 681 * |
626 * @return TRUE if the text contains RTL text, FALSE otherwise. | 682 * @return TRUE if the text contains RTL text, FALSE otherwise. |
627 * | |
628 * @since 2.6.0 | |
629 */ | 683 */ |
630 gboolean purple_markup_is_rtl(const char *html); | 684 gboolean purple_markup_is_rtl(const char *html); |
631 | 685 |
632 /*@}*/ | 686 /*@}*/ |
633 | 687 |
824 * | 878 * |
825 * @param fd The socket file descriptor. | 879 * @param fd The socket file descriptor. |
826 * | 880 * |
827 * @return The address family of the socket (AF_INET, AF_INET6, etc) or -1 | 881 * @return The address family of the socket (AF_INET, AF_INET6, etc) or -1 |
828 * on error. | 882 * on error. |
829 * @since 2.7.0 | |
830 */ | 883 */ |
831 int purple_socket_get_family(int fd); | 884 int purple_socket_get_family(int fd); |
832 | 885 |
833 /** | 886 /** |
834 * Returns TRUE if a socket is capable of speaking IPv4. | 887 * Returns TRUE if a socket is capable of speaking IPv4. |
836 * This is the case for IPv4 sockets and, on some systems, IPv6 sockets | 889 * This is the case for IPv4 sockets and, on some systems, IPv6 sockets |
837 * (due to the IPv4-mapped address functionality). | 890 * (due to the IPv4-mapped address functionality). |
838 * | 891 * |
839 * @param fd The socket file descriptor | 892 * @param fd The socket file descriptor |
840 * @return TRUE if a socket can speak IPv4. | 893 * @return TRUE if a socket can speak IPv4. |
841 * @since 2.7.0 | |
842 */ | 894 */ |
843 gboolean purple_socket_speaks_ipv4(int fd); | 895 gboolean purple_socket_speaks_ipv4(int fd); |
844 | 896 |
845 /*@}*/ | 897 /*@}*/ |
846 | 898 |
858 * | 910 * |
859 * @param left A string | 911 * @param left A string |
860 * @param right A string to compare with left | 912 * @param right A string to compare with left |
861 * | 913 * |
862 * @return @c TRUE if the strings are the same, else @c FALSE. | 914 * @return @c TRUE if the strings are the same, else @c FALSE. |
863 * | |
864 * @since 2.6.0 | |
865 */ | 915 */ |
866 gboolean purple_strequal(const gchar *left, const gchar *right); | 916 gboolean purple_strequal(const gchar *left, const gchar *right); |
867 | 917 |
868 /** | 918 /** |
869 * Normalizes a string, so that it is suitable for comparison. | 919 * Normalizes a string, so that it is suitable for comparison. |
1115 * @param url The URL. | 1165 * @param url The URL. |
1116 * @param full TRUE if this is the full URL, or FALSE if it's a | 1166 * @param full TRUE if this is the full URL, or FALSE if it's a |
1117 * partial URL. | 1167 * partial URL. |
1118 * @param user_agent The user agent field to use, or NULL. | 1168 * @param user_agent The user agent field to use, or NULL. |
1119 * @param http11 TRUE if HTTP/1.1 should be used to download the file. | 1169 * @param http11 TRUE if HTTP/1.1 should be used to download the file. |
1120 * @param cb The callback function. | |
1121 * @param data The user data to pass to the callback function. | |
1122 */ | |
1123 #define purple_util_fetch_url(url, full, user_agent, http11, cb, data) \ | |
1124 purple_util_fetch_url_request(url, full, user_agent, http11, NULL, \ | |
1125 FALSE, cb, data); | |
1126 | |
1127 /** | |
1128 * Fetches the data from a URL, and passes it to a callback function. | |
1129 * | |
1130 * @param url The URL. | |
1131 * @param full TRUE if this is the full URL, or FALSE if it's a | |
1132 * partial URL. | |
1133 * @param user_agent The user agent field to use, or NULL. | |
1134 * @param http11 TRUE if HTTP/1.1 should be used to download the file. | |
1135 * @param max_len The maximum number of bytes to retrieve (-1 for unlimited) | 1170 * @param max_len The maximum number of bytes to retrieve (-1 for unlimited) |
1136 * @param cb The callback function. | 1171 * @param cb The callback function. |
1137 * @param data The user data to pass to the callback function. | 1172 * @param data The user data to pass to the callback function. |
1138 * @deprecated In 3.0.0, we'll rename this to "purple_util_fetch_url" and get rid of the old one | 1173 */ |
1139 */ | 1174 #define purple_util_fetch_url(url, full, user_agent, http11, max_len, cb, data) \ |
1140 #define purple_util_fetch_url_len(url, full, user_agent, http11, max_len, cb, data) \ | 1175 purple_util_fetch_url_request(NULL, url, full, user_agent, http11, NULL, \ |
1141 purple_util_fetch_url_request_len(NULL, url, full, user_agent, http11, NULL, \ | |
1142 FALSE, max_len, cb, data); | 1176 FALSE, max_len, cb, data); |
1143 | |
1144 /** | |
1145 * Fetches the data from a URL, and passes it to a callback function. | |
1146 * | |
1147 * @param url The URL. | |
1148 * @param full TRUE if this is the full URL, or FALSE if it's a | |
1149 * partial URL. | |
1150 * @param user_agent The user agent field to use, or NULL. | |
1151 * @param http11 TRUE if HTTP/1.1 should be used to download the file. | |
1152 * @param request A HTTP request to send to the server instead of the | |
1153 * standard GET | |
1154 * @param include_headers | |
1155 * If TRUE, include the HTTP headers in the response. | |
1156 * @param callback The callback function. | |
1157 * @param data The user data to pass to the callback function. | |
1158 */ | |
1159 PurpleUtilFetchUrlData *purple_util_fetch_url_request(const gchar *url, | |
1160 gboolean full, const gchar *user_agent, gboolean http11, | |
1161 const gchar *request, gboolean include_headers, | |
1162 PurpleUtilFetchUrlCallback callback, gpointer data); | |
1163 | 1177 |
1164 /** | 1178 /** |
1165 * Fetches the data from a URL, and passes it to a callback function. | 1179 * Fetches the data from a URL, and passes it to a callback function. |
1166 * | 1180 * |
1167 * @param account The account for which the request is needed, or NULL. | 1181 * @param account The account for which the request is needed, or NULL. |
1175 * @param include_headers | 1189 * @param include_headers |
1176 * If TRUE, include the HTTP headers in the response. | 1190 * If TRUE, include the HTTP headers in the response. |
1177 * @param max_len The maximum number of bytes to retrieve (-1 for unlimited) | 1191 * @param max_len The maximum number of bytes to retrieve (-1 for unlimited) |
1178 * @param callback The callback function. | 1192 * @param callback The callback function. |
1179 * @param data The user data to pass to the callback function. | 1193 * @param data The user data to pass to the callback function. |
1180 * @deprecated In 3.0.0, we'll rename this to "purple_util_fetch_url_request" and get rid of the old one | 1194 */ |
1181 */ | 1195 PurpleUtilFetchUrlData *purple_util_fetch_url_request( |
1182 PurpleUtilFetchUrlData *purple_util_fetch_url_request_len( | |
1183 PurpleAccount *account, const gchar *url, | 1196 PurpleAccount *account, const gchar *url, |
1184 gboolean full, const gchar *user_agent, gboolean http11, | 1197 gboolean full, const gchar *user_agent, gboolean http11, |
1185 const gchar *request, gboolean include_headers, gssize max_len, | 1198 const gchar *request, gboolean include_headers, gssize max_len, |
1186 PurpleUtilFetchUrlCallback callback, gpointer data); | 1199 PurpleUtilFetchUrlCallback callback, gpointer data); |
1187 | 1200 |
1223 * @return True if the email address is syntactically correct. | 1236 * @return True if the email address is syntactically correct. |
1224 */ | 1237 */ |
1225 gboolean purple_email_is_valid(const char *address); | 1238 gboolean purple_email_is_valid(const char *address); |
1226 | 1239 |
1227 /** | 1240 /** |
1241 * Checks if the given IP address is a syntactically valid IPv4 or | |
1242 * IPv6 address. | |
1243 * If you specifically want to check for an IPv4 address use | |
1244 * purple_ipv4_address_is_valid(), or for an IPv6 address use | |
1245 * purple_ipv6_address_is_valid(). | |
1246 * | |
1247 * @param ip The IP address to validate. | |
1248 * | |
1249 * @return True if the IP address is syntactically correct. | |
1250 */ | |
1251 gboolean purple_ip_address_is_valid(const char *ip); | |
1252 | |
1253 /** | |
1228 * Checks if the given IP address is a syntactically valid IPv4 address. | 1254 * Checks if the given IP address is a syntactically valid IPv4 address. |
1229 * | 1255 * |
1230 * @param ip The IP address to validate. | 1256 * @param ip The IP address to validate. |
1231 * | 1257 * |
1232 * @return True if the IP address is syntactically correct. | 1258 * @return True if the IP address is syntactically correct. |
1233 * @deprecated This function will be replaced with one that validates | 1259 */ |
1234 * as either IPv4 or IPv6 in 3.0.0. If you don't want this, | 1260 gboolean purple_ipv4_address_is_valid(const char *ip); |
1235 * behavior, use one of the more specific functions. | 1261 |
1236 */ | 1262 /** |
1237 gboolean purple_ip_address_is_valid(const char *ip); | 1263 * Checks if the given IP address is a syntactically valid IPv6 address. |
1238 | |
1239 /** | |
1240 * Checks if the given IP address is a syntactically valid IPv4 address. | |
1241 * | 1264 * |
1242 * @param ip The IP address to validate. | 1265 * @param ip The IP address to validate. |
1243 * | 1266 * |
1244 * @return True if the IP address is syntactically correct. | 1267 * @return True if the IP address is syntactically correct. |
1245 * @since 2.6.0 | |
1246 */ | |
1247 gboolean purple_ipv4_address_is_valid(const char *ip); | |
1248 | |
1249 /** | |
1250 * Checks if the given IP address is a syntactically valid IPv6 address. | |
1251 * | |
1252 * @param ip The IP address to validate. | |
1253 * | |
1254 * @return True if the IP address is syntactically correct. | |
1255 * @since 2.6.0 | |
1256 */ | 1268 */ |
1257 gboolean purple_ipv6_address_is_valid(const char *ip); | 1269 gboolean purple_ipv6_address_is_valid(const char *ip); |
1258 | 1270 |
1259 /** | 1271 /** |
1260 * This function extracts a list of URIs from the a "text/uri-list" | 1272 * This function extracts a list of URIs from the a "text/uri-list" |
1318 * The returned string must be freed by the caller. | 1330 * The returned string must be freed by the caller. |
1319 * | 1331 * |
1320 * @param str A valid UTF-8 string. | 1332 * @param str A valid UTF-8 string. |
1321 * | 1333 * |
1322 * @return A newly allocated UTF-8 string without the unprintable characters. | 1334 * @return A newly allocated UTF-8 string without the unprintable characters. |
1323 * @since 2.6.0 | |
1324 */ | 1335 */ |
1325 gchar *purple_utf8_strip_unprintables(const gchar *str); | 1336 gchar *purple_utf8_strip_unprintables(const gchar *str); |
1326 | 1337 |
1327 /** | 1338 /** |
1328 * Return the UTF-8 version of gai_strerror(). It calls gai_strerror() | 1339 * Return the UTF-8 version of gai_strerror(). It calls gai_strerror() |
1330 * g_strerror(). | 1341 * g_strerror(). |
1331 * | 1342 * |
1332 * @param errnum The error code. | 1343 * @param errnum The error code. |
1333 * | 1344 * |
1334 * @return The UTF-8 error message. | 1345 * @return The UTF-8 error message. |
1335 * @since 2.4.0 | |
1336 */ | 1346 */ |
1337 G_CONST_RETURN gchar *purple_gai_strerror(gint errnum); | 1347 G_CONST_RETURN gchar *purple_gai_strerror(gint errnum); |
1338 | 1348 |
1339 /** | 1349 /** |
1340 * Compares two UTF-8 strings case-insensitively. This comparison is | 1350 * Compares two UTF-8 strings case-insensitively. This comparison is |
1444 | 1454 |
1445 /** | 1455 /** |
1446 * Returns a type 4 (random) UUID | 1456 * Returns a type 4 (random) UUID |
1447 * | 1457 * |
1448 * @return A UUID, caller is responsible for freeing it | 1458 * @return A UUID, caller is responsible for freeing it |
1449 * @since 2.7.0 | |
1450 */ | 1459 */ |
1451 gchar *purple_uuid_random(void); | 1460 gchar *purple_uuid_random(void); |
1452 | 1461 |
1453 #ifdef __cplusplus | 1462 #ifdef __cplusplus |
1454 } | 1463 } |