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