Mercurial > pidgin.yaz
annotate libgaim/util.h @ 14694:8538993dbb00
[gaim-migrate @ 17446]
Patch #1571853 from Richard Nelson (wabz):
"This patch removes the contact and all buddies when
removing a contact, rather than just removing it from
the blist (and having all the buddies show up next time
gaim-text is opened)"
committer: Tailor Script <tailor@pidgin.im>
author | Sadrul Habib Chowdhury <imadil@gmail.com> |
---|---|
date | Sun, 08 Oct 2006 04:21:20 +0000 |
parents | e0a93e6fa98b |
children | b81e4e44b509 |
rev | line source |
---|---|
14192 | 1 /** |
2 * @file util.h Utility Functions | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 * | |
25 * @todo Rename the functions so that they live somewhere in the gaim | |
26 * namespace. | |
27 */ | |
28 #ifndef _GAIM_UTIL_H_ | |
29 #define _GAIM_UTIL_H_ | |
30 | |
31 #include <stdio.h> | |
32 | |
33 #include "account.h" | |
34 #include "xmlnode.h" | |
35 | |
36 #ifdef __cplusplus | |
37 extern "C" { | |
38 #endif | |
39 | |
14354 | 40 typedef struct _GaimUtilFetchUrlData GaimUtilFetchUrlData; |
41 | |
14192 | 42 typedef struct _GaimMenuAction |
43 { | |
44 char *label; | |
45 GaimCallback callback; | |
46 gpointer data; | |
47 GList *children; | |
48 } GaimMenuAction; | |
49 | |
50 typedef char *(*GaimInfoFieldFormatCallback)(const char *field, size_t len); | |
51 | |
52 /** | |
53 * A key-value pair. | |
54 * | |
55 * This is used by, among other things, gaim_gtk_combo* functions to pass in a | |
56 * list of key-value pairs so it can display a user-friendly value. | |
57 */ | |
58 typedef struct _GaimKeyValuePair | |
59 { | |
60 gchar *key; | |
61 void *value; | |
62 | |
63 } GaimKeyValuePair; | |
64 | |
65 /** | |
66 * Creates a new GaimMenuAction. | |
67 * | |
68 * @param label The text label to display for this action. | |
69 * @param callback The function to be called when the action is used on | |
70 * the selected item. | |
71 * @param data Additional data to be passed to the callback. | |
72 * @param children A GList of GaimMenuActions to be added as a submenu | |
73 * of the action. | |
74 * @return The GaimMenuAction. | |
75 */ | |
76 GaimMenuAction *gaim_menu_action_new(const char *label, GaimCallback callback, | |
77 gpointer data, GList *children); | |
78 | |
79 /** | |
80 * Frees a GaimMenuAction | |
81 * | |
82 * @param act The GaimMenuAction to free. | |
83 */ | |
84 void gaim_menu_action_free(GaimMenuAction *act); | |
85 | |
86 /**************************************************************************/ | |
87 /** @name Base16 Functions */ | |
88 /**************************************************************************/ | |
89 /*@{*/ | |
90 | |
91 /** | |
92 * Converts a chunk of binary data to its base-16 equivalent. | |
93 * | |
94 * @param data The data to convert. | |
95 * @param len The length of the data. | |
96 * | |
97 * @return The base-16 string in the ASCII encoding. Must be | |
98 * g_free'd when no longer needed. | |
99 * | |
100 * @see gaim_base16_decode() | |
101 */ | |
102 gchar *gaim_base16_encode(const guchar *data, gsize len); | |
103 | |
104 /** | |
105 * Converts an ASCII string of base-16 encoded data to | |
106 * the binary equivalent. | |
107 * | |
108 * @param str The base-16 string to convert to raw data. | |
109 * @param ret_len The length of the returned data. You can | |
110 * pass in NULL if you're sure that you know | |
111 * the length of the decoded data, or if you | |
112 * know you'll be able to use strlen to | |
113 * determine the length, etc. | |
114 * | |
115 * @return The raw data. Must be g_free'd when no longer needed. | |
116 * | |
117 * @see gaim_base16_encode() | |
118 */ | |
119 guchar *gaim_base16_decode(const char *str, gsize *ret_len); | |
120 | |
121 /*@}*/ | |
122 | |
123 /**************************************************************************/ | |
124 /** @name Base64 Functions */ | |
125 /**************************************************************************/ | |
126 /*@{*/ | |
127 | |
128 /** | |
129 * Converts a chunk of binary data to its base-64 equivalent. | |
130 * | |
131 * @param data The data to convert. | |
132 * @param len The length of the data. | |
133 * | |
134 * @return The base-64 string in the ASCII encoding. Must be | |
135 * g_free'd when no longer needed. | |
136 * | |
137 * @see gaim_base64_decode() | |
138 */ | |
139 gchar *gaim_base64_encode(const guchar *data, gsize len); | |
140 | |
141 /** | |
142 * Converts an ASCII string of base-64 encoded data to | |
143 * the binary equivalent. | |
144 * | |
145 * @param str The base-64 string to convert to raw data. | |
146 * @param ret_len The length of the returned data. You can | |
147 * pass in NULL if you're sure that you know | |
148 * the length of the decoded data, or if you | |
149 * know you'll be able to use strlen to | |
150 * determine the length, etc. | |
151 * | |
152 * @return The raw data. Must be g_free'd when no longer needed. | |
153 * | |
154 * @see gaim_base64_encode() | |
155 */ | |
156 guchar *gaim_base64_decode(const char *str, gsize *ret_len); | |
157 | |
158 /*@}*/ | |
159 | |
160 /**************************************************************************/ | |
161 /** @name Quoted Printable Functions */ | |
162 /**************************************************************************/ | |
163 /*@{*/ | |
164 | |
165 /** | |
166 * Converts a quoted printable string back to its readable equivalent. | |
167 * What is a quoted printable string, you ask? It's an encoding used | |
168 * to transmit binary data as ASCII. It's intended purpose is to send | |
169 * e-mails containing non-ASCII characters. Wikipedia has a pretty good | |
170 * explanation. Also see RFC 2045. | |
171 * | |
172 * @param str The quoted printable ASCII string to convert to raw data. | |
173 * @param ret_len The length of the returned data. | |
174 * | |
175 * @return The readable string. Must be g_free'd when no longer needed. | |
176 */ | |
177 guchar *gaim_quotedp_decode(const char *str, gsize *ret_len); | |
178 | |
179 /*@}*/ | |
180 | |
181 /**************************************************************************/ | |
182 /** @name MIME Functions */ | |
183 /**************************************************************************/ | |
184 /*@{*/ | |
185 | |
186 /** | |
187 * Converts a MIME header field string back to its readable equivalent | |
188 * according to RFC 2047. Basically, a header is plain ASCII and can | |
189 * contain any number of sections called "encoded-words." The format | |
190 * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= | |
191 * =? designates the beginning of the encoded-word | |
192 * ?= designates the end of the encoded-word | |
193 * | |
194 * An encoded word is segmented into three pieces by the use of a | |
195 * question mark. The first piece is the character set, the second | |
196 * piece is the encoding, and the third piece is the encoded text. | |
197 * | |
198 * @param str The ASCII string, possibly containing any number of | |
199 * encoded-word sections. | |
200 * | |
201 * @return The string, with any encoded-word sections decoded and | |
202 * converted to UTF-8. Must be g_free'd when no longer | |
203 * needed. | |
204 */ | |
205 char *gaim_mime_decode_field(const char *str); | |
206 | |
207 /*@}*/ | |
208 | |
209 | |
210 /**************************************************************************/ | |
211 /** @name Date/Time Functions */ | |
212 /**************************************************************************/ | |
213 /*@{*/ | |
214 | |
215 /** | |
216 * Formats a time into the specified format. | |
217 * | |
218 * This is essentially strftime(), but it has a static buffer | |
219 * and handles the UTF-8 conversion for the caller. | |
220 * | |
221 * This function also provides the GNU %z formatter if the underlying C | |
222 * library doesn't. However, the format string parser is very naive, which | |
223 * means that conversions specifiers to %z cannot be guaranteed. The GNU | |
224 * strftime(3) man page describes %z as: 'The time-zone as hour offset from | |
225 * GMT. Required to emit RFC822-conformant dates | |
226 * (using "%a, %d %b %Y %H:%M:%S %z"). (GNU)' | |
227 * | |
228 * On Windows, this function also converts the results for %Z from a timezone | |
229 * name (as returned by the system strftime() %Z format string) to a timezone | |
230 * abbreviation (as is the case on Unix). As with %z, conversion specifiers | |
231 * should not be used. | |
232 * | |
233 * @param format The format string, in UTF-8 | |
234 * @param tm The time to format, or @c NULL to use the current local time | |
235 * | |
236 * @return The formatted time, in UTF-8. | |
237 * | |
238 * @note @a format is required to be in UTF-8. This differs from strftime(), | |
239 * where the format is provided in the locale charset. | |
240 */ | |
241 const char *gaim_utf8_strftime(const char *format, const struct tm *tm); | |
242 | |
243 /** | |
244 * Formats a time into the user's preferred short date format. | |
245 * | |
246 * The returned string is stored in a static buffer, so the result | |
247 * should be g_strdup()'d if it's going to be kept. | |
248 * | |
249 * @param tm The time to format, or @c NULL to use the current local time | |
250 * | |
251 * @return The date, formatted as per the user's settings. | |
252 */ | |
253 const char *gaim_date_format_short(const struct tm *tm); | |
254 | |
255 /** | |
256 * Formats a time into the user's preferred short date plus time format. | |
257 * | |
258 * The returned string is stored in a static buffer, so the result | |
259 * should be g_strdup()'d if it's going to be kept. | |
260 * | |
261 * @param tm The time to format, or @c NULL to use the current local time | |
262 * | |
263 * @return The timestamp, formatted as per the user's settings. | |
264 */ | |
265 const char *gaim_date_format_long(const struct tm *tm); | |
266 | |
267 /** | |
268 * Formats a time into the user's preferred full date and time format. | |
269 * | |
270 * The returned string is stored in a static buffer, so the result | |
271 * should be g_strdup()'d if it's going to be kept. | |
272 * | |
273 * @param tm The time to format, or @c NULL to use the current local time | |
274 * | |
275 * @return The date and time, formatted as per the user's settings. | |
276 */ | |
277 const char *gaim_date_format_full(const struct tm *tm); | |
278 | |
279 /** | |
280 * Formats a time into the user's preferred time format. | |
281 * | |
282 * The returned string is stored in a static buffer, so the result | |
283 * should be g_strdup()'d if it's going to be kept. | |
284 * | |
285 * @param tm The time to format, or @c NULL to use the current local time | |
286 * | |
287 * @return The time, formatted as per the user's settings. | |
288 */ | |
289 const char *gaim_time_format(const struct tm *tm); | |
290 | |
291 /** | |
292 * Builds a time_t from the supplied information. | |
293 * | |
294 * @param year The year. | |
295 * @param month The month. | |
296 * @param day The day. | |
297 * @param hour The hour. | |
298 * @param min The minute. | |
299 * @param sec The second. | |
300 * | |
301 * @return A time_t. | |
302 */ | |
303 time_t gaim_time_build(int year, int month, int day, int hour, | |
304 int min, int sec); | |
305 | |
306 /** Used by gaim_str_to_time to indicate no timezone offset was | |
307 * specified in the timestamp string. */ | |
308 #define GAIM_NO_TZ_OFF -500000 | |
309 | |
310 /** | |
311 * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns | |
312 * a time_t. | |
313 * | |
314 * @param timestamp The timestamp | |
315 * @param utc Assume UTC if no timezone specified | |
316 * @param tm If not @c NULL, the caller can get a copy of the | |
317 * struct tm used to calculate the time_t return value. | |
318 * @param tz_off If not @c NULL, the caller can get a copy of the | |
319 * timezone offset (from UTC) used to calculate the time_t | |
320 * return value. Note: Zero is a valid offset. As such, | |
321 * the value of the macro @c GAIM_NO_TZ_OFF indicates no | |
322 * offset was specified (which means that the local | |
323 * timezone was used in the calculation). | |
324 * @param rest If not @c NULL, the caller can get a pointer to the | |
325 * part of @a timestamp left over after parsing is | |
326 * completed, if it's not the end of @a timestamp. | |
327 * | |
328 * @return A time_t. | |
329 */ | |
330 time_t gaim_str_to_time(const char *timestamp, gboolean utc, | |
331 struct tm *tm, long *tz_off, const char **rest); | |
332 | |
333 /*@}*/ | |
334 | |
335 | |
336 /**************************************************************************/ | |
337 /** @name Markup Functions */ | |
338 /**************************************************************************/ | |
339 /*@{*/ | |
340 | |
341 /** | |
342 * Finds an HTML tag matching the given name. | |
343 * | |
344 * This locates an HTML tag's start and end, and stores its attributes | |
345 * in a GData hash table. The names of the attributes are lower-cased | |
346 * in the hash table, and the name of the tag is case insensitive. | |
347 * | |
348 * @param needle The name of the tag | |
349 * @param haystack The null-delimited string to search in | |
350 * @param start A pointer to the start of the tag if found | |
351 * @param end A pointer to the end of the tag if found | |
352 * @param attributes The attributes, if the tag was found. This should | |
353 * be freed with g_datalist_clear(). | |
354 * @return TRUE if the tag was found | |
355 */ | |
356 gboolean gaim_markup_find_tag(const char *needle, const char *haystack, | |
357 const char **start, const char **end, | |
358 GData **attributes); | |
359 | |
360 /** | |
361 * Extracts a field of data from HTML. | |
362 * | |
363 * This is a scary function. See protocols/msn/msn.c and | |
364 * protocols/yahoo/yahoo_profile.c for example usage. | |
365 * | |
366 * @param str The string to parse. | |
367 * @param len The size of str. | |
368 * @param dest The destination GString to append the new | |
369 * field info to. | |
370 * @param start_token The beginning token. | |
371 * @param skip The number of characters to skip after the | |
372 * start token. | |
373 * @param end_token The ending token. | |
374 * @param check_value The value that the last character must meet. | |
375 * @param no_value_token The token indicating no value is given. | |
376 * @param display_name The short descriptive name to display for this token. | |
377 * @param is_link TRUE if this should be a link, or FALSE otherwise. | |
378 * @param link_prefix The prefix for the link. | |
379 * @param format_cb A callback to format the value before adding it. | |
380 * | |
381 * @return TRUE if successful, or FALSE otherwise. | |
382 */ | |
383 gboolean gaim_markup_extract_info_field(const char *str, int len, GString *dest, | |
384 const char *start_token, int skip, | |
385 const char *end_token, char check_value, | |
386 const char *no_value_token, | |
387 const char *display_name, gboolean is_link, | |
388 const char *link_prefix, | |
389 GaimInfoFieldFormatCallback format_cb); | |
390 | |
391 /** | |
392 * Converts HTML markup to XHTML. | |
393 * | |
394 * @param html The HTML markup. | |
395 * @param dest_xhtml The destination XHTML output. | |
396 * @param dest_plain The destination plain-text output. | |
397 */ | |
398 void gaim_markup_html_to_xhtml(const char *html, char **dest_xhtml, | |
399 char **dest_plain); | |
400 | |
401 /** | |
402 * Strips HTML tags from a string. | |
403 * | |
404 * @param str The string to strip HTML from. | |
405 * | |
406 * @return The new string without HTML. This must be freed. | |
407 */ | |
408 char *gaim_markup_strip_html(const char *str); | |
409 | |
410 /** | |
411 * Adds the necessary HTML code to turn URIs into HTML links in a string. | |
412 * | |
413 * @param str The string to linkify. | |
414 * | |
415 * @return The linkified text. | |
416 */ | |
417 char *gaim_markup_linkify(const char *str); | |
418 | |
419 /** | |
420 * Unescapes HTML entities to their literal characters. | |
421 * For example "&" is replaced by '&' and so on. | |
422 * Actually only "&", """, "<" and ">" are currently | |
423 * supported. | |
424 * | |
425 * @param html The string in which to unescape any HTML entities | |
426 * | |
427 * @return the text with HTML entities literalized | |
428 */ | |
429 char *gaim_unescape_html(const char *html); | |
430 | |
431 /** | |
432 * Returns a newly allocated substring of the HTML UTF-8 string "str". | |
433 * The markup is preserved such that the substring will have the same | |
434 * formatting as original string, even though some tags may have been | |
435 * opened before "x", or may close after "y". All open tags are closed | |
436 * at the end of the returned string, in the proper order. | |
437 * | |
438 * Note that x and y are in character offsets, not byte offsets, and | |
439 * are offsets into an unformatted version of str. Because of this, | |
440 * this function may be sensitive to changes in GtkIMHtml and may break | |
441 * when used with other UI's. libgaim users are encouraged to report and | |
442 * work out any problems encountered. | |
443 * | |
444 * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string. | |
445 * @param x The character offset into an unformatted version of str to | |
446 * begin at. | |
447 * @param y The character offset (into an unformatted vesion of str) of | |
448 * one past the last character to include in the slice. | |
449 * | |
450 * @return The HTML slice of string, with all formatting retained. | |
451 */ | |
452 char *gaim_markup_slice(const char *str, guint x, guint y); | |
453 | |
454 /** | |
455 * Returns a newly allocated string containing the name of the tag | |
456 * located at "tag". Tag is expected to point to a '<', and contain | |
457 * a '>' sometime after that. If there is no '>' and the string is | |
458 * not NUL terminated, this function can be expected to segfault. | |
459 * | |
460 * @param tag The string starting a HTML tag. | |
461 * @return A string containing the name of the tag. | |
462 */ | |
463 char *gaim_markup_get_tag_name(const char *tag); | |
464 | |
465 /*@}*/ | |
466 | |
467 | |
468 /**************************************************************************/ | |
469 /** @name Path/Filename Functions */ | |
470 /**************************************************************************/ | |
471 /*@{*/ | |
472 | |
473 /** | |
474 * Returns the user's home directory. | |
475 * | |
476 * @return The user's home directory. | |
477 * | |
478 * @see gaim_user_dir() | |
479 */ | |
480 const gchar *gaim_home_dir(void); | |
481 | |
482 /** | |
483 * Returns the gaim settings directory in the user's home directory. | |
484 * This is usually ~/.gaim | |
485 * | |
486 * @return The gaim settings directory. | |
487 * | |
488 * @see gaim_home_dir() | |
489 */ | |
490 const char *gaim_user_dir(void); | |
491 | |
492 /** | |
493 * Define a custom gaim settings directory, overriding the default (user's home directory/.gaim) | |
494 * @param dir The custom settings directory | |
495 */ | |
496 void gaim_util_set_user_dir(const char *dir); | |
497 | |
498 /** | |
499 * Builds a complete path from the root, making any directories along | |
500 * the path which do not already exist. | |
501 * | |
502 * @param path The path you wish to create. Note that it must start | |
503 * from the root or this function will fail. | |
504 * @param mode Unix-style permissions for this directory. | |
505 * | |
506 * @return 0 for success, nonzero on any error. | |
507 */ | |
508 int gaim_build_dir(const char *path, int mode); | |
509 | |
510 /** | |
511 * Write a string of data to a file of the given name in the Gaim | |
512 * user directory ($HOME/.gaim by default). The data is typically | |
513 * a serialized version of one of Gaim's config files, such as | |
514 * prefs.xml, accounts.xml, etc. And the string is typically | |
515 * obtained using xmlnode_to_formatted_str. However, this function | |
516 * should work fine for saving binary files as well. | |
517 * | |
518 * @param filename The basename of the file to write in the gaim_user_dir. | |
519 * @param data A null-terminated string of data to write. | |
520 * @param size The size of the data to save. If data is | |
521 * null-terminated you can pass in -1. | |
522 * | |
523 * @return TRUE if the file was written successfully. FALSE otherwise. | |
524 */ | |
525 gboolean gaim_util_write_data_to_file(const char *filename, const char *data, | |
526 size_t size); | |
527 | |
528 /** | |
529 * Read the contents of a given file and parse the results into an | |
530 * xmlnode tree structure. This is intended to be used to read | |
531 * Gaim's configuration xml files (prefs.xml, pounces.xml, etc.) | |
532 * | |
533 * @param filename The basename of the file to open in the gaim_user_dir. | |
534 * @param description A very short description of the contents of this | |
535 * file. This is used in error messages shown to the | |
536 * user when the file can not be opened. For example, | |
537 * "preferences," or "buddy pounces." | |
538 * | |
539 * @return An xmlnode tree of the contents of the given file. Or NULL, if | |
540 * the file does not exist or there was an error reading the file. | |
541 */ | |
542 xmlnode *gaim_util_read_xml_from_file(const char *filename, | |
543 const char *description); | |
544 | |
545 /** | |
546 * Creates a temporary file and returns a file pointer to it. | |
547 * | |
548 * This is like mkstemp(), but returns a file pointer and uses a | |
549 * pre-set template. It uses the semantics of tempnam() for the | |
550 * directory to use and allocates the space for the file path. | |
551 * | |
552 * The caller is responsible for closing the file and removing it when | |
553 * done, as well as freeing the space pointed to by @a path with | |
554 * g_free(). | |
555 * | |
556 * @param path The returned path to the temp file. | |
557 * @param binary Text or binary, for platforms where it matters. | |
558 * | |
559 * @return A file pointer to the temporary file, or @c NULL on failure. | |
560 */ | |
561 FILE *gaim_mkstemp(char **path, gboolean binary); | |
562 | |
563 /** | |
564 * Checks if the given program name is valid and executable. | |
565 * | |
566 * @param program The file name of the application. | |
567 * | |
568 * @return TRUE if the program is runable. | |
569 */ | |
570 gboolean gaim_program_is_valid(const char *program); | |
571 | |
572 /** | |
573 * Check if running GNOME. | |
574 * | |
575 * @return TRUE if running GNOME, FALSE otherwise. | |
576 */ | |
577 gboolean gaim_running_gnome(void); | |
578 | |
579 /** | |
580 * Check if running KDE. | |
581 * | |
582 * @return TRUE if running KDE, FALSE otherwise. | |
583 */ | |
584 gboolean gaim_running_kde(void); | |
585 | |
586 /** | |
14646
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
587 * Check if running OS X. |
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
588 * |
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
589 * @return TRUE if running OS X, FALSE otherwise. |
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
590 */ |
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
591 gboolean gaim_running_osx(void); |
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
592 |
e0a93e6fa98b
[gaim-migrate @ 17392]
Evan Schoenberg <evan.s@dreskin.net>
parents:
14354
diff
changeset
|
593 /** |
14192 | 594 * Returns the IP address from a socket file descriptor. |
595 * | |
596 * @param fd The socket file descriptor. | |
597 * | |
598 * @return The IP address, or @c NULL on error. | |
599 */ | |
600 char *gaim_fd_get_ip(int fd); | |
601 | |
602 /*@}*/ | |
603 | |
604 | |
605 /**************************************************************************/ | |
606 /** @name String Functions */ | |
607 /**************************************************************************/ | |
608 /*@{*/ | |
609 | |
610 /** | |
611 * Normalizes a string, so that it is suitable for comparison. | |
612 * | |
613 * The returned string will point to a static buffer, so if the | |
614 * string is intended to be kept long-term, you <i>must</i> | |
615 * g_strdup() it. Also, calling normalize() twice in the same line | |
616 * will lead to problems. | |
617 * | |
618 * @param account The account the string belongs to, or NULL if you do | |
619 * not know the account. If you use NULL, the string | |
620 * will still be normalized, but if the PRPL uses a | |
621 * custom normalization function then the string may | |
622 * not be normalized correctly. | |
623 * @param str The string to normalize. | |
624 * | |
625 * @return A pointer to the normalized version stored in a static buffer. | |
626 */ | |
627 const char *gaim_normalize(const GaimAccount *account, const char *str); | |
628 | |
629 /** | |
630 * Normalizes a string, so that it is suitable for comparison. | |
631 * | |
632 * This is one possible implementation for the PRPL callback | |
633 * function "normalize." It returns a lowercase and UTF-8 | |
634 * normalized version of the string. | |
635 * | |
636 * @param account The account the string belongs to. | |
637 * @param str The string to normalize. | |
638 * | |
639 * @return A pointer to the normalized version stored in a static buffer. | |
640 */ | |
641 const char *gaim_normalize_nocase(const GaimAccount *account, const char *str); | |
642 | |
643 /** | |
644 * Compares two strings to see if the first contains the second as | |
645 * a proper prefix. | |
646 * | |
647 * @param s The string to check. | |
648 * @param p The prefix in question. | |
649 * | |
650 * @return TRUE if p is a prefix of s, otherwise FALSE. | |
651 */ | |
652 gboolean gaim_str_has_prefix(const char *s, const char *p); | |
653 | |
654 /** | |
655 * Compares two strings to see if the second is a proper suffix | |
656 * of the first. | |
657 * | |
658 * @param s The string to check. | |
659 * @param x The suffix in question. | |
660 * | |
661 * @return TRUE if x is a a suffix of s, otherwise FALSE. | |
662 */ | |
663 gboolean gaim_str_has_suffix(const char *s, const char *x); | |
664 | |
665 /** | |
666 * Duplicates a string and replaces all newline characters from the | |
667 * source string with HTML linebreaks. | |
668 * | |
669 * @param src The source string. | |
670 * | |
671 * @return The new string. Must be g_free'd by the caller. | |
672 */ | |
673 gchar *gaim_strdup_withhtml(const gchar *src); | |
674 | |
675 /** | |
676 * Ensures that all linefeeds have a matching carriage return. | |
677 * | |
678 * @param str The source string. | |
679 * | |
680 * @return The string with carriage returns. | |
681 */ | |
682 char *gaim_str_add_cr(const char *str); | |
683 | |
684 /** | |
685 * Strips all instances of the given character from the | |
686 * given string. The string is modified in place. This | |
687 * is useful for stripping new line characters, for example. | |
688 * | |
689 * Example usage: | |
690 * gaim_str_strip_char(my_dumb_string, '\n'); | |
691 * | |
692 * @param str The string to strip characters from. | |
693 * @param thechar The character to strip from the given string. | |
694 */ | |
695 void gaim_str_strip_char(char *str, char thechar); | |
696 | |
697 /** | |
698 * Given a string, this replaces all instances of one character | |
699 * with another. This happens inline (the original string IS | |
700 * modified). | |
701 * | |
702 * @param string The string from which to replace stuff. | |
703 * @param delimiter The character you want replaced. | |
704 * @param replacement The character you want inserted in place | |
705 * of the delimiting character. | |
706 */ | |
707 void gaim_util_chrreplace(char *string, char delimiter, | |
708 char replacement); | |
709 | |
710 /** | |
711 * Given a string, this replaces one substring with another | |
712 * and returns a newly allocated string. | |
713 * | |
714 * @param string The string from which to replace stuff. | |
715 * @param delimiter The substring you want replaced. | |
716 * @param replacement The substring you want inserted in place | |
717 * of the delimiting substring. | |
718 * | |
719 * @return A new string, after performing the substitution. | |
720 * free this with g_free(). | |
721 */ | |
722 gchar *gaim_strreplace(const char *string, const char *delimiter, | |
723 const char *replacement); | |
724 | |
725 | |
726 /** | |
727 * Given a string, this replaces any utf-8 substrings in that string with | |
728 * the corresponding numerical character reference, and returns a newly | |
729 * allocated string. | |
730 * | |
731 * @param in The string which might contain utf-8 substrings | |
732 * | |
733 * @return A new string, with utf-8 replaced with numerical character | |
734 * references, free this with g_free() | |
735 */ | |
736 char *gaim_utf8_ncr_encode(const char *in); | |
737 | |
738 | |
739 /** | |
740 * Given a string, this replaces any numerical character references | |
741 * in that string with the corresponding actual utf-8 substrings, | |
742 * and returns a newly allocated string. | |
743 * | |
744 * @param in The string which might contain numerical character references. | |
745 * | |
746 * @return A new string, with numerical character references | |
747 * replaced with actual utf-8, free this with g_free(). | |
748 */ | |
749 char *gaim_utf8_ncr_decode(const char *in); | |
750 | |
751 | |
752 /** | |
753 * Given a string, this replaces one substring with another | |
754 * ignoring case and returns a newly allocated string. | |
755 * | |
756 * @param string The string from which to replace stuff. | |
757 * @param delimiter The substring you want replaced. | |
758 * @param replacement The substring you want inserted in place | |
759 * of the delimiting substring. | |
760 * | |
761 * @return A new string, after performing the substitution. | |
762 * free this with g_free(). | |
763 */ | |
764 gchar *gaim_strcasereplace(const char *string, const char *delimiter, | |
765 const char *replacement); | |
766 | |
767 /** | |
768 * This is like strstr, except that it ignores ASCII case in | |
769 * searching for the substring. | |
770 * | |
771 * @param haystack The string to search in. | |
772 * @param needle The substring to find. | |
773 * | |
774 * @return the location of the substring if found, or NULL if not | |
775 */ | |
776 const char *gaim_strcasestr(const char *haystack, const char *needle); | |
777 | |
778 /** | |
779 * Returns a string representing a filesize in the appropriate | |
780 * units (MB, KB, GB, etc.) | |
781 * | |
782 * @param size The size | |
783 * | |
784 * @return The string in units form. This must be freed. | |
785 */ | |
786 char *gaim_str_size_to_units(size_t size); | |
787 | |
788 /** | |
789 * Converts seconds into a human-readable form. | |
790 * | |
791 * @param sec The seconds. | |
792 * | |
793 * @return A human-readable form, containing days, hours, minutes, and | |
794 * seconds. | |
795 */ | |
796 char *gaim_str_seconds_to_string(guint sec); | |
797 | |
798 /** | |
799 * Converts a binary string into a NUL terminated ascii string, | |
800 * replacing nonascii characters and characters below SPACE (including | |
801 * NUL) into \\xyy, where yy are two hex digits. Also backslashes are | |
802 * changed into two backslashes (\\\\). The returned, newly allocated | |
803 * string can be outputted to the console, and must be g_free()d. | |
804 * | |
805 * @param binary A string of random data, possibly with embedded NULs | |
806 * and such. | |
807 * @param len The length in bytes of the input string. Must not be 0. | |
808 * | |
809 * @return A newly allocated ASCIIZ string. | |
810 */ | |
811 char *gaim_str_binary_to_ascii(const unsigned char *binary, guint len); | |
812 /*@}*/ | |
813 | |
814 | |
815 /**************************************************************************/ | |
816 /** @name URI/URL Functions */ | |
817 /**************************************************************************/ | |
818 /*@{*/ | |
819 | |
820 /** | |
821 * Parses a URL, returning its host, port, file path, username and password. | |
822 * | |
823 * The returned data must be freed. | |
824 * | |
825 * @param url The URL to parse. | |
826 * @param ret_host The returned host. | |
827 * @param ret_port The returned port. | |
828 * @param ret_path The returned path. | |
829 * @param ret_user The returned username. | |
830 * @param ret_passwd The returned password. | |
831 */ | |
832 gboolean gaim_url_parse(const char *url, char **ret_host, int *ret_port, | |
833 char **ret_path, char **ret_user, char **ret_passwd); | |
834 | |
14354 | 835 /** |
836 * This is the signature used for functions that act as the callback | |
837 * to gaim_util_fetch_url() or gaim_util_fetch_url_request(). | |
838 * | |
839 * @param url_data The same value that was returned when you called | |
840 * gaim_fetch_url() or gaim_fetch_url_request(). | |
841 * @param user_data The user data that your code passed into either | |
842 * gaim_util_fetch_url() or gaim_util_fetch_url_request(). | |
843 * @param url_text This will be NULL on error. Otherwise this | |
844 * will contain the contents of the URL. | |
845 * @param len 0 on error, otherwise this is the length of buf. | |
846 * @param error_message If something went wrong then this will contain | |
847 * a descriptive error message, and buf will be | |
848 * NULL and len will be 0. | |
849 */ | |
850 typedef void (*GaimUtilFetchUrlCallback)(GaimUtilFetchUrlData *url_data, gpointer user_data, const gchar *url_text, gsize len, const gchar *error_message); | |
14192 | 851 |
852 /** | |
853 * Fetches the data from a URL, and passes it to a callback function. | |
854 * | |
855 * @param url The URL. | |
856 * @param full TRUE if this is the full URL, or FALSE if it's a | |
857 * partial URL. | |
858 * @param user_agent The user agent field to use, or NULL. | |
859 * @param http11 TRUE if HTTP/1.1 should be used to download the file. | |
860 * @param cb The callback function. | |
861 * @param data The user data to pass to the callback function. | |
862 */ | |
14354 | 863 #define gaim_util_fetch_url(url, full, user_agent, http11, cb, data) \ |
864 gaim_util_fetch_url_request(url, full, user_agent, http11, NULL, \ | |
14192 | 865 FALSE, cb, data); |
866 | |
867 /** | |
868 * Fetches the data from a URL, and passes it to a callback function. | |
869 * | |
870 * @param url The URL. | |
871 * @param full TRUE if this is the full URL, or FALSE if it's a | |
872 * partial URL. | |
873 * @param user_agent The user agent field to use, or NULL. | |
874 * @param http11 TRUE if HTTP/1.1 should be used to download the file. | |
875 * @param request A HTTP request to send to the server instead of the | |
876 * standard GET | |
14354 | 877 * @param include_headers |
878 * If TRUE, include the HTTP headers in the response. | |
879 * @param callback The callback function. | |
14192 | 880 * @param data The user data to pass to the callback function. |
881 */ | |
14354 | 882 GaimUtilFetchUrlData *gaim_util_fetch_url_request(const gchar *url, |
883 gboolean full, const gchar *user_agent, gboolean http11, | |
884 const gchar *request, gboolean include_headers, | |
885 GaimUtilFetchUrlCallback callback, gpointer data); | |
886 | |
887 /** | |
888 * Cancel a pending URL request started with either | |
889 * gaim_util_fetch_url_request() or gaim_util_fetch_url(). | |
890 * | |
891 * @param url_data The data returned when you initiated the URL fetch. | |
892 */ | |
893 void gaim_util_fetch_url_cancel(GaimUtilFetchUrlData *url_data); | |
14192 | 894 |
895 /** | |
896 * Decodes a URL into a plain string. | |
897 * | |
898 * This will change hex codes and such to their ascii equivalents. | |
899 * | |
900 * @param str The string to translate. | |
901 * | |
902 * @return The resulting string. | |
903 */ | |
904 const char *gaim_url_decode(const char *str); | |
905 | |
906 /** | |
907 * Encodes a URL into an escaped string. | |
908 * | |
909 * This will change non-alphanumeric characters to hex codes. | |
910 * | |
911 * @param str The string to translate. | |
912 * | |
913 * @return The resulting string. | |
914 */ | |
915 const char *gaim_url_encode(const char *str); | |
916 | |
917 /** | |
918 * Checks if the given email address is syntactically valid. | |
919 * | |
920 * @param address The email address to validate. | |
921 * | |
922 * @return True if the email address is syntactically correct. | |
923 */ | |
924 gboolean gaim_email_is_valid(const char *address); | |
925 | |
926 /** | |
927 * This function extracts a list of URIs from the a "text/uri-list" | |
928 * string. It was "borrowed" from gnome_uri_list_extract_uris | |
929 * | |
930 * @param uri_list An uri-list in the standard format. | |
931 * | |
932 * @return A GList containing strings allocated with g_malloc | |
933 * that have been splitted from uri-list. | |
934 */ | |
935 GList *gaim_uri_list_extract_uris(const gchar *uri_list); | |
936 | |
937 /** | |
938 * This function extracts a list of filenames from a | |
939 * "text/uri-list" string. It was "borrowed" from | |
940 * gnome_uri_list_extract_filenames | |
941 * | |
942 * @param uri_list A uri-list in the standard format. | |
943 * | |
944 * @return A GList containing strings allocated with g_malloc that | |
945 * contain the filenames in the uri-list. Note that unlike | |
946 * gaim_uri_list_extract_uris() function, this will discard | |
947 * any non-file uri from the result value. | |
948 */ | |
949 GList *gaim_uri_list_extract_filenames(const gchar *uri_list); | |
950 | |
951 /*@}*/ | |
952 | |
953 /************************************************************************** | |
954 * UTF8 String Functions | |
955 **************************************************************************/ | |
956 /*@{*/ | |
957 | |
958 /** | |
959 * Attempts to convert a string to UTF-8 from an unknown encoding. | |
960 * | |
961 * This function checks the locale and tries sane defaults. | |
962 * | |
963 * @param str The source string. | |
964 * | |
965 * @return The UTF-8 string, or @c NULL if it could not be converted. | |
966 */ | |
967 gchar *gaim_utf8_try_convert(const char *str); | |
968 | |
969 /** | |
970 * Salvages the valid UTF-8 characters from a string, replacing any | |
971 * invalid characters with a filler character (currently hardcoded to | |
972 * '?'). | |
973 * | |
974 * @param str The source string. | |
975 * | |
976 * @return A valid UTF-8 string. | |
977 */ | |
978 gchar *gaim_utf8_salvage(const char *str); | |
979 | |
980 /** | |
981 * Compares two UTF-8 strings case-insensitively. | |
982 * | |
983 * @param a The first string. | |
984 * @param b The second string. | |
985 * | |
986 * @return -1 if @a is less than @a b. | |
987 * 0 if @a is equal to @a b. | |
988 * 1 if @a is greater than @a b. | |
989 */ | |
990 int gaim_utf8_strcasecmp(const char *a, const char *b); | |
991 | |
992 /** | |
993 * Case insensitive search for a word in a string. The needle string | |
994 * must be contained in the haystack string and not be immediately | |
995 * preceded or immediately followed by another alpha-numeric character. | |
996 * | |
997 * @param haystack The string to search in. | |
998 * @param needle The substring to find. | |
999 * | |
1000 * @return TRUE if haystack has the word, otherwise FALSE | |
1001 */ | |
1002 gboolean gaim_utf8_has_word(const char *haystack, const char *needle); | |
1003 | |
1004 /** | |
1005 * Prints a UTF-8 message to the given file stream. The function | |
1006 * tries to convert the UTF-8 message to user's locale. If this | |
1007 * is not possible, the original UTF-8 text will be printed. | |
1008 * | |
1009 * @param filestream The file stream (e.g. STDOUT or STDERR) | |
1010 * @param message The message to print. | |
1011 */ | |
1012 void gaim_print_utf8_to_console(FILE *filestream, char *message); | |
1013 | |
1014 /** | |
1015 * Checks for messages starting with "/me " | |
1016 * | |
1017 * @param message The message to check | |
1018 * @param len The message length, or -1 | |
1019 * | |
1020 * @return TRUE if it starts with /me, and it has been removed, otherwise FALSE | |
1021 */ | |
1022 gboolean gaim_message_meify(char *message, size_t len); | |
1023 | |
1024 /** | |
1025 * Removes the underscore characters from a string used identify the mnemonic | |
1026 * character. | |
1027 * | |
1028 * @param in The string to strip | |
1029 * | |
1030 * @return The stripped string | |
1031 */ | |
1032 char *gaim_text_strip_mnemonic(const char *in); | |
1033 | |
1034 /*@}*/ | |
1035 | |
1036 /** | |
1037 * Adds 8 to something. | |
1038 * | |
1039 * Blame SimGuy. | |
1040 * | |
1041 * @param x The number to add 8 to. | |
1042 * | |
1043 * @return x + 8 | |
1044 */ | |
1045 #define gaim_add_eight(x) ((x)+8) | |
1046 | |
1047 /** | |
1048 * Does the reverse of gaim_escape_filename | |
1049 * | |
1050 * This will change hex codes and such to their ascii equivalents. | |
1051 * | |
1052 * @param str The string to translate. | |
1053 * | |
1054 * @return The resulting string. | |
1055 */ | |
1056 const char *gaim_unescape_filename(const char *str); | |
1057 | |
1058 /** | |
1059 * Escapes filesystem-unfriendly characters from a filename | |
1060 * | |
1061 * @param str The string to translate. | |
1062 * | |
1063 * @return The resulting string. | |
1064 */ | |
1065 const char *gaim_escape_filename(const char *str); | |
1066 | |
1067 #ifdef __cplusplus | |
1068 } | |
1069 #endif | |
1070 | |
1071 #endif /* _GAIM_UTIL_H_ */ |