libpurple/util.h

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