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 /* GLib Event Loop Functions                                              */
 326 /**************************************************************************/
 327
 328 /**
 329  * purple_timeout_reset:
 330  * @source:           A #GTimeoutSource.
 331  * @seconds_from_now: Seconds to add to current monotonic time.
 332  *
 333  * Resets a #GTimeoutSource to be dispatched after @seconds_from_now seconds,
 334  * after which it'll continue dispatching at its specified interval.
 335  *
 336  * The #GSource API exposes a function g_source_set_ready_time(), which is
 337  * meant to be used for implementing custom source types. It sets a #GSource
 338  * to be dispatched when the given monotonic time is reached, and it's also
 339  * the function that's used by the #GTimeoutSource implementation to keep
 340  * dispatching at a specified interval.
 341  *
 342  * The #GTimeoutSource API doesn't expose a function to reset when a
 343  * #GTimeoutSource will dispatch the next time, but because it works to
 344  * directly call g_source_set_ready_time() on a #GTimeoutSource, and since
 345  * it seems unlikely that the implementation will change, we just do that
 346  * for now as a workaround for this API shortcoming.
 347  *
 348  * For the moment, these would be correct ways to achieve a similar effect,
 349  * both of which are ugly:
 350  *
 351  * - Remove the old #GTimeoutSource by calling g_source_remove(), and add a
 352  *   new #GTimeoutSource by calling g_timeout_add_seconds(). Destroying and
 353  *   creating #GSource objects is unnecessarily expensive.
 354  * - Implement a custom #GResettableTimeoutSource. This means duplicating
 355  *   #GTimeoutSource and adding one function g_resettable_timeout_reset()
 356  *   which simply calls g_source_set_ready_time().
 357  */
 358 void purple_timeout_reset(GSource *source, gint64 seconds_from_now);
 359
 360
 361 /**************************************************************************/
 362 /* Markup Functions                                                       */
 363 /**************************************************************************/
 364
 365 /**
 366  * purple_markup_escape_text:
 367  * @text: The text to escape
 368  * @length: The length of the text, or -1 if #NULL terminated
 369  *
 370  * Escapes special characters in a plain-text string so they display
 371  * correctly as HTML.  For example, &amp; is replaced with &amp;amp; and &lt; is
 372  * replaced with &amp;lt;
 373  *
 374  * This is exactly the same as g_markup_escape_text(), except that it
 375  * does not change ' to &amp;apos; because &amp;apos; is not a valid HTML 4 entity,
 376  * and is displayed literally in IE7.
 377  */
 378 gchar *purple_markup_escape_text(const gchar *text, gssize length);
 379
 380 /**
 381  * purple_markup_find_tag:
 382  * @needle:       The name of the tag
 383  * @haystack:     The null-delimited string to search in
 384  * @start:                A pointer to the start of the tag if found
 385  * @end:                  A pointer to the end of the tag if found
 386  * @attributes:  The attributes, if the tag was found.  This should
 387  *                    be freed with g_datalist_clear().
 388  *
 389  * Finds an HTML tag matching the given name.
 390  *
 391  * This locates an HTML tag's start and end, and stores its attributes
 392  * in a GData hash table. The names of the attributes are lower-cased
 393  * in the hash table, and the name of the tag is case insensitive.
 394  *
 395  * Returns: TRUE if the tag was found
 396  */
 397 gboolean purple_markup_find_tag(const char *needle, const char *haystack,
 398                                                           const char **start, const char **end,
 399                                                           GData **attributes);
 400
 401 /**
 402  * purple_markup_extract_info_field:
 403  * @str:            The string to parse.
 404  * @len:            The size of str.
 405  * @user_info:      The destination PurpleNotifyUserInfo to which the new
 406  *                       field info should be added.
 407  * @start_token:    The beginning token.
 408  * @skip:           The number of characters to skip after the
 409  *                       start token.
 410  * @end_token:      The ending token.
 411  * @check_value:    The value that the last character must meet.
 412  * @no_value_token: The token indicating no value is given.
 413  * @display_name:   The short descriptive name to display for this token.
 414  * @is_link:        TRUE if this should be a link, or FALSE otherwise.
 415  * @link_prefix:    The prefix for the link.
 416  * @format_cb:      A callback to format the value before adding it.
 417  *
 418  * Extracts a field of data from HTML.
 419  *
 420  * This is a scary function. It used to be used for MSN and Yahoo prpls,
 421  * but since those prpls have been removed, this is now deprecated.
 422  *
 423  * Returns: TRUE if successful, or FALSE otherwise.
 424  */
 425 gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info,
 426                                         const char *start_token, int skip,
 427                                         const char *end_token, char check_value,
 428                                         const char *no_value_token,
 429                                         const char *display_name, gboolean is_link,
 430                                         const char *link_prefix,
 431                                         PurpleInfoFieldFormatCallback format_cb);
 432
 433 /**
 434  * purple_markup_html_to_xhtml:
 435  * @html:       The HTML markup.
 436  * @dest_xhtml: The destination XHTML output.
 437  * @dest_plain: The destination plain-text output.
 438  *
 439  * Converts HTML markup to XHTML.
 440  */
 441 void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,
 442                                                            char **dest_plain);
 443
 444 /**
 445  * purple_markup_strip_html:
 446  * @str: The string to strip HTML from.
 447  *
 448  * Strips HTML tags from a string.
 449  *
 450  * Returns: The new string without HTML.  You must g_free this string
 451  *         when finished with it.
 452  */
 453 char *purple_markup_strip_html(const char *str);
 454
 455 /**
 456  * purple_markup_linkify:
 457  * @str: The string to linkify.
 458  *
 459  * Adds the necessary HTML code to turn URIs into HTML links in a string.
 460  *
 461  * Returns: The new string with all URIs surrounded in standard
 462  *          HTML &lt;a href="whatever"&gt;&lt;/a&gt; tags. You must g_free()
 463  *          this string when finished with it.
 464  */
 465 char *purple_markup_linkify(const char *str);
 466
 467 /**
 468  * purple_unescape_text:
 469  * @text: The string in which to unescape any HTML entities
 470  *
 471  * Unescapes HTML entities to their literal characters in the text.
 472  * For example "&amp;amp;" is replaced by '&amp;' and so on.  Also converts
 473  * numerical entities (e.g. "&amp;\#38;" is also '&amp;').
 474  *
 475  * This function currently supports the following named entities:
 476  *     "&amp;amp;", "&amp;lt;", "&amp;gt;", "&amp;copy;", "&amp;quot;",
 477  *     "&amp;reg;", "&amp;apos;"
 478  *
 479  * purple_unescape_html() is similar, but also converts "&lt;br&gt;" into "\n".
 480  *
 481  *  See purple_unescape_html()
 482  *
 483  * Returns: The text with HTML entities literalized.  You must g_free
 484  *         this string when finished with it.
 485  */
 486 char *purple_unescape_text(const char *text);
 487
 488 /**
 489  * purple_unescape_html:
 490  * @html: The string in which to unescape any HTML entities
 491  *
 492  * Unescapes HTML entities to their literal characters and converts
 493  * "&lt;br&gt;" to "\n".  See purple_unescape_text() for more details.
 494  *
 495  *  See purple_unescape_text()
 496  *
 497  * Returns: The text with HTML entities literalized.  You must g_free
 498  *         this string when finished with it.
 499  */
 500 char *purple_unescape_html(const char *html);
 501
 502 /**
 503  * purple_markup_slice:
 504  * @str: The input NUL terminated, HTML, UTF-8 (or ASCII) string.
 505  * @x: The character offset into an unformatted version of str to
 506  *          begin at.
 507  * @y: The character offset (into an unformatted vesion of str) of
 508  *          one past the last character to include in the slice.
 509  *
 510  * Returns a newly allocated substring of the HTML UTF-8 string "str".
 511  * The markup is preserved such that the substring will have the same
 512  * formatting as original string, even though some tags may have been
 513  * opened before "x", or may close after "y". All open tags are closed
 514  * at the end of the returned string, in the proper order.
 515  *
 516  * Note that x and y are in character offsets, not byte offsets, and
 517  * are offsets into an unformatted version of str. Because of this,
 518  * this function may be sensitive to changes in GtkIMHtml and may break
 519  * when used with other UI's. libpurple users are encouraged to report and
 520  * work out any problems encountered.
 521  *
 522  * Returns: The HTML slice of string, with all formatting retained.
 523  */
 524 char *purple_markup_slice(const char *str, guint x, guint y);
 525
 526 /**
 527  * purple_markup_get_tag_name:
 528  * @tag: The string starting a HTML tag.
 529  *
 530  * Returns a newly allocated string containing the name of the tag
 531  * located at "tag". Tag is expected to point to a '<', and contain
 532  * a '>' sometime after that. If there is no '>' and the string is
 533  * not NUL terminated, this function can be expected to segfault.
 534  *
 535  * Returns: A string containing the name of the tag.
 536  */
 537 char *purple_markup_get_tag_name(const char *tag);
 538
 539 /**
 540  * purple_markup_unescape_entity:
 541  * @text:   A string containing an HTML entity.
 542  * @length: If not %NULL, the string length of the entity is stored in this location.
 543  *
 544  * Returns a constant string of the character representation of the HTML
 545  * entity pointed to by @text. For example, purple_markup_unescape_entity("&amp;amp;")
 546  * will return "&amp;". The @text variable is expected to point to an '&amp;',
 547  * the first character of the entity. If given an unrecognized entity, the function
 548  * returns %NULL.
 549  *
 550  * Note that this function, unlike purple_unescape_html(), does not search
 551  * the string for the entity, does not replace the entity, and does not
 552  * return a newly allocated string.
 553  *
 554  * Returns: A constant string containing the character representation of the given entity.
 555  */
 556 const char * purple_markup_unescape_entity(const char *text, int *length);
 557
 558 /**
 559  * purple_markup_get_css_property:
 560  * @style: A string containing the inline CSS text.
 561  * @opt:   The requested CSS property.
 562  *
 563  * Returns a newly allocated string containing the value of the CSS property specified
 564  * in opt. The @style argument is expected to point to a HTML inline CSS.
 565  * The function will seek for the CSS property and return its value.
 566  *
 567  * For example, purple_markup_get_css_property("direction:rtl;color:#dc4d1b;",
 568  * "color") would return "#dc4d1b".
 569  *
 570  * On error or if the requested property was not found, the function returns
 571  * %NULL.
 572  *
 573  * Returns: The value of the requested CSS property.
 574  */
 575 char * purple_markup_get_css_property(const gchar *style, const gchar *opt);
 576
 577 /**
 578  * purple_markup_is_rtl:
 579  * @html:  The HTML text.
 580  *
 581  * Check if the given HTML contains RTL text.
 582  *
 583  * Returns:  TRUE if the text contains RTL text, FALSE otherwise.
 584  */
 585 gboolean purple_markup_is_rtl(const char *html);
 586
 587
 588 /**************************************************************************/
 589 /* Path/Filename Functions                                                */
 590 /**************************************************************************/
 591
 592 /**
 593  * purple_home_dir:
 594  *
 595  * Returns the user's home directory.
 596  *
 597  *  See purple_user_dir()
 598  *
 599  * Returns: The user's home directory.
 600  */
 601 const gchar *purple_home_dir(void);
 602
 603 /**
 604  * purple_user_dir:
 605  *
 606  * Returns the purple settings directory in the user's home directory.
 607  * This is usually $HOME/.purple
 608  *
 609  *  See purple_home_dir()
 610  *
 611  * Returns: The purple settings directory.
 612  *
 613  * Deprecated: Use purple_cache_dir(), purple_config_dir() or
 614  *             purple_data_dir() instead.
 615  */
 616 G_DEPRECATED_FOR(purple_cache_dir' or 'purple_config_dir' or 'purple_data_dir)
 617 const char *purple_user_dir(void);
 618
 619 /**
 620  * purple_cache_dir:
 621  *
 622  * Returns the purple cache directory according to XDG Base Directory Specification.
 623  * This is usually $HOME/.cache/purple.
 624  * If custom user dir was specified then this is cache
 625  * sub-directory of DIR argument passed to -c option.
 626  *
 627  * Returns: The purple cache directory.
 628  */
 629 const gchar *purple_cache_dir(void);
 630
 631 /**
 632  * purple_config_dir:
 633  *
 634  * Returns the purple configuration directory according to XDG Base Directory Specification.
 635  * This is usually $HOME/.config/purple.
 636  * If custom user dir was specified then this is config
 637  * sub-directory of DIR argument passed to -c option.
 638  *
 639  * Returns: The purple configuration directory.
 640  */
 641 const gchar *purple_config_dir(void);
 642
 643 /**
 644  * purple_data_dir:
 645  *
 646  * Returns the purple data directory according to XDG Base Directory Specification.
 647  * This is usually $HOME/.local/share/purple.
 648  * If custom user dir was specified then this is data
 649  * sub-directory of DIR argument passed to -c option.
 650  *
 651  * Returns: The purple data directory.
 652  */
 653 const gchar *purple_data_dir(void);
 654
 655 /**
 656  * purple_move_to_xdg_base_dir:
 657  * @purple_xdg_dir: The path to cache, config or data dir.
 658  *                  Use respective function
 659  * @path:           File or directory in purple_user_dir
 660  *
 661  * Moves file or directory from legacy user dir to XDG
 662  * based dir.
 663  *
 664  * Returns: TRUE if moved successfully, FALSE otherwise
 665  */
 666 gboolean
 667 purple_move_to_xdg_base_dir(const char *purple_xdg_dir, char *path);
 668
 669 /**
 670  * purple_util_set_user_dir:
 671  * @dir: The custom settings directory
 672  *
 673  * Define a custom purple settings directory, overriding the default (user's home directory/.purple)
 674  */
 675 void purple_util_set_user_dir(const char *dir);
 676
 677 /**
 678  * purple_build_dir:
 679  * @path: The path you wish to create.  Note that it must start
 680  *        from the root or this function will fail.
 681  * @mode: Unix-style permissions for this directory.
 682  *
 683  * Builds a complete path from the root, making any directories along
 684  * the path which do not already exist.
 685  *
 686  * Returns: 0 for success, nonzero on any error.
 687  */
 688 int purple_build_dir(const char *path, int mode);
 689
 690 /**
 691  * purple_util_write_data_to_file:
 692  * @filename: The basename of the file to write in the purple_user_dir.
 693  * @data:     A string of data to write.
 694  * @size:     The size of the data to save.  If data is
 695  *                 null-terminated you can pass in -1.
 696  *
 697  * Write a string of data to a file of the given name in the Purple
 698  * user directory ($HOME/.purple by default).  The data is typically
 699  * a serialized version of one of Purple's config files, such as
 700  * prefs.xml, accounts.xml, etc.  And the string is typically
 701  * obtained using purple_xmlnode_to_formatted_str.  However, this function
 702  * should work fine for saving binary files as well.
 703  *
 704  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 705  *
 706  * Deprecated: Use purple_util_write_data_to_cache_file(),
 707  *             purple_util_write_data_to_config_file() or
 708  *             purple_util_write_data_to_data_file() instead.
 709  */
 710 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)
 711 gboolean purple_util_write_data_to_file(const char *filename, const char *data,
 712                                                                           gssize size);
 713
 714 /**
 715  * purple_util_write_data_to_cache_file:
 716  * @filename: The basename of the file to write in the purple_cache_dir.
 717  * @data:     A string of data to write.
 718  * @size:     The size of the data to save.  If data is
 719  *                 null-terminated you can pass in -1.
 720  *
 721  * Write a string of data to a file of the given name in the Purple
 722  * cache directory ($HOME/.cache/purple by default).
 723  *
 724  *  See purple_util_write_data_to_file()
 725  *
 726  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 727  */
 728 gboolean
 729 purple_util_write_data_to_cache_file(const char *filename, const char *data, gssize size);
 730
 731 /**
 732  * purple_util_write_data_to_config_file:
 733  * @filename: The basename of the file to write in the purple_config_dir.
 734  * @data:     A string of data to write.
 735  * @size:     The size of the data to save.  If data is
 736  *                 null-terminated you can pass in -1.
 737  *
 738  * Write a string of data to a file of the given name in the Purple
 739  * config directory ($HOME/.config/purple by default).
 740  *
 741  *  See purple_util_write_data_to_file()
 742  *
 743  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 744  */
 745 gboolean
 746 purple_util_write_data_to_config_file(const char *filename, const char *data, gssize size);
 747
 748 /**
 749  * purple_util_write_data_to_data_file:
 750  * @filename: The basename of the file to write in the purple_data_dir.
 751  * @data:     A string of data to write.
 752  * @size:     The size of the data to save.  If data is
 753  *                 null-terminated you can pass in -1.
 754  *
 755  * Write a string of data to a file of the given name in the Purple
 756  * data directory ($HOME/.local/share/purple by default).
 757  *
 758  *  See purple_util_write_data_to_file()
 759  *
 760  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 761  */
 762 gboolean
 763 purple_util_write_data_to_data_file(const char *filename, const char *data, gssize size);
 764
 765 /**
 766  * purple_util_write_data_to_file_absolute:
 767  * @filename_full: Filename to write to
 768  * @data:          A string of data to write.
 769  * @size:          The size of the data to save.  If data is
 770  *                      null-terminated you can pass in -1.
 771  *
 772  * Write data to a file using the absolute path.
 773  *
 774  * This exists for Glib backwards compatibility reasons.
 775  *
 776  *  See purple_util_write_data_to_file()
 777  *
 778  * Returns: TRUE if the file was written successfully.  FALSE otherwise.
 779  */
 780 /* TODO: Remove this function (use g_file_set_contents instead) when 3.0.0
 781  *       rolls around. */
 782 gboolean
 783 purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size);
 784
 785 /**
 786  * purple_util_read_xml_from_file:
 787  * @filename:    The basename of the file to open in the purple_user_dir.
 788  * @description: A very short description of the contents of this
 789  *                    file.  This is used in error messages shown to the
 790  *                    user when the file can not be opened.  For example,
 791  *                    "preferences," or "buddy pounces."
 792  *
 793  * Read the contents of a given file and parse the results into an
 794  * PurpleXmlNode tree structure.  This is intended to be used to read
 795  * Purple's configuration xml files (prefs.xml, pounces.xml, etc.)
 796  *
 797  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 798  *         the file does not exist or there was an error reading the file.
 799  *
 800  * Deprecated: Use purple_util_read_xml_from_cache_file(),
 801  *             purple_util_read_xml_from_config_file() or
 802  *             purple_util_read_xml_from_data_file() instead.
 803  */
 804 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)
 805 PurpleXmlNode *purple_util_read_xml_from_file(const char *filename,
 806                                                                           const char *description);
 807
 808 /**
 809  * purple_util_read_xml_from_cache_file:
 810  * @filename:    The basename of the file to open in the purple_cache_dir.
 811  * @description: A very short description of the contents of this
 812  *                    file.  This is used in error messages shown to the
 813  *                    user when the file can not be opened.  For example,
 814  *                    "preferences," or "buddy pounces."
 815  *
 816  * Read the contents of a given file and parse the results into an
 817  * PurpleXmlNode tree structure.  This is intended to be used to read
 818  * Purple's cache xml files (xmpp-caps.xml, etc.)
 819  *
 820  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 821  *         the file does not exist or there was an error reading the file.
 822  */
 823 PurpleXmlNode *
 824 purple_util_read_xml_from_cache_file(const char *filename, const char *description);
 825
 826 /**
 827  * purple_util_read_xml_from_config_file:
 828  * @filename:    The basename of the file to open in the purple_config_dir.
 829  * @description: A very short description of the contents of this
 830  *                    file.  This is used in error messages shown to the
 831  *                    user when the file can not be opened.  For example,
 832  *                    "preferences," or "buddy pounces."
 833  *
 834  * Read the contents of a given file and parse the results into an
 835  * PurpleXmlNode tree structure.  This is intended to be used to read
 836  * Purple's config xml files (prefs.xml, pounces.xml, etc.)
 837  *
 838  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 839  *         the file does not exist or there was an error reading the file.
 840  */
 841 PurpleXmlNode *
 842 purple_util_read_xml_from_config_file(const char *filename, const char *description);
 843
 844 /**
 845  * purple_util_read_xml_from_data_file:
 846  * @filename:    The basename of the file to open in the purple_data_dir.
 847  * @description: A very short description of the contents of this
 848  *                    file.  This is used in error messages shown to the
 849  *                    user when the file can not be opened.  For example,
 850  *                    "preferences," or "buddy pounces."
 851  *
 852  * Read the contents of a given file and parse the results into an
 853  * PurpleXmlNode tree structure.  This is intended to be used to read
 854  * Purple's cache xml files (accounts.xml, etc.)
 855  *
 856  * Returns: An PurpleXmlNode tree of the contents of the given file.  Or NULL, if
 857  *         the file does not exist or there was an error reading the file.
 858  */
 859 PurpleXmlNode *
 860 purple_util_read_xml_from_data_file(const char *filename, const char *description);
 861
 862 /**
 863  * purple_mkstemp:
 864  * @path:   The returned path to the temp file.
 865  * @binary: Text or binary, for platforms where it matters.
 866  *
 867  * Creates a temporary file and returns a file pointer to it.
 868  *
 869  * This is like mkstemp(), but returns a file pointer and uses a
 870  * pre-set template. It uses the semantics of tempnam() for the
 871  * directory to use and allocates the space for the file path.
 872  *
 873  * The caller is responsible for closing the file and removing it when
 874  * done, as well as freeing the space pointed to by @path with
 875  * g_free().
 876  *
 877  * Returns: A file pointer to the temporary file, or %NULL on failure.
 878  */
 879 FILE *purple_mkstemp(char **path, gboolean binary);
 880
 881
 882 /**************************************************************************/
 883 /* Environment Detection Functions                                        */
 884 /**************************************************************************/
 885
 886 /**
 887  * purple_program_is_valid:
 888  * @program: The file name of the application.
 889  *
 890  * Checks if the given program name is valid and executable.
 891  *
 892  * Returns: TRUE if the program is runable.
 893  */
 894 gboolean purple_program_is_valid(const char *program);
 895
 896 /**
 897  * purple_running_gnome:
 898  *
 899  * Check if running GNOME.
 900  *
 901  * Returns: TRUE if running GNOME, FALSE otherwise.
 902  */
 903 gboolean purple_running_gnome(void);
 904
 905 /**
 906  * purple_running_kde:
 907  *
 908  * Check if running KDE.
 909  *
 910  * Returns: TRUE if running KDE, FALSE otherwise.
 911  */
 912 gboolean purple_running_kde(void);
 913
 914 /**
 915  * purple_running_osx:
 916  *
 917  * Check if running OS X.
 918  *
 919  * Returns: TRUE if running OS X, FALSE otherwise.
 920  */
 921 gboolean purple_running_osx(void);
 922
 923 /**
 924  * purple_fd_get_ip:
 925  * @fd: The socket file descriptor.
 926  *
 927  * Returns the IP address from a socket file descriptor.
 928  *
 929  * Returns: The IP address, or %NULL on error.
 930  */
 931 char *purple_fd_get_ip(int fd);
 932
 933 /**
 934  * purple_socket_get_family:
 935  * @fd: The socket file descriptor.
 936  *
 937  * Returns the address family of a socket.
 938  *
 939  * Returns: The address family of the socket (AF_INET, AF_INET6, etc) or -1
 940  *         on error.
 941  */
 942 int purple_socket_get_family(int fd);
 943
 944 /**
 945  * purple_socket_speaks_ipv4:
 946  * @fd: The socket file descriptor
 947  *
 948  * Returns TRUE if a socket is capable of speaking IPv4.
 949  *
 950  * This is the case for IPv4 sockets and, on some systems, IPv6 sockets
 951  * (due to the IPv4-mapped address functionality).
 952  *
 953  * Returns: TRUE if a socket can speak IPv4.
 954  */
 955 gboolean purple_socket_speaks_ipv4(int fd);
 956
 957
 958 /**************************************************************************/
 959 /* String Functions                                                       */
 960 /**************************************************************************/
 961
 962 /**
 963  * purple_strequal:
 964  * @left:       A string
 965  * @right: A string to compare with left
 966  *
 967  * Tests two strings for equality.
 968  *
 969  * Unlike strcmp(), this function will not crash if one or both of the
 970  * strings are %NULL.
 971  *
 972  * Returns: %TRUE if the strings are the same, else %FALSE.
 973  */
 974 static inline gboolean
 975 purple_strequal(const gchar *left, const gchar *right)
 976 {
 977         return (g_strcmp0(left, right) == 0);
 978 }
 979
 980 /**
 981  * purple_normalize:
 982  * @account:  The account the string belongs to, or NULL if you do
 983  *                 not know the account.  If you use NULL, the string
 984  *                 will still be normalized, but if the protocol uses a
 985  *                 custom normalization function then the string may
 986  *                 not be normalized correctly.
 987  * @str:      The string to normalize.
 988  *
 989  * Normalizes a string, so that it is suitable for comparison.
 990  *
 991  * The returned string will point to a static buffer, so if the
 992  * string is intended to be kept long-term, you <emphasis>must</emphasis>
 993  * g_strdup() it. Also, calling normalize() twice in the same line
 994  * will lead to problems.
 995  *
 996  * Returns: A pointer to the normalized version stored in a static buffer.
 997  */
 998 const char *purple_normalize(PurpleAccount *account, const char *str);
 999
1000 /**
1001  * purple_normalize_nocase:
1002  * @account:  The account the string belongs to.
1003  * @str:      The string to normalize.
1004  *
1005  * Normalizes a string, so that it is suitable for comparison.
1006  *
1007  * This is one possible implementation for the protocol callback
1008  * function "normalize."  It returns a lowercase and UTF-8
1009  * normalized version of the string.
1010  *
1011  * Returns: A pointer to the normalized version stored in a static buffer.
1012  */
1013 const char *purple_normalize_nocase(const PurpleAccount *account, const char *str);
1014
1015 /**
1016  * purple_validate:
1017  * @protocol: The protocol the string belongs to.
1018  * @str:      The string to validate.
1019  *
1020  * Checks, if a string is valid.
1021  *
1022  * Returns: TRUE, if string is valid, otherwise FALSE.
1023  */
1024 gboolean purple_validate(const PurpleProtocol *protocol, const char *str);
1025
1026 /**
1027  * purple_str_has_prefix:
1028  * @s:  The string to check.
1029  * @p:  The prefix in question.
1030  *
1031  * Compares two strings to see if the first contains the second as
1032  * a proper prefix.
1033  *
1034  * Returns:   TRUE if p is a prefix of s, otherwise FALSE.
1035  */
1036 gboolean purple_str_has_prefix(const char *s, const char *p);
1037
1038 /**
1039  * purple_str_has_caseprefix:
1040  * @s: The string to check.
1041  * @p: The prefix in question.
1042  *
1043  * Compares two strings to see if the first contains the second as
1044  * a proper case-insensitive prefix.
1045  *
1046  * Returns: %TRUE if @p is a prefix of @s, otherwise %FALSE.
1047  */
1048 gboolean
1049 purple_str_has_caseprefix(const gchar *s, const gchar *p);
1050
1051 /**
1052  * purple_str_has_suffix:
1053  * @s:  The string to check.
1054  * @x:  The suffix in question.
1055  *
1056  * Compares two strings to see if the second is a proper suffix
1057  * of the first.
1058  *
1059  * Returns:   TRUE if x is a a suffix of s, otherwise FALSE.
1060  */
1061 gboolean purple_str_has_suffix(const char *s, const char *x);
1062
1063 /**
1064  * purple_strdup_withhtml:
1065  * @src: The source string.
1066  *
1067  * Duplicates a string and replaces all newline characters from the
1068  * source string with HTML linebreaks.
1069  *
1070  * Returns: The new string.  Must be g_free'd by the caller.
1071  */
1072 gchar *purple_strdup_withhtml(const gchar *src);
1073
1074 /**
1075  * purple_str_add_cr:
1076  * @str: The source string.
1077  *
1078  * Ensures that all linefeeds have a matching carriage return.
1079  *
1080  * Returns: The string with carriage returns.
1081  */
1082 char *purple_str_add_cr(const char *str);
1083
1084 /**
1085  * purple_str_strip_char:
1086  * @str:     The string to strip characters from.
1087  * @thechar: The character to strip from the given string.
1088  *
1089  * Strips all instances of the given character from the
1090  * given string.  The string is modified in place.  This
1091  * is useful for stripping new line characters, for example.
1092  *
1093  * Example usage:
1094  * purple_str_strip_char(my_dumb_string, '\n');
1095  */
1096 void purple_str_strip_char(char *str, char thechar);
1097
1098 /**
1099  * purple_util_chrreplace:
1100  * @string: The string from which to replace stuff.
1101  * @delimiter: The character you want replaced.
1102  * @replacement: The character you want inserted in place
1103  *        of the delimiting character.
1104  *
1105  * Given a string, this replaces all instances of one character
1106  * with another.  This happens inline (the original string IS
1107  * modified).
1108  */
1109 void purple_util_chrreplace(char *string, char delimiter,
1110                                                   char replacement);
1111
1112 /**
1113  * purple_strreplace:
1114  * @string: The string from which to replace stuff.
1115  * @delimiter: The substring you want replaced.
1116  * @replacement: The substring you want inserted in place
1117  *        of the delimiting substring.
1118  *
1119  * Given a string, this replaces one substring with another
1120  * and returns a newly allocated string.
1121  *
1122  * Returns: A new string, after performing the substitution.
1123  *         free this with g_free().
1124  */
1125 gchar *purple_strreplace(const char *string, const char *delimiter,
1126                                            const char *replacement);
1127
1128
1129 /**
1130  * purple_utf8_ncr_encode:
1131  * @in: The string which might contain utf-8 substrings
1132  *
1133  * Given a string, this replaces any utf-8 substrings in that string with
1134  * the corresponding numerical character reference, and returns a newly
1135  * allocated string.
1136  *
1137  * Returns: A new string, with utf-8 replaced with numerical character
1138  *         references, free this with g_free()
1139 */
1140 char *purple_utf8_ncr_encode(const char *in);
1141
1142
1143 /**
1144  * purple_utf8_ncr_decode:
1145  * @in: The string which might contain numerical character references.
1146  *
1147  * Given a string, this replaces any numerical character references
1148  * in that string with the corresponding actual utf-8 substrings,
1149  * and returns a newly allocated string.
1150  *
1151  * Returns: A new string, with numerical character references
1152  *         replaced with actual utf-8, free this with g_free().
1153  */
1154 char *purple_utf8_ncr_decode(const char *in);
1155
1156
1157 /**
1158  * purple_strcasereplace:
1159  * @string: The string from which to replace stuff.
1160  * @delimiter: The substring you want replaced.
1161  * @replacement: The substring you want inserted in place
1162  *        of the delimiting substring.
1163  *
1164  * Given a string, this replaces one substring with another
1165  * ignoring case and returns a newly allocated string.
1166  *
1167  * Returns: A new string, after performing the substitution.
1168  *         free this with g_free().
1169  */
1170 gchar *purple_strcasereplace(const char *string, const char *delimiter,
1171                                                    const char *replacement);
1172
1173 /**
1174  * purple_strcasestr:
1175  * @haystack: The string to search in.
1176  * @needle:   The substring to find.
1177  *
1178  * This is like strstr, except that it ignores ASCII case in
1179  * searching for the substring.
1180  *
1181  * Returns: the location of the substring if found, or NULL if not
1182  */
1183 const char *purple_strcasestr(const char *haystack, const char *needle);
1184
1185 /**
1186  * purple_str_size_to_units:
1187  * @size: The size
1188  *
1189  * Returns a string representing a filesize in the appropriate
1190  * units (MB, KB, GB, etc.)
1191  *
1192  * Returns: The string in units form. This must be freed.
1193  */
1194 char *purple_str_size_to_units(goffset size);
1195
1196 /**
1197  * purple_str_seconds_to_string:
1198  * @sec: The seconds.
1199  *
1200  * Converts seconds into a human-readable form.
1201  *
1202  * Returns: A human-readable form, containing days, hours, minutes, and
1203  *         seconds.
1204  */
1205 char *purple_str_seconds_to_string(guint sec);
1206
1207 /**
1208  * purple_str_binary_to_ascii:
1209  * @binary: A string of random data, possibly with embedded NULs
1210  *               and such.
1211  * @len: The length in bytes of the input string. Must not be 0.
1212  *
1213  * Converts a binary string into a NUL terminated ascii string,
1214  * replacing nonascii characters and characters below SPACE (including
1215  * NUL) into \\xyy, where yy are two hex digits. Also backslashes are
1216  * changed into two backslashes (\\\\). The returned, newly allocated
1217  * string can be outputted to the console, and must be g_free()d.
1218  *
1219  * Returns: A newly allocated ASCIIZ string.
1220  */
1221 char *purple_str_binary_to_ascii(const unsigned char *binary, guint len);
1222
1223 /**
1224  * purple_utf16_size:
1225  * @str: String to check.
1226  *
1227  * Calculates UTF-16 string size (in bytes).
1228  *
1229  * Returns:    Number of bytes (including NUL character) that string occupies.
1230  */
1231 size_t purple_utf16_size(const gunichar2 *str);
1232
1233 /**
1234  * purple_str_wipe:
1235  * @str: A NUL-terminated string to free, or a NULL-pointer.
1236  *
1237  * Fills a NUL-terminated string with zeros and frees it.
1238  *
1239  * It should be used to free sensitive data, like passwords.
1240  */
1241 void purple_str_wipe(gchar *str);
1242
1243 /**
1244  * purple_utf16_wipe:
1245  * @str: A NUL-terminated string to free, or a NULL-pointer.
1246  *
1247  * Fills a NUL-terminated UTF-16 string with zeros and frees it.
1248  *
1249  * It should be used to free sensitive data, like passwords.
1250  */
1251 void purple_utf16_wipe(gunichar2 *str);
1252
1253
1254 /**************************************************************************/
1255 /* URI/URL Functions                                                      */
1256 /**************************************************************************/
1257
1258 void purple_got_protocol_handler_uri(const char *uri);
1259
1260 /**
1261  * purple_url_decode:
1262  * @str: The string to translate.
1263  *
1264  * Decodes a URL into a plain string.
1265  *
1266  * This will change hex codes and such to their ascii equivalents.
1267  *
1268  * Returns: The resulting string.
1269  */
1270 const char *purple_url_decode(const char *str);
1271
1272 /**
1273  * purple_url_encode:
1274  * @str: The string to translate.
1275  *
1276  * Encodes a URL into an escaped string.
1277  *
1278  * This will change non-alphanumeric characters to hex codes.
1279  *
1280  * Returns: The resulting string.
1281  */
1282 const char *purple_url_encode(const char *str);
1283
1284 /**
1285  * purple_email_is_valid:
1286  * @address: The email address to validate.
1287  *
1288  * Checks if the given email address is syntactically valid.
1289  *
1290  * Returns: True if the email address is syntactically correct.
1291  */
1292 gboolean purple_email_is_valid(const char *address);
1293
1294 /**
1295  * purple_ip_address_is_valid:
1296  * @ip: The IP address to validate.
1297  *
1298  * Checks if the given IP address is a syntactically valid IPv4 or
1299  * IPv6 address.
1300  * If you specifically want to check for an IPv4 address use
1301  * purple_ipv4_address_is_valid(), or for an IPv6 address use
1302  * purple_ipv6_address_is_valid().
1303  *
1304  * Returns: True if the IP address is syntactically correct.
1305  */
1306 gboolean purple_ip_address_is_valid(const char *ip);
1307
1308 /**
1309  * purple_ipv4_address_is_valid:
1310  * @ip: The IP address to validate.
1311  *
1312  * Checks if the given IP address is a syntactically valid IPv4 address.
1313  *
1314  * Returns: True if the IP address is syntactically correct.
1315  */
1316 gboolean purple_ipv4_address_is_valid(const char *ip);
1317
1318 /**
1319  * purple_ipv6_address_is_valid:
1320  * @ip: The IP address to validate.
1321  *
1322  * Checks if the given IP address is a syntactically valid IPv6 address.
1323  *
1324  * Returns: True if the IP address is syntactically correct.
1325  */
1326 gboolean purple_ipv6_address_is_valid(const char *ip);
1327
1328 /**
1329  * purple_uri_list_extract_uris:
1330  * @uri_list: An uri-list in the standard format.
1331  *
1332  * This function extracts a list of URIs from the a "text/uri-list"
1333  * string.  It was "borrowed" from gnome_uri_list_extract_uris
1334  *
1335  * Returns: (element-type utf8): A GList containing strings allocated with
1336  *          g_malloc that have been split from uri-list.
1337  */
1338 GList *purple_uri_list_extract_uris(const gchar *uri_list);
1339
1340 /**
1341  * purple_uri_list_extract_filenames:
1342  * @uri_list: A uri-list in the standard format.
1343  *
1344  * This function extracts a list of filenames from a
1345  * "text/uri-list" string.  It was "borrowed" from
1346  * gnome_uri_list_extract_filenames
1347  *
1348  * Returns: (element-type utf8): A GList containing strings allocated with
1349  *          g_malloc that contain the filenames in the uri-list. Note that
1350  *          unlike the purple_uri_list_extract_uris() function, this will
1351  *          discard any non-file uri from the result value.
1352  */
1353 GList *purple_uri_list_extract_filenames(const gchar *uri_list);
1354
1355 /**
1356  * purple_uri_escape_for_open:
1357  * @unescaped: The unescaped URI.
1358  *
1359  * This function escapes any characters that might be interpreted by the shell
1360  * when executing a program to open a URI on some systems.
1361  *
1362  * Returns: A newly allocated string with any shell metacharacters replaced
1363  *          with their escaped equivalents.
1364  */
1365 char *purple_uri_escape_for_open(const char *unescaped);
1366
1367 /**************************************************************************
1368  * UTF8 String Functions
1369  **************************************************************************/
1370
1371 /**
1372  * purple_utf8_try_convert:
1373  * @str: The source string.
1374  *
1375  * Attempts to convert a string to UTF-8 from an unknown encoding.
1376  *
1377  * This function checks the locale and tries sane defaults.
1378  *
1379  * Returns: The UTF-8 string, or %NULL if it could not be converted.
1380  */
1381 gchar *purple_utf8_try_convert(const char *str);
1382
1383 /**
1384  * purple_utf8_salvage:
1385  * @str: The source string.
1386  *
1387  * Salvages the valid UTF-8 characters from a string, replacing any
1388  * invalid characters with a filler character (currently hardcoded to
1389  * '?').
1390  *
1391  * Returns: A valid UTF-8 string.
1392  */
1393 gchar *purple_utf8_salvage(const char *str);
1394
1395 /**
1396  * purple_utf8_strip_unprintables:
1397  * @str: A valid UTF-8 string.
1398  *
1399  * Removes unprintable characters from a UTF-8 string. These characters
1400  * (in particular low-ASCII characters) are invalid in XML 1.0 and thus
1401  * are not allowed in XMPP and are rejected by libxml2 by default.
1402  *
1403  * The returned string must be freed by the caller.
1404  *
1405  * Returns: A newly allocated UTF-8 string without the unprintable characters.
1406  */
1407 gchar *purple_utf8_strip_unprintables(const gchar *str);
1408
1409 /**
1410  * purple_gai_strerror:
1411  * @errnum: The error code.
1412  *
1413  * Return the UTF-8 version of #gai_strerror. It calls #gai_strerror
1414  * then converts the result to UTF-8. This function is analogous to
1415  * g_strerror().
1416  *
1417  * Returns: The UTF-8 error message.
1418  */
1419 const gchar *purple_gai_strerror(gint errnum);
1420
1421 /**
1422  * purple_utf8_strcasecmp:
1423  * @a: The first string.
1424  * @b: The second string.
1425  *
1426  * Compares two UTF-8 strings case-insensitively.  This comparison is
1427  * more expensive than a simple g_utf8_collate() comparison because
1428  * it calls g_utf8_casefold() on each string, which allocates new
1429  * strings.
1430  *
1431  * Returns: -1 if @a is less than @b.
1432  *           0 if @a is equal to @b.
1433  *           1 if @a is greater than @b.
1434  */
1435 int purple_utf8_strcasecmp(const char *a, const char *b);
1436
1437 /**
1438  * purple_utf8_has_word:
1439  * @haystack: The string to search in.
1440  * @needle:   The substring to find.
1441  *
1442  * Case insensitive search for a word in a string. The needle string
1443  * must be contained in the haystack string and not be immediately
1444  * preceded or immediately followed by another alpha-numeric character.
1445  *
1446  * Returns: TRUE if haystack has the word, otherwise FALSE
1447  */
1448 gboolean purple_utf8_has_word(const char *haystack, const char *needle);
1449
1450 /**
1451  * purple_message_meify:
1452  * @message: The message to check
1453  * @len:     The message length, or -1
1454  *
1455  * Checks for messages starting (post-HTML) with "/me ", including the space.
1456  *
1457  * Returns: TRUE if it starts with "/me ", and it has been removed, otherwise
1458  *         FALSE
1459  */
1460 gboolean purple_message_meify(char *message, gssize len);
1461
1462 /**
1463  * purple_text_strip_mnemonic:
1464  * @in:  The string to strip
1465  *
1466  * Removes the underscore characters from a string used identify the mnemonic
1467  * character.
1468  *
1469  * Returns: The stripped string
1470  */
1471 char *purple_text_strip_mnemonic(const char *in);
1472
1473 /**
1474  * purple_unescape_filename:
1475  * @str: The string to translate.
1476  *
1477  * Does the reverse of purple_escape_filename
1478  *
1479  * This will change hex codes and such to their ascii equivalents.
1480  *
1481  * Returns: The resulting string.
1482  */
1483 const char *purple_unescape_filename(const char *str);
1484
1485 /**
1486  * purple_escape_filename:
1487  * @str: The string to translate.
1488  *
1489  * Escapes filesystem-unfriendly characters from a filename
1490  *
1491  * Returns: The resulting string.
1492  */
1493 const char *purple_escape_filename(const char *str);
1494
1495 /**
1496  * purple_escape_js:
1497  * @str: The string to escape.
1498  *
1499  * Escapes javascript-unfriendly substrings from a string.
1500  *
1501  * Returns: The javascript-safe string (must be g_free'd after use).
1502  */
1503 gchar * purple_escape_js(const gchar *str);
1504
1505 /**
1506  * purple_restore_default_signal_handlers:
1507  *
1508  * Restore default signal handlers for signals which might reasonably have
1509  * handlers. This should be called by a fork()'d child process, since child processes
1510  * inherit the handlers of the parent.
1511  */
1512 void purple_restore_default_signal_handlers(void);
1513
1514 /**
1515  * purple_get_host_name:
1516  *
1517  * Gets the host name of the machine. If it not possible to determine the
1518  * host name, "localhost" is returned
1519  *
1520  * Returns: The hostname
1521  */
1522 const gchar *purple_get_host_name(void);
1523
1524 /**
1525  * purple_uuid_random:
1526  *
1527  * Returns a type 4 (random) UUID
1528  *
1529  * Returns: A UUID, caller is responsible for freeing it
1530  */
1531 gchar *purple_uuid_random(void);
1532
1533 /**
1534  * purple_callback_set_zero:
1535  * @data: A pointer to variable, which should be set to NULL.
1536  *
1537  * Sets given pointer to NULL.
1538  *
1539  * Function designed to be used as a GDestroyNotify callback.
1540  */
1541 void purple_callback_set_zero(gpointer data);
1542
1543 /**
1544  * purple_value_new:
1545  * @type:  The type of data to be held by the GValue
1546  *
1547  * Creates a new GValue of the specified type.
1548  *
1549  * Returns:  The created GValue
1550  */
1551 GValue *purple_value_new(GType type);
1552
1553 /**
1554  * purple_value_dup:
1555  * @value:  The GValue to duplicate
1556  *
1557  * Duplicates a GValue.
1558  *
1559  * Returns:  The duplicated GValue
1560  */
1561 GValue *purple_value_dup(GValue *value);
1562
1563 /**
1564  * purple_value_free:
1565  * @value:  The GValue to free.
1566  *
1567  * Frees a GValue.
1568  */
1569 void purple_value_free(GValue *value);
1570
1571 /**
1572  * purple_http_digest_calculate_session_key:
1573  * @algorithm:    The hash algorithm to use
1574  * @username:     The username provided by the user
1575  * @realm:        The authentication realm provided by the server
1576  * @password:     The password provided by the user
1577  * @nonce:        The nonce provided by the server
1578  * @client_nonce: The nonce provided by the client
1579  *
1580  * Calculates a session key for HTTP Digest authentation
1581  *
1582  * See RFC 2617 for more information.
1583  *
1584  * Returns: The session key, or %NULL if an error occurred.
1585  */
1586 gchar *purple_http_digest_calculate_session_key(
1587                 const gchar *algorithm, const gchar *username,
1588                 const gchar *realm, const gchar *password,
1589                 const gchar *nonce, const gchar *client_nonce);
1590
1591 /**
1592  * purple_http_digest_calculate_response:
1593  * @algorithm:         The hash algorithm to use
1594  * @method:            The HTTP method in use
1595  * @digest_uri:        The URI from the initial request
1596  * @qop:               The "quality of protection"
1597  * @entity:            The entity body
1598  * @nonce:             The nonce provided by the server
1599  * @nonce_count:       The nonce count
1600  * @client_nonce:      The nonce provided by the client
1601  * @session_key:       The session key from purple_http_digest_calculate_session_key()
1602  *
1603  * Calculate a response for HTTP Digest authentication
1604  *
1605  * See RFC 2617 for more information.
1606  *
1607  * Returns: The hashed response, or %NULL if an error occurred.
1608  */
1609 gchar *purple_http_digest_calculate_response(
1610                 const gchar *algorithm, const gchar *method,
1611                 const gchar *digest_uri, const gchar *qop,
1612                 const gchar *entity, const gchar *nonce,
1613                 const gchar *nonce_count, const gchar *client_nonce,
1614                 const gchar *session_key);
1615
1616 G_END_DECLS
1617
1618 #endif /* _PURPLE_UTIL_H_ */