/**

 * @file util.h Utility Functions

 * @ingroup core

 */

/* purple

 *

 * Purple is the legal property of its developers, whose names are too numerous

 * to list here.  Please refer to the COPYRIGHT file distributed with this

 * source distribution.

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation; either version 2 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA

 *

 * @todo Rename the functions so that they live somewhere in the purple

 *       namespace.

 */

#ifndef _PURPLE_UTIL_H_

#define _PURPLE_UTIL_H_

#include <stdio.h>

typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData;

typedef struct _PurpleMenuAction PurpleMenuAction;

typedef struct _PurpleKeyValuePair PurpleKeyValuePair;

#include "account.h"

#include "xmlnode.h"

#include "notify.h"

#ifdef __cplusplus

extern "C" {

#endif

struct _PurpleMenuAction

{

	char *label;

	PurpleCallback callback;

	gpointer data;

	GList *children;

};

typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);

/**

 * A key-value pair.

 *

 * This is used by, among other things, purple_gtk_combo* functions to pass in a

 * list of key-value pairs so it can display a user-friendly value.

 */

struct _PurpleKeyValuePair

{

	gchar *key;

	void *value;

};

/**

 * Creates a new PurpleMenuAction.

 *

 * @param label    The text label to display for this action.

 * @param callback The function to be called when the action is used on

 *                 the selected item.

 * @param data     Additional data to be passed to the callback.

 * @param children A GList of PurpleMenuActions to be added as a submenu

 *                 of the action.

 * @return The PurpleMenuAction.

 */

PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback,

                                     gpointer data, GList *children);

/**

 * Frees a PurpleMenuAction

 *

 * @param act The PurpleMenuAction to free.

 */

void purple_menu_action_free(PurpleMenuAction *act);

/**

 * Set the appropriate presence values for the currently playing song.

 *

 * @param title     The title of the song, @c NULL to unset the value.

 * @param artist    The artist of the song, can be @c NULL.

 * @param album     The album of the song, can be @c NULL.

 * @since 2.4.0

 */

void purple_util_set_current_song(const char *title, const char *artist,

		const char *album);

/**

 * Format song information.

 *

 * @param title     The title of the song, @c NULL to unset the value.

 * @param artist    The artist of the song, can be @c NULL.

 * @param album     The album of the song, can be @c NULL.

 * @param unused    Currently unused, must be @c NULL.

 *

 * @return   The formatted string. The caller must #g_free the returned string.

 * @since 2.4.0

 */

char * purple_util_format_song_info(const char *title, const char *artist,

		const char *album, gpointer unused);

/**************************************************************************/

/** @name Utility Subsystem                                               */

/**************************************************************************/

/*@{*/

/**

 * Initializes the utility subsystem.

 *

 * @since 2.3.0

 */

void purple_util_init(void);

/**

 * Uninitializes the util subsystem.

 *

 * @since 2.3.0

 */

void purple_util_uninit(void);

/*@}*/

/**************************************************************************/

/** @name Base16 Functions                                                */

/**************************************************************************/

/*@{*/

/**

 * Converts a chunk of binary data to its base-16 equivalent.

 *

 * @param data The data to convert.

 * @param len  The length of the data.

 *

 * @return The base-16 string in the ASCII encoding.  Must be

 *         g_free'd when no longer needed.

 *

 * @see purple_base16_decode()

 */

gchar *purple_base16_encode(const guchar *data, gsize len);

/**

 * Converts an ASCII string of base-16 encoded data to

 * the binary equivalent.

 *

 * @param str     The base-16 string to convert to raw data.

 * @param ret_len The length of the returned data.  You can

 *                pass in NULL if you're sure that you know

 *                the length of the decoded data, or if you

 *                know you'll be able to use strlen to

 *                determine the length, etc.

 *

 * @return The raw data.  Must be g_free'd when no longer needed.

 *

 * @see purple_base16_encode()

 */

guchar *purple_base16_decode(const char *str, gsize *ret_len);

/**

 * Converts a chunk of binary data to a chunked base-16 representation

 * (handy for key fingerprints)

 *

 * Example output: 01:23:45:67:89:AB:CD:EF

 *

 * @param data The data to convert.

 * @param len  The length of the data.

 *

 * @return The base-16 string in the ASCII chunked encoding.  Must be

 *         g_free'd when no longer needed.

 */

gchar *purple_base16_encode_chunked(const guchar *data, gsize len);

/*@}*/

/**************************************************************************/

/** @name Base64 Functions                                                */

/**************************************************************************/

/*@{*/

/**

 * Converts a chunk of binary data to its base-64 equivalent.

 *

 * @param data The data to convert.

 * @param len  The length of the data.

 *

 * @return The base-64 string in the ASCII encoding.  Must be

 *         g_free'd when no longer needed.

 *

 * @see purple_base64_decode()

 */

gchar *purple_base64_encode(const guchar *data, gsize len);

/**

 * Converts an ASCII string of base-64 encoded data to

 * the binary equivalent.

 *

 * @param str     The base-64 string to convert to raw data.

 * @param ret_len The length of the returned data.  You can

 *                pass in NULL if you're sure that you know

 *                the length of the decoded data, or if you

 *                know you'll be able to use strlen to

 *                determine the length, etc.

 *

 * @return The raw data.  Must be g_free'd when no longer needed.

 *

 * @see purple_base64_encode()

 */

guchar *purple_base64_decode(const char *str, gsize *ret_len);

/*@}*/

/**************************************************************************/

/** @name Quoted Printable Functions                                      */

/**************************************************************************/

/*@{*/

/**

 * Converts a quoted printable string back to its readable equivalent.

 * What is a quoted printable string, you ask?  It's an encoding used

 * to transmit binary data as ASCII.  It's intended purpose is to send

 * emails containing non-ASCII characters.  Wikipedia has a pretty good

 * explanation.  Also see RFC 2045.

 *

 * @param str     The quoted printable ASCII string to convert to raw data.

 * @param ret_len The length of the returned data.

 *

 * @return The readable string.  Must be g_free'd when no longer needed.

 */

guchar *purple_quotedp_decode(const char *str, gsize *ret_len);

/*@}*/

/**************************************************************************/

/** @name MIME Functions                                                  */

/**************************************************************************/

/*@{*/

/**

 * Converts a MIME header field string back to its readable equivalent

 * according to RFC 2047.  Basically, a header is plain ASCII and can

 * contain any number of sections called "encoded-words."  The format

 * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=

 * =? designates the beginning of the encoded-word

 * ?= designates the end of the encoded-word

 *

 * An encoded word is segmented into three pieces by the use of a

 * question mark.  The first piece is the character set, the second

 * piece is the encoding, and the third piece is the encoded text.

 *

 * @param str The ASCII string, possibly containing any number of

 *            encoded-word sections.

 *

 * @return The string, with any encoded-word sections decoded and

 *         converted to UTF-8.  Must be g_free'd when no longer

 *         needed.

 */

char *purple_mime_decode_field(const char *str);

/*@}*/

/**************************************************************************/

/** @name Date/Time Functions                                             */

/**************************************************************************/

/*@{*/

/**

 * Formats a time into the specified format.

 *

 * This is essentially strftime(), but it has a static buffer

 * and handles the UTF-8 conversion for the caller.

 *

 * This function also provides the GNU %z formatter if the underlying C

 * library doesn't.  However, the format string parser is very naive, which

 * means that conversions specifiers to %z cannot be guaranteed.  The GNU

 * strftime(3) man page describes %z as: 'The time-zone as hour offset from

 * GMT.  Required to emit RFC822-conformant dates

 * (using "%a, %d %b %Y %H:%M:%S %z"). (GNU)'

 *

 * On Windows, this function also converts the results for %Z from a timezone

 * name (as returned by the system strftime() %Z format string) to a timezone

 * abbreviation (as is the case on Unix).  As with %z, conversion specifiers

 * should not be used.

 *

 * @param format The format string, in UTF-8

 * @param tm     The time to format, or @c NULL to use the current local time

 *

 * @return The formatted time, in UTF-8.

 *

 * @note @a format is required to be in UTF-8.  This differs from strftime(),

 *       where the format is provided in the locale charset.

 */

const char *purple_utf8_strftime(const char *format, const struct tm *tm);

/**

 * Gets a string representation of the local timezone offset

 *

 * @param tm   The time to get the timezone for

 * @param iso  TRUE to format the offset according to ISO-8601, FALSE to

 *             not substitute 'Z' for 0 offset, and to not separate

 *             hours and minutes with a colon.

 */

const char *purple_get_tzoff_str(const struct tm *tm, gboolean iso);

/**

 * Formats a time into the user's preferred short date format.

 *

 * The returned string is stored in a static buffer, so the result

 * should be g_strdup()'d if it's going to be kept.

 *

 * @param tm The time to format, or @c NULL to use the current local time

 *

 * @return The date, formatted as per the user's settings.

 */

const char *purple_date_format_short(const struct tm *tm);

/**

 * Formats a time into the user's preferred short date plus time format.

 *

 * The returned string is stored in a static buffer, so the result

 * should be g_strdup()'d if it's going to be kept.

 *

 * @param tm The time to format, or @c NULL to use the current local time

 *

 * @return The timestamp, formatted as per the user's settings.

 */

const char *purple_date_format_long(const struct tm *tm);

/**

 * Formats a time into the user's preferred full date and time format.

 *

 * The returned string is stored in a static buffer, so the result

 * should be g_strdup()'d if it's going to be kept.

 *

 * @param tm The time to format, or @c NULL to use the current local time

 *

 * @return The date and time, formatted as per the user's settings.

 */

const char *purple_date_format_full(const struct tm *tm);

/**

 * Formats a time into the user's preferred time format.

 *

 * The returned string is stored in a static buffer, so the result

 * should be g_strdup()'d if it's going to be kept.

 *

 * @param tm The time to format, or @c NULL to use the current local time

 *

 * @return The time, formatted as per the user's settings.

 */

const char *purple_time_format(const struct tm *tm);

/**

 * Builds a time_t from the supplied information.

 *

 * @param year  The year.

 * @param month The month.

 * @param day   The day.

 * @param hour  The hour.

 * @param min   The minute.

 * @param sec   The second.

 *

 * @return A time_t.

 */

time_t purple_time_build(int year, int month, int day, int hour,

					   int min, int sec);

/** Used by purple_str_to_time to indicate no timezone offset was

  * specified in the timestamp string. */

#define PURPLE_NO_TZ_OFF -500000

/**

 * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns

 * a time_t.

 *

 * @param timestamp The timestamp

 * @param utc       Assume UTC if no timezone specified

 * @param tm        If not @c NULL, the caller can get a copy of the

 *                  struct tm used to calculate the time_t return value.

 * @param tz_off    If not @c NULL, the caller can get a copy of the

 *                  timezone offset (from UTC) used to calculate the time_t

 *                  return value. Note: Zero is a valid offset. As such,

 *                  the value of the macro @c PURPLE_NO_TZ_OFF indicates no

 *                  offset was specified (which means that the local

 *                  timezone was used in the calculation).

 * @param rest      If not @c NULL, the caller can get a pointer to the

 *                  part of @a timestamp left over after parsing is

 *                  completed, if it's not the end of @a timestamp.

 *

 * @return A time_t.

 */

time_t purple_str_to_time(const char *timestamp, gboolean utc,

                        struct tm *tm, long *tz_off, const char **rest);

/*@}*/

/**************************************************************************/

/** @name Markup Functions                                                */

/**************************************************************************/

/*@{*/

/**

 * Escapes special characters in a plain-text string so they display

 * correctly as HTML.  For example, & is replaced with &amp; and < is

 * replaced with <

 *

 * This is exactly the same as g_markup_escape_text(), except that it

 * does not change ' to ' because ' is not a valid HTML 4 entity,

 * and is displayed literally in IE7.

 *

 * @since 2.6.0

 */

gchar *purple_markup_escape_text(const gchar *text, gssize length);

/**

 * Finds an HTML tag matching the given name.

 *

 * This locates an HTML tag's start and end, and stores its attributes

 * in a GData hash table. The names of the attributes are lower-cased

 * in the hash table, and the name of the tag is case insensitive.

 *

 * @param needle	  The name of the tag

 * @param haystack	  The null-delimited string to search in

 * @param start		  A pointer to the start of the tag if found

 * @param end		  A pointer to the end of the tag if found

 * @param attributes  The attributes, if the tag was found.  This should

 *                    be freed with g_datalist_clear().

 * @return TRUE if the tag was found

 */

gboolean purple_markup_find_tag(const char *needle, const char *haystack,

							  const char **start, const char **end,

							  GData **attributes);

/**

 * Extracts a field of data from HTML.

 *

 * This is a scary function. See protocols/msn/msn.c and

 * protocols/yahoo/yahoo_profile.c for example usage.

 *

 * @param str            The string to parse.

 * @param len            The size of str.

 * @param user_info      The destination PurpleNotifyUserInfo to which the new

 *                       field info should be added.

 * @param start_token    The beginning token.

 * @param skip           The number of characters to skip after the

 *                       start token.

 * @param end_token      The ending token.

 * @param check_value    The value that the last character must meet.

 * @param no_value_token The token indicating no value is given.

 * @param display_name   The short descriptive name to display for this token.

 * @param is_link        TRUE if this should be a link, or FALSE otherwise.

 * @param link_prefix    The prefix for the link.

 * @param format_cb      A callback to format the value before adding it.

 *

 * @return TRUE if successful, or FALSE otherwise.

 */

gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info,

                                        const char *start_token, int skip,

                                        const char *end_token, char check_value,

                                        const char *no_value_token,

                                        const char *display_name, gboolean is_link,

                                        const char *link_prefix,

					PurpleInfoFieldFormatCallback format_cb);

/**

 * Converts HTML markup to XHTML.

 *

 * @param html       The HTML markup.

 * @param dest_xhtml The destination XHTML output.

 * @param dest_plain The destination plain-text output.

 */

void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,

							   char **dest_plain);

/**

 * Strips HTML tags from a string.

 *

 * @param str The string to strip HTML from.

 *

 * @return The new string without HTML.  You must g_free this string

 *         when finished with it.

 */

char *purple_markup_strip_html(const char *str);

/**

 * Adds the necessary HTML code to turn URIs into HTML links in a string.

 *

 * @param str The string to linkify.

 *

 * @return The new string with all URIs surrounded in standard

 *         HTML <a href="whatever"></a> tags.  You must g_free this

 *         string when finished with it.

 */

char *purple_markup_linkify(const char *str);

/**

 * Unescapes HTML entities to their literal characters. Also translates

 * "<br>" to "\n".

 * For example "&" is replaced by '&' and so on.

 * Actually only "&", """, "<" and ">" are currently

 * supported.

 *

 * @param html The string in which to unescape any HTML entities

 *

 * @return The text with HTML entities literalized.  You must g_free

 *         this string when finished with it.

 */

char *purple_unescape_html(const char *html);

/**

 * Returns a newly allocated substring of the HTML UTF-8 string "str".

 * The markup is preserved such that the substring will have the same

 * formatting as original string, even though some tags may have been

 * opened before "x", or may close after "y". All open tags are closed

 * at the end of the returned string, in the proper order.

 *

 * Note that x and y are in character offsets, not byte offsets, and

 * are offsets into an unformatted version of str. Because of this,

 * this function may be sensitive to changes in GtkIMHtml and may break

 * when used with other UI's. libpurple users are encouraged to report and

 * work out any problems encountered.

 *

 * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string.

 * @param x The character offset into an unformatted version of str to

 *          begin at.

 * @param y The character offset (into an unformatted vesion of str) of

 *          one past the last character to include in the slice.

 *

 * @return The HTML slice of string, with all formatting retained.

 */

char *purple_markup_slice(const char *str, guint x, guint y);

/**

 * Returns a newly allocated string containing the name of the tag

 * located at "tag". Tag is expected to point to a '<', and contain

 * a '>' sometime after that. If there is no '>' and the string is

 * not NUL terminated, this function can be expected to segfault.

 *

 * @param tag The string starting a HTML tag.

 * @return A string containing the name of the tag.

 */

char *purple_markup_get_tag_name(const char *tag);

/**

 * Returns a constant string of the character representation of the HTML

 * entity pointed to by @a text. For example, purple_markup_unescape_entity("&")

 * will return "&". The @a text variable is expected to point to an '&',

 * the first character of the entity. If given an unrecognized entity, the function

 * returns @c NULL.

 *

 * Note that this function, unlike purple_unescape_html(), does not search

 * the string for the entity, does not replace the entity, and does not

 * return a newly allocated string.

 *

 * @param text   A string containing an HTML entity.

 * @param length If not @c NULL, the string length of the entity is stored in this location.

 *

 * @return A constant string containing the character representation of the given entity.

 */

const char * purple_markup_unescape_entity(const char *text, int *length);

/**

 * Returns a newly allocated string containing the value of the CSS property specified

 * in opt. The @a style argument is expected to point to a HTML inline CSS.

 * The function will seek for the CSS property and return its value.

 *

 * For example, purple_markup_get_css_property("direction:rtl;color:#dc4d1b;",

 * "color") would return "#dc4d1b".

 *

 * On error or if the requested property was not found, the function returns

 * @c NULL.

 *

 * @param style A string containing the inline CSS text.

 * @param opt   The requested CSS property.

 *

 * @return The value of the requested CSS property.

 */

char * purple_markup_get_css_property(const gchar *style, const gchar *opt);

/**

 * Check if the given HTML contains RTL text.

 *

 * @param html  The HTML text.

 *

 * @return  TRUE if the text contains RTL text, FALSE otherwise.

 *

 * @since 2.6.0

 */

gboolean purple_markup_is_rtl(const char *html);

/*@}*/

/**************************************************************************/

/** @name Path/Filename Functions                                         */

/**************************************************************************/

/*@{*/

/**

 * Returns the user's home directory.

 *

 * @return The user's home directory.

 *

 * @see purple_user_dir()

 */

const gchar *purple_home_dir(void);

/**

 * Returns the purple settings directory in the user's home directory.

 * This is usually ~/.purple

 *

 * @return The purple settings directory.

 *

 * @see purple_home_dir()

 */

const char *purple_user_dir(void);

/**

 * Define a custom purple settings directory, overriding the default (user's home directory/.purple)

 * @param dir The custom settings directory

 */

void purple_util_set_user_dir(const char *dir);

/**

 * Builds a complete path from the root, making any directories along

 * the path which do not already exist.

 *

 * @param path The path you wish to create.  Note that it must start

 *        from the root or this function will fail.

 * @param mode Unix-style permissions for this directory.

 *

 * @return 0 for success, nonzero on any error.

 */

int purple_build_dir(const char *path, int mode);

/**

 * Write a string of data to a file of the given name in the Purple

 * user directory ($HOME/.purple by default).  The data is typically

 * a serialized version of one of Purple's config files, such as

 * prefs.xml, accounts.xml, etc.  And the string is typically

 * obtained using xmlnode_to_formatted_str.  However, this function

 * should work fine for saving binary files as well.

 *

 * @param filename The basename of the file to write in the purple_user_dir.

 * @param data     A null-terminated string of data to write.

 * @param size     The size of the data to save.  If data is

 *                 null-terminated you can pass in -1.

 *

 * @return TRUE if the file was written successfully.  FALSE otherwise.

 */

gboolean purple_util_write_data_to_file(const char *filename, const char *data,

									  gssize size);

/**

 * Write data to a file using the absolute path.

 *

 * This exists for Glib backwards compatibility reasons.

 *

 * @param filename_full Filename to write to

 * @param data          A null-terminated string of data to write.

 * @param size          The size of the data to save.  If data is

 *                      null-terminated you can pass in -1.

 *

 * @return TRUE if the file was written successfully.  FALSE otherwise.

 *

 * @todo Remove this function (use g_file_set_contents instead) when 3.0.0

 *       rolls around.

 * @see purple_util_write_data_to_file()

 *

 */

gboolean

purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size);

/**

 * Read the contents of a given file and parse the results into an

 * xmlnode tree structure.  This is intended to be used to read

 * Purple's configuration xml files (prefs.xml, pounces.xml, etc.)

 *

 * @param filename    The basename of the file to open in the purple_user_dir.

 * @param description A very short description of the contents of this

 *                    file.  This is used in error messages shown to the

 *                    user when the file can not be opened.  For example,

 *                    "preferences," or "buddy pounces."

 *

 * @return An xmlnode tree of the contents of the given file.  Or NULL, if

 *         the file does not exist or there was an error reading the file.

 */

xmlnode *purple_util_read_xml_from_file(const char *filename,

									  const char *description);

/**

 * Creates a temporary file and returns a file pointer to it.

 *

 * This is like mkstemp(), but returns a file pointer and uses a

 * pre-set template. It uses the semantics of tempnam() for the

 * directory to use and allocates the space for the file path.

 *

 * The caller is responsible for closing the file and removing it when

 * done, as well as freeing the space pointed to by @a path with

 * g_free().

 *

 * @param path   The returned path to the temp file.

 * @param binary Text or binary, for platforms where it matters.

 *

 * @return A file pointer to the temporary file, or @c NULL on failure.

 */

FILE *purple_mkstemp(char **path, gboolean binary);

/**

 * Returns an extension corresponding to the image data's file type.

 *

 * @param data A pointer to the image data

 * @param len  The length of the image data

 *

 * @return The appropriate extension, or "icon" if unknown.

 */

const char *

purple_util_get_image_extension(gconstpointer data, size_t len);

/**

 * Returns a SHA-1 hash string of the data passed in.

 */

char *purple_util_get_image_checksum(gconstpointer image_data, size_t image_len);

/**

 * @return A hex encoded version of the SHA-1 hash of the data passed

 *         in with the correct file extention appended.  The file

 *         extension is determined by calling

 *         purple_util_get_image_extension().  This return value must

 *         be g_freed by the caller.

 */

char *purple_util_get_image_filename(gconstpointer image_data, size_t image_len);

/*@}*/

/**************************************************************************/

/** @name Environment Detection Functions                                 */

/**************************************************************************/

/*@{*/

/**

 * Checks if the given program name is valid and executable.

 *

 * @param program The file name of the application.

 *

 * @return TRUE if the program is runable.

 */

gboolean purple_program_is_valid(const char *program);

/**

 * Check if running GNOME.

 *

 * @return TRUE if running GNOME, FALSE otherwise.

 */

gboolean purple_running_gnome(void);

/**

 * Check if running KDE.

 *

 * @return TRUE if running KDE, FALSE otherwise.

 */

gboolean purple_running_kde(void);

/**

 * Check if running OS X.

 *

 * @return TRUE if running OS X, FALSE otherwise.

 */

gboolean purple_running_osx(void);

/**

 * Returns the IP address from a socket file descriptor.

 *

 * @param fd The socket file descriptor.

 *

 * @return The IP address, or @c NULL on error.

 */

char *purple_fd_get_ip(int fd);

/*@}*/

/**************************************************************************/

/** @name String Functions                                                */

/**************************************************************************/

/*@{*/

/**

 * Tests two strings for equality.

 *

 * Unlike strcmp(), this function will not crash if one or both of the

 * strings are @c NULL.

 *

 * @param left	A string

 * @param right A string to compare with left

 *

 * @return @c TRUE if the strings are the same, else @c FALSE.

 *

 * @since 2.6.0

 */

gboolean purple_strequal(const gchar *left, const gchar *right);

/**

 * Normalizes a string, so that it is suitable for comparison.

 *

 * The returned string will point to a static buffer, so if the

 * string is intended to be kept long-term, you <i>must</i>

 * g_strdup() it. Also, calling normalize() twice in the same line

 * will lead to problems.