libpurple/util.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  *
  21  * TODO Rename the functions so that they live somewhere in the purple
  22  *      namespace.
  23  */
  24
  25 #ifndef PURPLE_UTIL_H
  26 #define PURPLE_UTIL_H
  27 /**
  28  * SECTION:util
  29  * @section_id: libpurple-util
  30  * @short_description: <filename>util.h</filename>
  31  * @title: Utility Functions
  32  */
  33
  34 #include <stdio.h>
  35
  36 /**
  37  * PurpleKeyValuePair:
  38  * @key: The key
  39  * @value: The value
  40  *
  41  * A key-value pair.
  42  *
  43  * This is used by, among other things, purple_gtk_combo* functions to pass in a
  44  * list of key-value pairs so it can display a user-friendly value.
  45  */
  46 typedef struct _PurpleKeyValuePair PurpleKeyValuePair;
  47
  48 #include "account.h"
  49 #include "signals.h"
  50 #include "xmlnode.h"
  51 #include "notify.h"
  52 #include "protocols.h"
  53
  54
  55 typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);
  56
  57 struct _PurpleKeyValuePair
  58 {
  59         gchar *key;
  60         void *value;
  61
  62 };
  63
  64 G_BEGIN_DECLS
  65
  66 /**
  67  * purple_util_set_current_song:
  68  * @title:     The title of the song, %NULL to unset the value.
  69  * @artist:    The artist of the song, can be %NULL.
  70  * @album:     The album of the song, can be %NULL.
  71  *
  72  * Set the appropriate presence values for the currently playing song.
  73  */
  74 void purple_util_set_current_song(const char *title, const char *artist,
  75                 const char *album);
  76
  77 /**
  78  * purple_util_format_song_info:
  79  * @title:     The title of the song, %NULL to unset the value.
  80  * @artist:    The artist of the song, can be %NULL.
  81  * @album:     The album of the song, can be %NULL.
  82  * @unused:    Currently unused, must be %NULL.
  83  *
  84  * Format song information.
  85  *
  86  * Returns:   The formatted string. The caller must g_free the returned string.
  87  */
  88 char * purple_util_format_song_info(const char *title, const char *artist,
  89                 const char *album, gpointer unused);
  90
  91 /**************************************************************************/
  92 /* Utility Subsystem                                                      */
  93 /**************************************************************************/
  94
  95 /**
  96  * purple_util_init:
  97  *
  98  * Initializes the utility subsystem.
  99  */
 100 void purple_util_init(void);
 101
 102 /**
 103  * purple_util_uninit:
 104  *
 105  * Uninitializes the util subsystem.
 106  */
 107 void purple_util_uninit(void);
 108
 109 /**************************************************************************/
 110 /* Base16 Functions                                                       */
 111 /**************************************************************************/
 112
 113 /**
 114  * purple_base16_encode:
 115  * @data: The data to convert.
 116  * @len:  The length of the data.
 117  *
 118  * Converts a chunk of binary data to its base-16 equivalent.
 119  *
 120  *  See purple_base16_decode()
 121  *
 122  * Returns: The base-16 string in the ASCII encoding.  Must be
 123  *         g_free'd when no longer needed.
 124  */
 125 gchar *purple_base16_encode(const guchar *data, gsize len);
 126
 127 /**
 128  * purple_base16_decode:
 129  * @str:     The base-16 string to convert to raw data.
 130  * @ret_len: The length of the returned data.  You can
 131  *                pass in NULL if you're sure that you know
 132  *                the length of the decoded data, or if you
 133  *                know you'll be able to use strlen to
 134  *                determine the length, etc.
 135  *
 136  * Converts an ASCII string of base-16 encoded data to
 137  * the binary equivalent.
 138  *
 139  *  See purple_base16_encode()
 140  *
 141  * Returns: The raw data.  Must be g_free'd when no longer needed.
 142  */
 143 guchar *purple_base16_decode(const char *str, gsize *ret_len);
 144
 145 /**
 146  * purple_base16_encode_chunked:
 147  * @data: The data to convert.
 148  * @len:  The length of the data.
 149  *
 150  * Converts a chunk of binary data to a chunked base-16 representation
 151  * (handy for key fingerprints)
 152  *
 153  * Example output: 01:23:45:67:89:AB:CD:EF
 154  *
 155  * Returns: The base-16 string in the ASCII chunked encoding.  Must be
 156  *         g_free'd when no longer needed.
 157  */
 158 gchar *purple_base16_encode_chunked(const guchar *data, gsize len);
 159
 160 /**************************************************************************/
 161 /* Date/Time Functions                                                    */
 162 /**************************************************************************/
 163
 164 /**
 165  * purple_utf8_strftime:
 166  * @format: The format string, in UTF-8
 167  * @tm:     The time to format, or %NULL to use the current local time
 168  *
 169  * Formats a time into the specified format.
 170  *
 171  * This is essentially strftime(), but it has a static buffer
 172  * and handles the UTF-8 conversion for the caller.
 173  *
 174  * This function also provides the GNU \%z formatter if the underlying C
 175  * library doesn't.  However, the format string parser is very naive, which
 176  * means that conversions specifiers to \%z cannot be guaranteed.  The GNU
 177  * strftime(3) man page describes \%z as: 'The time-zone as hour offset from
 178  * GMT.  Required to emit RFC822-conformant dates
 179  * (using "\%a, \%d \%b \%Y \%H:\%M:\%S \%z"). (GNU)'
 180  *
 181  * On Windows, this function also converts the results for \%Z from a timezone
 182  * name (as returned by the system strftime() \%Z format string) to a timezone
 183  * abbreviation (as is the case on Unix).  As with \%z, conversion specifiers
 184  * should not be used.
 185  *
 186  * Note: @format is required to be in UTF-8.  This differs from strftime(),
 187  *       where the format is provided in the locale charset.
 188  *
 189  * Returns: The formatted time, in UTF-8.
 190  */
 191 const char *purple_utf8_strftime(const char *format, const struct tm *tm);
 192
 193 /**
 194  * purple_date_format_short:
 195  * @tm: The time to format, or %NULL to use the current local time
 196  *
 197  * Formats a time into the user's preferred short date format.
 198  *
 199  * The returned string is stored in a static buffer, so the result
 200  * should be g_strdup()'d if it's going to be kept.
 201  *
 202  * Returns: The date, formatted as per the user's settings.  In the USA this
 203  *         is something like "02/18/13"
 204  */
 205 const char *purple_date_format_short(const struct tm *tm);
 206
 207 /**
 208  * purple_date_format_long:
 209  * @tm: The time to format, or %NULL to use the current local time
 210  *
 211  * Formats a time into the user's preferred short date plus time format.
 212  *
 213  * The returned string is stored in a static buffer, so the result
 214  * should be g_strdup()'d if it's going to be kept.
 215  *
 216  * Returns: The timestamp, formatted as per the user's settings.  In the USA
 217  *         this is something like "02/18/13 15:26:44"
 218  */
 219 const char *purple_date_format_long(const struct tm *tm);
 220
 221 /**
 222  * purple_date_format_full:
 223  * @tm: The time to format, or %NULL to use the current local time
 224  *
 225  * Formats a time into the user's preferred full date and time format.
 226  *
 227  * The returned string is stored in a static buffer, so the result
 228  * should be g_strdup()'d if it's going to be kept.
 229  *
 230  * Returns: The date and time, formatted as per the user's settings.  In the
 231  *         USA this is something like "Mon Feb 18 15:26:44 2013"
 232  */
 233 const char *purple_date_format_full(const struct tm *tm);
 234
 235 /**
 236  * purple_time_format:
 237  * @tm: The time to format, or %NULL to use the current local time
 238  *
 239  * Formats a time into the user's preferred time format.
 240  *
 241  * The returned string is stored in a static buffer, so the result
 242  * should be g_strdup()'d if it's going to be kept.
 243  *
 244  * Returns: The time, formatted as per the user's settings.  In the USA this
 245  *         is something like "15:26:44"
 246  */
 247 const char *purple_time_format(const struct tm *tm);
 248
 249 /**
 250  * purple_time_build:
 251  * @year:  The year.
 252  * @month: The month.
 253  * @day:   The day.
 254  * @hour:  The hour.
 255  * @min:   The minute.
 256  * @sec:   The second.
 257  *
 258  * Builds a time_t from the supplied information.
 259  *
 260  * Returns: A time_t.
 261  */
 262 time_t purple_time_build(int year, int month, int day, int hour,
 263                                            int min, int sec);
 264
 265 /**
 266  * PURPLE_NO_TZ_OFF:
 267  *
 268  * Used by purple_str_to_time to indicate no timezone offset was
 269  * specified in the timestamp string.
 270  */
 271 #define PURPLE_NO_TZ_OFF -500000
 272
 273 /**
 274  * purple_str_to_time:
 275  * @timestamp: The timestamp
 276  * @utc:       Assume UTC if no timezone specified
 277  * @tm:        If not %NULL, the caller can get a copy of the
 278  *                  struct tm used to calculate the time_t return value.
 279  * @tz_off:    If not %NULL, the caller can get a copy of the
 280  *                  timezone offset (from UTC) used to calculate the time_t
 281  *                  return value. Note: Zero is a valid offset. As such,
 282  *                  the value of the macro PURPLE_NO_TZ_OFF indicates no
 283  *                  offset was specified (which means that the local
 284  *                  timezone was used in the calculation).
 285  * @rest:      If not %NULL, the caller can get a pointer to the
 286  *                  part of @timestamp left over after parsing is
 287  *                  completed, if it's not the end of @timestamp.
 288  *
 289  * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns
 290  * a time_t.
 291  *
 292  * Returns: A time_t.
 293  */
 294 time_t purple_str_to_time(const char *timestamp, gboolean utc,
 295                         struct tm *tm, long *tz_off, const char **rest);
 296
 297 /**
 298  * purple_str_to_date_time:
 299  * @timestamp: The timestamp
 300  * @utc:       Assume UTC if no timezone specified
 301  *
 302  * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns
 303  * a GDateTime.
 304  *
 305  * Returns: (transfer full): A GDateTime.
 306  */
 307 GDateTime *purple_str_to_date_time(const char *timestamp, gboolean utc);
 308
 309 /**
 310  * purple_uts35_to_str:
 311  * @format: The formatting string, according to UTS \#35
 312  *               See http://unicode.org/reports/tr35/
 313  *               (NOTE: not all formats are supported)
 314  * @len:    The length of the formatting string
 315  * @tm:     The time to format, or %NULL to use the current local time
 316  *
 317  * Formats a datetime according to a UTS-35 Date Format Pattern.
 318  *
 319  * Returns: The time, formatted as per the user's settings.
 320  */
 321 char *purple_uts35_to_str(const char *format, size_t len, struct tm *tm);
 322
 323
 324 /**************************************************************************/
 325 /* Markup Functions                                                       */
 326 /**************************************************************************/
 327
 328 /**
 329  * purple_markup_escape_text:
 330  * @text: The text to escape
 331  * @length: The length of the text, or -1 if #NULL terminated
 332  *
 333  * Escapes special characters in a plain-text string so they display
 334  * correctly as HTML.  For example, &amp; is replaced with &amp;amp; and &lt; is
 335  * replaced with &amp;lt;
 336  *
 337  * This is exactly the same as g_markup_escape_text(), except that it
 338  * does not change ' to &amp;apos; because &amp;apos; is not a valid HTML 4 entity,
 339  * and is displayed literally in IE7.
 340  */
 341 gchar *purple_markup_escape_text(const gchar *text, gssize length);
 342
 343 /**
 344  * purple_markup_find_tag:
 345  * @needle:       The name of the tag
 346  * @haystack:     The null-delimited string to search in
 347  * @start:                A pointer to the start of the tag if found
 348  * @end:                  A pointer to the end of the tag if found
 349  * @attributes:  The attributes, if the tag was found.  This should
 350  *                    be freed with g_datalist_clear().
 351  *
 352  * Finds an HTML tag matching the given name.
 353  *
 354  * This locates an HTML tag's start and end, and stores its attributes
 355  * in a GData hash table. The names of the attributes are lower-cased
 356  * in the hash table, and the name of the tag is case insensitive.
 357  *
 358  * Returns: TRUE if the tag was found
 359  */
 360 gboolean purple_markup_find_tag(const char *needle, const char *haystack,
 361                                                           const char **start, const char **end,
 362                                                           GData **attributes);
 363
 364 /**
 365  * purple_markup_extract_info_field:
 366  * @str:            The string to parse.
 367  * @len:            The size of str.
 368  * @user_info:      The destination PurpleNotifyUserInfo to which the new
 369  *                       field info should be added.
 370  * @start_token:    The beginning token.
 371  * @skip:           The number of characters to skip after the
 372  *                       start token.
 373  * @end_token:      The ending token.
 374  * @check_value:    The value that the last character must meet.
 375  * @no_value_token: The token indicating no value is given.
 376  * @display_name:   The short descriptive name to display for this token.
 377  * @is_link:        TRUE if this should be a link, or FALSE otherwise.
 378  * @link_prefix:    The prefix for the link.
 379  * @format_cb: (scope call): A callback to format the value before adding it.
 380  *
 381  * Extracts a field of data from HTML.
 382  *
 383  * This is a scary function. It used to be used for MSN and Yahoo prpls,
 384  * but since those prpls have been removed, this is now deprecated.
 385  *
 386  * Returns: TRUE if successful, or FALSE otherwise.
 387  */
 388 gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info,
 389                                         const char *start_token, int skip,
 390                                         const char *end_token, char check_value,
 391                                         const char *no_value_token,
 392                                         const char *display_name, gboolean is_link,
 393                                         const char *link_prefix,
 394                                         PurpleInfoFieldFormatCallback format_cb);
 395
 396 /**
 397  * purple_markup_html_to_xhtml:
 398  * @html:       The HTML markup.
 399  * @dest_xhtml: The destination XHTML output.
 400  * @dest_plain: The destination plain-text output.
 401  *
 402  * Converts HTML markup to XHTML.
 403  */
 404 void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,
 405                                                            char **dest_plain);
 406
 407 /**
 408  * purple_markup_strip_html:
 409  * @str: The string to strip HTML from.
 410  *
 411  * Strips HTML tags from a string.
 412  *
 413  * Returns: The new string without HTML.  You must g_free this string
 414  *         when finished with it.
 415  */
 416 char *purple_markup_strip_html(const char *str);
 417
 418 /**
 419  * purple_markup_linkify:
 420  * @str: The string to linkify.
 421  *
 422  * Adds the necessary HTML code to turn URIs into HTML links in a string.
 423  *
 424  * Returns: The new string with all URIs surrounded in standard
 425  *          HTML &lt;a href="whatever"&gt;&lt;/a&gt; tags. You must g_free()
 426  *          this string when finished with it.
 427  */
 428 char *purple_markup_linkify(const char *str);
 429
 430 /**
 431  * purple_unescape_text:
 432  * @text: The string in which to unescape any HTML entities
 433  *
 434  * Unescapes HTML entities to their literal characters in the text.
 435  * For example "&amp;amp;" is replaced by '&amp;' and so on.  Also converts
 436  * numerical entities (e.g. "&amp;\#38;" is also '&amp;').
 437  *
 438  * This function currently supports the following named entities:
 439  *     "&amp;amp;", "&amp;lt;", "&amp;gt;", "&amp;copy;", "&amp;quot;",
 440  *     "&amp;reg;", "&amp;apos;"
 441  *
 442  * purple_unescape_html() is similar, but also converts "&lt;br&gt;" into "\n".
 443  *
 444  *  See purple_unescape_html()
 445  *
 446  * Returns: The text with HTML entities literalized.  You must g_free
 447  *         this string when finished with it.
 448  */
 449 char *purple_unescape_text(const char *text);
 450
 451 /**
 452  * purple_unescape_html:
 453  * @html: The string in which to unescape any HTML entities
 454  *
 455  * Unescapes HTML entities to their literal characters and converts
 456  * "&lt;br&gt;" to "\n".  See purple_unescape_text() for more details.
 457  *
 458  *  See purple_unescape_text()
 459  *
 460  * Returns: The text with HTML entities literalized.  You must g_free
 461  *         this string when finished with it.
 462  */
 463 char *purple_unescape_html(const char *html);
 464
 465 /**
 466  * purple_markup_slice:
 467  * @str: The input NUL terminated, HTML, UTF-8 (or ASCII) string.
 468  * @x: The character offset into an unformatted version of str to
 469  *          begin at.
 470  * @y: The character offset (into an unformatted vesion of str) of
 471  *          one past the last character to include in the slice.
 472  *
 473  * Returns a newly allocated substring of the HTML UTF-8 string "str".
 474  * The markup is preserved such that the substring will have the same
 475  * formatting as original string, even though some tags may have been
 476  * opened before "x", or may close after "y". All open tags are closed
 477  * at the end of the returned string, in the proper order.
 478  *
 479  * Note that x and y are in character offsets, not byte offsets, and
 480  * are offsets into an unformatted version of str. Because of this,
 481  * this function may be sensitive to changes in GtkIMHtml and may break
 482  * when used with other UI's. libpurple users are encouraged to report and
 483  * work out any problems encountered.
 484  *
 485  * Returns: The HTML slice of string, with all formatting retained.
 486  */
 487 char *purple_markup_slice(const char *str, guint x, guint y);
 488
 489 /**
 490  * purple_markup_get_tag_name:
 491  * @tag: The string starting a HTML tag.
 492  *
 493  * Returns a newly allocated string containing the name of the tag
 494  * located at "tag". Tag is expected to point to a '<', and contain
 495  * a '>' sometime after that. If there is no '>' and the string is
 496  * not NUL terminated, this function can be expected to segfault.
 497  *
 498  * Returns: A string containing the name of the tag.
 499  */
 500 char *purple_markup_get_tag_name(const char *tag);
 501
 502 /**
 503  * purple_markup_unescape_entity:
 504  * @text:   A string containing an HTML entity.
 505  * @length: If not %NULL, the string length of the entity is stored in this location.
 506  *
 507  * Returns a constant string of the character representation of the HTML
 508  * entity pointed to by @text. For example, purple_markup_unescape_entity("&amp;amp;")
 509  * will return "&amp;". The @text variable is expected to point to an '&amp;',
 510  * the first character of the entity. If given an unrecognized entity, the function
 511  * returns %NULL.
 512  *
 513  * Note that this function, unlike purple_unescape_html(), does not search
 514  * the string for the entity, does not replace the entity, and does not
 515  * return a newly allocated string.
 516  *
 517  * Returns: A constant string containing the character representation of the given entity.
 518  */
 519 const char * purple_markup_unescape_entity(const char *text, int *length);
 520
 521 /**
 522  * purple_markup_get_css_property:
 523  * @style: A string containing the inline CSS text.
 524  * @opt:   The requested CSS property.
 525  *
 526  * Returns a newly allocated string containing the value of the CSS property specified
 527  * in opt. The @style argument is expected to point to a HTML inline CSS.
 528  * The function will seek for the CSS property and return its value.
 529  *
 530  * For example, purple_markup_get_css_property("direction:rtl;color:#dc4d1b;",
 531  * "color") would return "#dc4d1b".
 532  *
 533  * On error or if the requested property was not found, the function returns
 534  * %NULL.
 535  *
 536  * Returns: The value of the requested CSS property.
 537  */
 538 char * purple_markup_get_css_property(const gchar *style, const gchar *opt);
 539
 540 /**
 541  * purple_markup_is_rtl:
 542  * @html:  The HTML text.
 543  *
 544  * Check if the given HTML contains RTL text.
 545  *
 546  * Returns:  TRUE if the text contains RTL text, FALSE otherwise.
 547  */
 548 gboolean purple_markup_is_rtl(const char *html);
 549
 550
 551 /**************************************************************************/
 552 /* Path/Filename Functions                                                */
 553 /**************************************************************************/
 554
 555 /**
 556  * purple_home_dir:
 557  *
 558  * Returns the user's home directory.
 559  *
 560  *  See purple_user_dir()
 561  *
 562  * Returns: The user's home directory.
 563  */
 564 const gchar *purple_home_dir(void);
 565
 566 /**
 567  * purple_user_dir:
 568  *
 569  * Returns the purple settings directory in the user's home directory.
 570  * This is usually $HOME/.purple
 571  *
 572  *  See purple_home_dir()
 573  *
 574  * Returns: The purple settings directory.
 575  *
 576  * Deprecated: Use purple_cache_dir(), purple_config_dir() or
 577  *             purple_data_dir() instead.
 578  */
 579 G_DEPRECATED_FOR(purple_cache_dir' or 'purple_config_dir' or 'purple_data_dir)
 580 const char *purple_user_dir(void);
 581
 582 /**
 583  * purple_cache_dir:
 584  *
 585  * Returns the purple cache directory according to XDG Base Directory Specification.
 586  * This is usually $HOME/.cache/purple.
 587  * If custom user dir was specified then this is cache
 588  * sub-directory of DIR argument passed to -c option.
 589  *
 590  * Returns: The purple cache directory.
 591  */
 592 const gchar *purple_cache_dir(void);
 593
 594 /**
 595  * purple_config_dir:
 596  *
 597  * Returns the purple configuration directory according to XDG Base Directory Specification.
 598  * This is usually $HOME/.config/purple.
 599  * If custom user dir was specified then this is config
 600  * sub-directory of DIR argument passed to -c option.
 601  *
 602  * Returns: The purple configuration directory.
 603  */
 604 const gchar *purple_config_dir(void);
 605
 606 /**
 607  * purple_data_dir:
 608  *
 609  * Returns the purple data directory according to XDG Base Directory Specification.
 610  * This is usually $HOME/.local/share/purple.
 611  * If custom user dir was specified then this is data
 612  * sub-directory of DIR argument passed to -c option.
 613  *
 614  * Returns: The purple data directory.
 615  */
 616 const gchar *purple_data_dir(void);
 617
 618 /**
 619  * purple_move_to_xdg_base_dir:
 620  * @purple_xdg_dir: The path to cache, config or data dir.
 621  *                  Use respective function
 622  * @path:           File or directory in purple_user_dir
 623  *
 624  * Moves file or directory from legacy user dir to XDG
 625  * based dir.
 626  *
 627  * Returns: TRUE if moved successfully, FALSE otherwise
 628  */
 629 gboolean
 630 purple_move_to_xdg_base_dir(const char *purple_xdg_dir, char *path);
 631
 632 /**
 633  * purple_util_set_user_dir:
 634  * @dir: The custom settings directory
 635  *
 636  * Define a custom purple settings directory, overriding the default (user's home directory/.purple)
 637  */
 638 void purple_util_set_user_dir(const char *dir);
 639
 640 /**
 641  * purple_build_dir:
 642  * @path: The path you wish to create.  Note that it must start
 643  *        from the root or this function will fail.
 644  * @mode: Unix-style permissions for this directory.
 645  *
 646  * Builds a complete path from the root, making any directories along
 647  * the path which do not already exist.
 648  *
 649  * Returns: 0 for success, nonzero on any error.
 650  */
 651 int purple_build_dir(const char *path, int mode);
 652
 653 /**
 654  * purple_util_write_data_to_file:
 655  * @filename: The basename of the file to write in the purple_user_dir.
 656  * @data:     A string of data to write.
 657  * @size:     The size of the data to save.  If data is
 658  *                 null-terminated you can pass in -1.
 659  *
 660  * Write a string of data to a file of the given name in the Purple
 661  * user directory ($HOME/.purple by default).  The data is typically
 662  * a serialized version of one of Purple's config files, such as
 663  * prefs.xml, accounts.xml, etc.  And the string is typically
 664  * obtained using purple_xmlnode_to_formatted_str.  However, this function
 665  * should work fine for saving binary files as well.
 666  *
 667  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 668  *
 669  * Deprecated: Use purple_util_write_data_to_cache_file(),
 670  *             purple_util_write_data_to_config_file() or
 671  *             purple_util_write_data_to_data_file() instead.
 672  */
 673 G_DEPRECATED_FOR(purple_util_write_data_to_cache_file' or 'purple_util_write_data_to_config_file' or 'purple_util_write_data_to_data_file)
 674 gboolean purple_util_write_data_to_file(const char *filename, const char *data,
 675                                                                           gssize size);
 676
 677 /**
 678  * purple_util_write_data_to_cache_file:
 679  * @filename: The basename of the file to write in the purple_cache_dir.
 680  * @data:     A string of data to write.
 681  * @size:     The size of the data to save.  If data is
 682  *                 null-terminated you can pass in -1.
 683  *
 684  * Write a string of data to a file of the given name in the Purple
 685  * cache directory ($HOME/.cache/purple by default).
 686  *
 687  *  See purple_util_write_data_to_file()
 688  *
 689  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 690  */
 691 gboolean
 692 purple_util_write_data_to_cache_file(const char *filename, const char *data, gssize size);
 693
 694 /**
 695  * purple_util_write_data_to_config_file:
 696  * @filename: The basename of the file to write in the purple_config_dir.
 697  * @data:     A string of data to write.
 698  * @size:     The size of the data to save.  If data is
 699  *                 null-terminated you can pass in -1.
 700  *
 701  * Write a string of data to a file of the given name in the Purple
 702  * config directory ($HOME/.config/purple by default).
 703  *
 704  *  See purple_util_write_data_to_file()
 705  *
 706  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 707  */
 708 gboolean
 709 purple_util_write_data_to_config_file(const char *filename, const char *data, gssize size);
 710
 711 /**
 712  * purple_util_write_data_to_data_file:
 713  * @filename: The basename of the file to write in the purple_data_dir.
 714  * @data:     A string of data to write.
 715  * @size:     The size of the data to save.  If data is
 716  *                 null-terminated you can pass in -1.
 717  *
 718  * Write a string of data to a file of the given name in the Purple
 719  * data directory ($HOME/.local/share/purple by default).
 720  *
 721  *  See purple_util_write_data_to_file()
 722  *
 723  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 724  */
 725 gboolean
 726 purple_util_write_data_to_data_file(const char *filename, const char *data, gssize size);
 727
 728 /**
 729  * purple_util_write_data_to_file_absolute:
 730  * @filename_full: Filename to write to
 731  * @data:          A string of data to write.
 732  * @size:          The size of the data to save.  If data is
 733  *                      null-terminated you can pass in -1.
 734  *
 735  * Write data to a file using the absolute path.
 736  *
 737  * This exists for Glib backwards compatibility reasons.
 738  *
 739  *  See purple_util_write_data_to_file()
 740  *
 741  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 742  */
 743 /* TODO: Remove this function (use g_file_set_contents instead) when 3.0.0
 744  *       rolls around. */
 745 gboolean
 746 purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size);
 747
 748 /**
 749  * purple_util_read_xml_from_file:
 750  * @filename:    The basename of the file to open in the purple_user_dir.
 751  * @description: A very short description of the contents of this
 752  *                    file.  This is used in error messages shown to the
 753  *                    user when the file can not be opened.  For example,
 754  *                    "preferences," or "buddy pounces."
 755  *
 756  * Read the contents of a given file and parse the results into an
 757  * PurpleXmlNode tree structure.  This is intended to be used to read
 758  * Purple's configuration xml files (prefs.xml, pounces.xml, etc.)
 759  *
 760  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 761  *         the file does not exist or there was an error reading the file.
 762  *
 763  * Deprecated: Use purple_util_read_xml_from_cache_file(),
 764  *             purple_util_read_xml_from_config_file() or
 765  *             purple_util_read_xml_from_data_file() instead.
 766  */
 767 G_DEPRECATED_FOR(purple_util_read_xml_from_cache_file' or 'purple_util_read_xml_from_config_file' or 'purple_util_read_xml_from_data_file)
 768 PurpleXmlNode *purple_util_read_xml_from_file(const char *filename,
 769                                                                           const char *description);
 770
 771 /**
 772  * purple_util_read_xml_from_cache_file:
 773  * @filename:    The basename of the file to open in the purple_cache_dir.
 774  * @description: A very short description of the contents of this
 775  *                    file.  This is used in error messages shown to the
 776  *                    user when the file can not be opened.  For example,
 777  *                    "preferences," or "buddy pounces."
 778  *
 779  * Read the contents of a given file and parse the results into an
 780  * PurpleXmlNode tree structure.  This is intended to be used to read
 781  * Purple's cache xml files (xmpp-caps.xml, etc.)
 782  *
 783  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 784  *         the file does not exist or there was an error reading the file.
 785  */
 786 PurpleXmlNode *
 787 purple_util_read_xml_from_cache_file(const char *filename, const char *description);
 788
 789 /**
 790  * purple_util_read_xml_from_config_file:
 791  * @filename:    The basename of the file to open in the purple_config_dir.
 792  * @description: A very short description of the contents of this
 793  *                    file.  This is used in error messages shown to the
 794  *                    user when the file can not be opened.  For example,
 795  *                    "preferences," or "buddy pounces."
 796  *
 797  * Read the contents of a given file and parse the results into an
 798  * PurpleXmlNode tree structure.  This is intended to be used to read
 799  * Purple's config xml files (prefs.xml, pounces.xml, etc.)
 800  *
 801  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 802  *         the file does not exist or there was an error reading the file.
 803  */
 804 PurpleXmlNode *
 805 purple_util_read_xml_from_config_file(const char *filename, const char *description);
 806
 807 /**
 808  * purple_util_read_xml_from_data_file:
 809  * @filename:    The basename of the file to open in the purple_data_dir.
 810  * @description: A very short description of the contents of this
 811  *                    file.  This is used in error messages shown to the
 812  *                    user when the file can not be opened.  For example,
 813  *                    "preferences," or "buddy pounces."
 814  *
 815  * Read the contents of a given file and parse the results into an
 816  * PurpleXmlNode tree structure.  This is intended to be used to read
 817  * Purple's cache xml files (accounts.xml, etc.)
 818  *
 819  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 820  *         the file does not exist or there was an error reading the file.
 821  */
 822 PurpleXmlNode *
 823 purple_util_read_xml_from_data_file(const char *filename, const char *description);
 824
 825 /**
 826  * purple_mkstemp:
 827  * @path:   The returned path to the temp file.
 828  * @binary: Text or binary, for platforms where it matters.
 829  *
 830  * Creates a temporary file and returns a file pointer to it.
 831  *
 832  * This is like mkstemp(), but returns a file pointer and uses a
 833  * pre-set template. It uses the semantics of tempnam() for the
 834  * directory to use and allocates the space for the file path.
 835  *
 836  * The caller is responsible for closing the file and removing it when
 837  * done, as well as freeing the space pointed to by @path with
 838  * g_free().
 839  *
 840  * Returns: A file pointer to the temporary file, or %NULL on failure.
 841  */
 842 FILE *purple_mkstemp(char **path, gboolean binary);
 843
 844
 845 /**************************************************************************/
 846 /* Environment Detection Functions                                        */
 847 /**************************************************************************/
 848
 849 /**
 850  * purple_program_is_valid:
 851  * @program: The file name of the application.
 852  *
 853  * Checks if the given program name is valid and executable.
 854  *
 855  * Returns: TRUE if the program is runable.
 856  */
 857 gboolean purple_program_is_valid(const char *program);
 858
 859 /**
 860  * purple_running_gnome:
 861  *
 862  * Check if running GNOME.
 863  *
 864  * Returns: TRUE if running GNOME, FALSE otherwise.
 865  */
 866 gboolean purple_running_gnome(void);
 867
 868 /**
 869  * purple_running_kde:
 870  *
 871  * Check if running KDE.
 872  *
 873  * Returns: TRUE if running KDE, FALSE otherwise.
 874  */
 875 gboolean purple_running_kde(void);
 876
 877 /**
 878  * purple_running_osx:
 879  *
 880  * Check if running OS X.
 881  *
 882  * Returns: TRUE if running OS X, FALSE otherwise.
 883  */
 884 gboolean purple_running_osx(void);
 885
 886 /**
 887  * purple_fd_get_ip:
 888  * @fd: The socket file descriptor.
 889  *
 890  * Returns the IP address from a socket file descriptor.
 891  *
 892  * Returns: The IP address, or %NULL on error.
 893  */
 894 char *purple_fd_get_ip(int fd);
 895
 896 /**
 897  * purple_socket_get_family:
 898  * @fd: The socket file descriptor.
 899  *
 900  * Returns the address family of a socket.
 901  *
 902  * Returns: The address family of the socket (AF_INET, AF_INET6, etc) or -1
 903  *         on error.
 904  */
 905 int purple_socket_get_family(int fd);
 906
 907 /**
 908  * purple_socket_speaks_ipv4:
 909  * @fd: The socket file descriptor
 910  *
 911  * Returns TRUE if a socket is capable of speaking IPv4.
 912  *
 913  * This is the case for IPv4 sockets and, on some systems, IPv6 sockets
 914  * (due to the IPv4-mapped address functionality).
 915  *
 916  * Returns: TRUE if a socket can speak IPv4.
 917  */
 918 gboolean purple_socket_speaks_ipv4(int fd);
 919
 920
 921 /**************************************************************************/
 922 /* String Functions                                                       */
 923 /**************************************************************************/
 924
 925 /**
 926  * purple_strequal:
 927  * @left:       A string
 928  * @right: A string to compare with left
 929  *
 930  * Tests two strings for equality.
 931  *
 932  * Unlike strcmp(), this function will not crash if one or both of the
 933  * strings are %NULL.
 934  *
 935  * Returns: %TRUE if the strings are the same, else %FALSE.
 936  */
 937 static inline gboolean
 938 purple_strequal(const gchar *left, const gchar *right)
 939 {
 940         return (g_strcmp0(left, right) == 0);
 941 }
 942
 943 /**
 944  * purple_normalize:
 945  * @account:  The account the string belongs to, or NULL if you do
 946  *                 not know the account.  If you use NULL, the string
 947  *                 will still be normalized, but if the protocol uses a
 948  *                 custom normalization function then the string may
 949  *                 not be normalized correctly.
 950  * @str:      The string to normalize.
 951  *
 952  * Normalizes a string, so that it is suitable for comparison.
 953  *
 954  * The returned string will point to a static buffer, so if the
 955  * string is intended to be kept long-term, you <emphasis>must</emphasis>
 956  * g_strdup() it. Also, calling normalize() twice in the same line
 957  * will lead to problems.
 958  *
 959  * Returns: A pointer to the normalized version stored in a static buffer.
 960  */
 961 const char *purple_normalize(PurpleAccount *account, const char *str);
 962
 963 /**
 964  * purple_normalize_nocase:
 965  * @account:  The account the string belongs to.
 966  * @str:      The string to normalize.
 967  *
 968  * Normalizes a string, so that it is suitable for comparison.
 969  *
 970  * This is one possible implementation for the protocol callback
 971  * function "normalize."  It returns a lowercase and UTF-8
 972  * normalized version of the string.
 973  *
 974  * Returns: A pointer to the normalized version stored in a static buffer.
 975  */
 976 const char *purple_normalize_nocase(const PurpleAccount *account, const char *str);
 977
 978 /**
 979  * purple_validate:
 980  * @protocol: The protocol the string belongs to.
 981  * @str:      The string to validate.
 982  *
 983  * Checks, if a string is valid.
 984  *
 985  * Returns: TRUE, if string is valid, otherwise FALSE.
 986  */
 987 gboolean purple_validate(const PurpleProtocol *protocol, const char *str);
 988
 989 /**
 990  * purple_str_has_prefix:
 991  * @s:  The string to check.
 992  * @p:  The prefix in question.
 993  *
 994  * Compares two strings to see if the first contains the second as
 995  * a proper prefix.
 996  *
 997  * Returns:   TRUE if p is a prefix of s, otherwise FALSE.
 998  */
 999 gboolean purple_str_has_prefix(const char *s, const char *p);
1000
1001 /**
1002  * purple_str_has_caseprefix:
1003  * @s: The string to check.
1004  * @p: The prefix in question.
1005  *
1006  * Compares two strings to see if the first contains the second as
1007  * a proper case-insensitive prefix.
1008  *
1009  * Returns: %TRUE if @p is a prefix of @s, otherwise %FALSE.
1010  */
1011 gboolean
1012 purple_str_has_caseprefix(const gchar *s, const gchar *p);
1013
1014 /**
1015  * purple_str_has_suffix:
1016  * @s:  The string to check.
1017  * @x:  The suffix in question.
1018  *
1019  * Compares two strings to see if the second is a proper suffix
1020  * of the first.
1021  *
1022  * Returns:   TRUE if x is a a suffix of s, otherwise FALSE.
1023  */
1024 gboolean purple_str_has_suffix(const char *s, const char *x);
1025
1026 /**
1027  * purple_strdup_withhtml:
1028  * @src: The source string.
1029  *
1030  * Duplicates a string and replaces all newline characters from the
1031  * source string with HTML linebreaks.
1032  *
1033  * Returns: The new string.  Must be g_free'd by the caller.
1034  */
1035 gchar *purple_strdup_withhtml(const gchar *src);
1036
1037 /**
1038  * purple_str_add_cr:
1039  * @str: The source string.
1040  *
1041  * Ensures that all linefeeds have a matching carriage return.
1042  *
1043  * Returns: The string with carriage returns.
1044  */
1045 char *purple_str_add_cr(const char *str);
1046
1047 /**
1048  * purple_str_strip_char:
1049  * @str:     The string to strip characters from.
1050  * @thechar: The character to strip from the given string.
1051  *
1052  * Strips all instances of the given character from the
1053  * given string.  The string is modified in place.  This
1054  * is useful for stripping new line characters, for example.
1055  *
1056  * Example usage:
1057  * purple_str_strip_char(my_dumb_string, '\n');
1058  */
1059 void purple_str_strip_char(char *str, char thechar);
1060
1061 /**
1062  * purple_util_chrreplace:
1063  * @string: The string from which to replace stuff.
1064  * @delimiter: The character you want replaced.
1065  * @replacement: The character you want inserted in place
1066  *        of the delimiting character.
1067  *
1068  * Given a string, this replaces all instances of one character
1069  * with another.  This happens inline (the original string IS
1070  * modified).
1071  */
1072 void purple_util_chrreplace(char *string, char delimiter,
1073                                                   char replacement);
1074
1075 /**
1076  * purple_strreplace:
1077  * @string: The string from which to replace stuff.
1078  * @delimiter: The substring you want replaced.
1079  * @replacement: The substring you want inserted in place
1080  *        of the delimiting substring.
1081  *
1082  * Given a string, this replaces one substring with another
1083  * and returns a newly allocated string.
1084  *
1085  * Returns: A new string, after performing the substitution.
1086  *         free this with g_free().
1087  */
1088 gchar *purple_strreplace(const char *string, const char *delimiter,
1089                                            const char *replacement);
1090
1091
1092 /**
1093  * purple_utf8_ncr_encode:
1094  * @in: The string which might contain utf-8 substrings
1095  *
1096  * Given a string, this replaces any utf-8 substrings in that string with
1097  * the corresponding numerical character reference, and returns a newly
1098  * allocated string.
1099  *
1100  * Returns: A new string, with utf-8 replaced with numerical character
1101  *         references, free this with g_free()
1102 */
1103 char *purple_utf8_ncr_encode(const char *in);
1104
1105
1106 /**
1107  * purple_utf8_ncr_decode:
1108  * @in: The string which might contain numerical character references.
1109  *
1110  * Given a string, this replaces any numerical character references
1111  * in that string with the corresponding actual utf-8 substrings,
1112  * and returns a newly allocated string.
1113  *
1114  * Returns: A new string, with numerical character references
1115  *         replaced with actual utf-8, free this with g_free().
1116  */
1117 char *purple_utf8_ncr_decode(const char *in);
1118
1119
1120 /**
1121  * purple_strcasereplace:
1122  * @string: The string from which to replace stuff.
1123  * @delimiter: The substring you want replaced.
1124  * @replacement: The substring you want inserted in place
1125  *        of the delimiting substring.
1126  *
1127  * Given a string, this replaces one substring with another
1128  * ignoring case and returns a newly allocated string.
1129  *
1130  * Returns: A new string, after performing the substitution.
1131  *         free this with g_free().
1132  */
1133 gchar *purple_strcasereplace(const char *string, const char *delimiter,
1134                                                    const char *replacement);
1135
1136 /**
1137  * purple_strcasestr:
1138  * @haystack: The string to search in.
1139  * @needle:   The substring to find.
1140  *
1141  * This is like strstr, except that it ignores ASCII case in
1142  * searching for the substring.
1143  *
1144  * Returns: the location of the substring if found, or NULL if not
1145  */
1146 const char *purple_strcasestr(const char *haystack, const char *needle);
1147
1148 /**
1149  * purple_str_seconds_to_string:
1150  * @sec: The seconds.
1151  *
1152  * Converts seconds into a human-readable form.
1153  *
1154  * Returns: A human-readable form, containing days, hours, minutes, and
1155  *         seconds.
1156  */
1157 char *purple_str_seconds_to_string(guint sec);
1158
1159 /**
1160  * purple_str_binary_to_ascii:
1161  * @binary: A string of random data, possibly with embedded NULs
1162  *               and such.
1163  * @len: The length in bytes of the input string. Must not be 0.
1164  *
1165  * Converts a binary string into a NUL terminated ascii string,
1166  * replacing nonascii characters and characters below SPACE (including
1167  * NUL) into \\xyy, where yy are two hex digits. Also backslashes are
1168  * changed into two backslashes (\\\\). The returned, newly allocated
1169  * string can be outputted to the console, and must be g_free()d.
1170  *
1171  * Returns: A newly allocated ASCIIZ string.
1172  */
1173 char *purple_str_binary_to_ascii(const unsigned char *binary, guint len);
1174
1175 /**
1176  * purple_utf16_size:
1177  * @str: String to check.
1178  *
1179  * Calculates UTF-16 string size (in bytes).
1180  *
1181  * Returns:    Number of bytes (including NUL character) that string occupies.
1182  */
1183 size_t purple_utf16_size(const gunichar2 *str);
1184
1185 /**
1186  * purple_str_wipe:
1187  * @str: A NUL-terminated string to free, or a NULL-pointer.
1188  *
1189  * Fills a NUL-terminated string with zeros and frees it.
1190  *
1191  * It should be used to free sensitive data, like passwords.
1192  */
1193 void purple_str_wipe(gchar *str);
1194
1195 /**
1196  * purple_utf16_wipe:
1197  * @str: A NUL-terminated string to free, or a NULL-pointer.
1198  *
1199  * Fills a NUL-terminated UTF-16 string with zeros and frees it.
1200  *
1201  * It should be used to free sensitive data, like passwords.
1202  */
1203 void purple_utf16_wipe(gunichar2 *str);
1204
1205
1206 /**************************************************************************/
1207 /* URI/URL Functions                                                      */
1208 /**************************************************************************/
1209
1210 void purple_got_protocol_handler_uri(const char *uri);
1211
1212 /**
1213  * purple_url_decode:
1214  * @str: The string to translate.
1215  *
1216  * Decodes a URL into a plain string.
1217  *
1218  * This will change hex codes and such to their ascii equivalents.
1219  *
1220  * Returns: The resulting string.
1221  */
1222 const char *purple_url_decode(const char *str);
1223
1224 /**
1225  * purple_url_encode:
1226  * @str: The string to translate.
1227  *
1228  * Encodes a URL into an escaped string.
1229  *
1230  * This will change non-alphanumeric characters to hex codes.
1231  *
1232  * Returns: The resulting string.
1233  */
1234 const char *purple_url_encode(const char *str);
1235
1236 /**
1237  * purple_email_is_valid:
1238  * @address: The email address to validate.
1239  *
1240  * Checks if the given email address is syntactically valid.
1241  *
1242  * Returns: True if the email address is syntactically correct.
1243  */
1244 gboolean purple_email_is_valid(const char *address);
1245
1246 /**
1247  * purple_ip_address_is_valid:
1248  * @ip: The IP address to validate.
1249  *
1250  * Checks if the given IP address is a syntactically valid IPv4 or
1251  * IPv6 address.
1252  * If you specifically want to check for an IPv4 address use
1253  * purple_ipv4_address_is_valid(), or for an IPv6 address use
1254  * purple_ipv6_address_is_valid().
1255  *
1256  * Returns: True if the IP address is syntactically correct.
1257  */
1258 gboolean purple_ip_address_is_valid(const char *ip);
1259
1260 /**
1261  * purple_ipv4_address_is_valid:
1262  * @ip: The IP address to validate.
1263  *
1264  * Checks if the given IP address is a syntactically valid IPv4 address.
1265  *
1266  * Returns: True if the IP address is syntactically correct.
1267  */
1268 gboolean purple_ipv4_address_is_valid(const char *ip);
1269
1270 /**
1271  * purple_ipv6_address_is_valid:
1272  * @ip: The IP address to validate.
1273  *
1274  * Checks if the given IP address is a syntactically valid IPv6 address.
1275  *
1276  * Returns: True if the IP address is syntactically correct.
1277  */
1278 gboolean purple_ipv6_address_is_valid(const char *ip);
1279
1280 /**
1281  * purple_uri_list_extract_uris:
1282  * @uri_list: An uri-list in the standard format.
1283  *
1284  * This function extracts a list of URIs from the a "text/uri-list"
1285  * string.  It was "borrowed" from gnome_uri_list_extract_uris
1286  *
1287  * Returns: (element-type utf8) (transfer full): A list of strings that have
1288  *          been split from uri-list.
1289  */
1290 GList *purple_uri_list_extract_uris(const gchar *uri_list);
1291
1292 /**
1293  * purple_uri_list_extract_filenames:
1294  * @uri_list: A uri-list in the standard format.
1295  *
1296  * This function extracts a list of filenames from a
1297  * "text/uri-list" string.  It was "borrowed" from
1298  * gnome_uri_list_extract_filenames
1299  *
1300  * Returns: (element-type utf8) (transfer full): A list of strings that contain
1301  *          the filenames in the uri-list. Note that unlike the
1302  *          purple_uri_list_extract_uris() function, this will discard any
1303  *          non-file uri from the result value.
1304  */
1305 GList *purple_uri_list_extract_filenames(const gchar *uri_list);
1306
1307 /**
1308  * purple_uri_escape_for_open:
1309  * @unescaped: The unescaped URI.
1310  *
1311  * This function escapes any characters that might be interpreted by the shell
1312  * when executing a program to open a URI on some systems.
1313  *
1314  * Returns: A newly allocated string with any shell metacharacters replaced
1315  *          with their escaped equivalents.
1316  */
1317 char *purple_uri_escape_for_open(const char *unescaped);
1318
1319 /**************************************************************************
1320  * UTF8 String Functions
1321  **************************************************************************/
1322
1323 /**
1324  * purple_utf8_try_convert:
1325  * @str: The source string.
1326  *
1327  * Attempts to convert a string to UTF-8 from an unknown encoding.
1328  *
1329  * This function checks the locale and tries sane defaults.
1330  *
1331  * Returns: The UTF-8 string, or %NULL if it could not be converted.
1332  */
1333 gchar *purple_utf8_try_convert(const char *str);
1334
1335 /**
1336  * purple_utf8_salvage:
1337  * @str: The source string.
1338  *
1339  * Salvages the valid UTF-8 characters from a string, replacing any
1340  * invalid characters with a filler character (currently hardcoded to
1341  * '?').
1342  *
1343  * Returns: A valid UTF-8 string.
1344  */
1345 gchar *purple_utf8_salvage(const char *str);
1346
1347 /**
1348  * purple_utf8_strip_unprintables:
1349  * @str: A valid UTF-8 string.
1350  *
1351  * Removes unprintable characters from a UTF-8 string. These characters
1352  * (in particular low-ASCII characters) are invalid in XML 1.0 and thus
1353  * are not allowed in XMPP and are rejected by libxml2 by default.
1354  *
1355  * The returned string must be freed by the caller.
1356  *
1357  * Returns: A newly allocated UTF-8 string without the unprintable characters.
1358  */
1359 gchar *purple_utf8_strip_unprintables(const gchar *str);
1360
1361 /**
1362  * purple_gai_strerror:
1363  * @errnum: The error code.
1364  *
1365  * Return the UTF-8 version of #gai_strerror. It calls #gai_strerror
1366  * then converts the result to UTF-8. This function is analogous to
1367  * g_strerror().
1368  *
1369  * Returns: The UTF-8 error message.
1370  */
1371 const gchar *purple_gai_strerror(gint errnum);
1372
1373 /**
1374  * purple_utf8_strcasecmp:
1375  * @a: The first string.
1376  * @b: The second string.
1377  *
1378  * Compares two UTF-8 strings case-insensitively.  This comparison is
1379  * more expensive than a simple g_utf8_collate() comparison because
1380  * it calls g_utf8_casefold() on each string, which allocates new
1381  * strings.
1382  *
1383  * Returns: -1 if @a is less than @b.
1384  *           0 if @a is equal to @b.
1385  *           1 if @a is greater than @b.
1386  */
1387 int purple_utf8_strcasecmp(const char *a, const char *b);
1388
1389 /**
1390  * purple_utf8_has_word:
1391  * @haystack: The string to search in.
1392  * @needle:   The substring to find.
1393  *
1394  * Case insensitive search for a word in a string. The needle string
1395  * must be contained in the haystack string and not be immediately
1396  * preceded or immediately followed by another alpha-numeric character.
1397  *
1398  * Returns: TRUE if haystack has the word, otherwise FALSE
1399  */
1400 gboolean purple_utf8_has_word(const char *haystack, const char *needle);
1401
1402 /**
1403  * purple_message_meify:
1404  * @message: The message to check
1405  * @len:     The message length, or -1
1406  *
1407  * Checks for messages starting (post-HTML) with "/me ", including the space.
1408  *
1409  * Returns: TRUE if it starts with "/me ", and it has been removed, otherwise
1410  *         FALSE
1411  */
1412 gboolean purple_message_meify(char *message, gssize len);
1413
1414 /**
1415  * purple_text_strip_mnemonic:
1416  * @in:  The string to strip
1417  *
1418  * Removes the underscore characters from a string used identify the mnemonic
1419  * character.
1420  *
1421  * Returns: The stripped string
1422  */
1423 char *purple_text_strip_mnemonic(const char *in);
1424
1425 /**
1426  * purple_unescape_filename:
1427  * @str: The string to translate.
1428  *
1429  * Does the reverse of purple_escape_filename
1430  *
1431  * This will change hex codes and such to their ascii equivalents.
1432  *
1433  * Returns: The resulting string.
1434  */
1435 const char *purple_unescape_filename(const char *str);
1436
1437 /**
1438  * purple_escape_filename:
1439  * @str: The string to translate.
1440  *
1441  * Escapes filesystem-unfriendly characters from a filename
1442  *
1443  * Returns: The resulting string.
1444  */
1445 const char *purple_escape_filename(const char *str);
1446
1447 /**
1448  * purple_escape_js:
1449  * @str: The string to escape.
1450  *
1451  * Escapes javascript-unfriendly substrings from a string.
1452  *
1453  * Returns: The javascript-safe string (must be g_free'd after use).
1454  */
1455 gchar * purple_escape_js(const gchar *str);
1456
1457 /**
1458  * purple_restore_default_signal_handlers:
1459  *
1460  * Restore default signal handlers for signals which might reasonably have
1461  * handlers. This should be called by a fork()'d child process, since child processes
1462  * inherit the handlers of the parent.
1463  */
1464 void purple_restore_default_signal_handlers(void);
1465
1466 /**
1467  * purple_get_host_name:
1468  *
1469  * Gets the host name of the machine. If it not possible to determine the
1470  * host name, "localhost" is returned
1471  *
1472  * Returns: The hostname
1473  */
1474 const gchar *purple_get_host_name(void);
1475
1476 /**
1477  * purple_uuid_random:
1478  *
1479  * Returns a type 4 (random) UUID
1480  *
1481  * Returns: A UUID, caller is responsible for freeing it
1482  */
1483 gchar *purple_uuid_random(void);
1484
1485 /**
1486  * purple_callback_set_zero:
1487  * @data: A pointer to variable, which should be set to NULL.
1488  *
1489  * Sets given pointer to NULL.
1490  *
1491  * Function designed to be used as a GDestroyNotify callback.
1492  */
1493 void purple_callback_set_zero(gpointer data);
1494
1495 /**
1496  * purple_value_new:
1497  * @type:  The type of data to be held by the GValue
1498  *
1499  * Creates a new GValue of the specified type.
1500  *
1501  * Returns:  The created GValue
1502  */
1503 GValue *purple_value_new(GType type);
1504
1505 /**
1506  * purple_value_dup:
1507  * @value:  The GValue to duplicate
1508  *
1509  * Duplicates a GValue.
1510  *
1511  * Returns:  The duplicated GValue
1512  */
1513 GValue *purple_value_dup(GValue *value);
1514
1515 /**
1516  * purple_value_free:
1517  * @value:  The GValue to free.
1518  *
1519  * Frees a GValue.
1520  */
1521 void purple_value_free(GValue *value);
1522
1523 /**
1524  * purple_http_digest_calculate_session_key:
1525  * @algorithm:    The hash algorithm to use
1526  * @username:     The username provided by the user
1527  * @realm:        The authentication realm provided by the server
1528  * @password:     The password provided by the user
1529  * @nonce:        The nonce provided by the server
1530  * @client_nonce: The nonce provided by the client
1531  *
1532  * Calculates a session key for HTTP Digest authentation
1533  *
1534  * See RFC 2617 for more information.
1535  *
1536  * Returns: The session key, or %NULL if an error occurred.
1537  */
1538 gchar *purple_http_digest_calculate_session_key(
1539                 const gchar *algorithm, const gchar *username,
1540                 const gchar *realm, const gchar *password,
1541                 const gchar *nonce, const gchar *client_nonce);
1542
1543 /**
1544  * purple_http_digest_calculate_response:
1545  * @algorithm:         The hash algorithm to use
1546  * @method:            The HTTP method in use
1547  * @digest_uri:        The URI from the initial request
1548  * @qop:               The "quality of protection"
1549  * @entity:            The entity body
1550  * @nonce:             The nonce provided by the server
1551  * @nonce_count:       The nonce count
1552  * @client_nonce:      The nonce provided by the client
1553  * @session_key:       The session key from purple_http_digest_calculate_session_key()
1554  *
1555  * Calculate a response for HTTP Digest authentication
1556  *
1557  * See RFC 2617 for more information.
1558  *
1559  * Returns: The hashed response, or %NULL if an error occurred.
1560  */
1561 gchar *purple_http_digest_calculate_response(
1562                 const gchar *algorithm, const gchar *method,
1563                 const gchar *digest_uri, const gchar *qop,
1564                 const gchar *entity, const gchar *nonce,
1565                 const gchar *nonce_count, const gchar *client_nonce,
1566                 const gchar *session_key);
1567
1568 G_END_DECLS
1569
1570 #endif /* PURPLE_UTIL_H */