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