1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/util.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,1430 @@
1.4 +/**
1.5 + * @file util.h Utility Functions
1.6 + * @ingroup core
1.7 + */
1.8 +
1.9 +/* purple
1.10 + *
1.11 + * Purple is the legal property of its developers, whose names are too numerous
1.12 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.13 + * source distribution.
1.14 + *
1.15 + * This program is free software; you can redistribute it and/or modify
1.16 + * it under the terms of the GNU General Public License as published by
1.17 + * the Free Software Foundation; either version 2 of the License, or
1.18 + * (at your option) any later version.
1.19 + *
1.20 + * This program is distributed in the hope that it will be useful,
1.21 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.22 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.23 + * GNU General Public License for more details.
1.24 + *
1.25 + * You should have received a copy of the GNU General Public License
1.26 + * along with this program; if not, write to the Free Software
1.27 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.28 + *
1.29 + * @todo Rename the functions so that they live somewhere in the purple
1.30 + * namespace.
1.31 + */
1.32 +#ifndef _PURPLE_UTIL_H_
1.33 +#define _PURPLE_UTIL_H_
1.34 +
1.35 +#include <stdio.h>
1.36 +
1.37 +typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData;
1.38 +typedef struct _PurpleMenuAction PurpleMenuAction;
1.39 +typedef struct _PurpleKeyValuePair PurpleKeyValuePair;
1.40 +
1.41 +#include "account.h"
1.42 +#include "xmlnode.h"
1.43 +#include "notify.h"
1.44 +
1.45 +
1.46 +#ifdef __cplusplus
1.47 +extern "C" {
1.48 +#endif
1.49 +
1.50 +struct _PurpleMenuAction
1.51 +{
1.52 + char *label;
1.53 + PurpleCallback callback;
1.54 + gpointer data;
1.55 + GList *children;
1.56 +};
1.57 +
1.58 +typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);
1.59 +
1.60 +/**
1.61 + * A key-value pair.
1.62 + *
1.63 + * This is used by, among other things, purple_gtk_combo* functions to pass in a
1.64 + * list of key-value pairs so it can display a user-friendly value.
1.65 + */
1.66 +struct _PurpleKeyValuePair
1.67 +{
1.68 + gchar *key;
1.69 + void *value;
1.70 +
1.71 +};
1.72 +
1.73 +/**
1.74 + * Creates a new PurpleMenuAction.
1.75 + *
1.76 + * @param label The text label to display for this action.
1.77 + * @param callback The function to be called when the action is used on
1.78 + * the selected item.
1.79 + * @param data Additional data to be passed to the callback.
1.80 + * @param children A GList of PurpleMenuActions to be added as a submenu
1.81 + * of the action.
1.82 + * @return The PurpleMenuAction.
1.83 + */
1.84 +PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback,
1.85 + gpointer data, GList *children);
1.86 +
1.87 +/**
1.88 + * Frees a PurpleMenuAction
1.89 + *
1.90 + * @param act The PurpleMenuAction to free.
1.91 + */
1.92 +void purple_menu_action_free(PurpleMenuAction *act);
1.93 +
1.94 +/**
1.95 + * Set the appropriate presence values for the currently playing song.
1.96 + *
1.97 + * @param title The title of the song, @c NULL to unset the value.
1.98 + * @param artist The artist of the song, can be @c NULL.
1.99 + * @param album The album of the song, can be @c NULL.
1.100 + * @since 2.4.0
1.101 + */
1.102 +void purple_util_set_current_song(const char *title, const char *artist,
1.103 + const char *album);
1.104 +
1.105 +/**
1.106 + * Format song information.
1.107 + *
1.108 + * @param title The title of the song, @c NULL to unset the value.
1.109 + * @param artist The artist of the song, can be @c NULL.
1.110 + * @param album The album of the song, can be @c NULL.
1.111 + * @param unused Currently unused, must be @c NULL.
1.112 + *
1.113 + * @return The formatted string. The caller must #g_free the returned string.
1.114 + * @since 2.4.0
1.115 + */
1.116 +char * purple_util_format_song_info(const char *title, const char *artist,
1.117 + const char *album, gpointer unused);
1.118 +
1.119 +/**************************************************************************/
1.120 +/** @name Utility Subsystem */
1.121 +/**************************************************************************/
1.122 +/*@{*/
1.123 +
1.124 +/**
1.125 + * Initializes the utility subsystem.
1.126 + *
1.127 + * @since 2.3.0
1.128 + */
1.129 +void purple_util_init(void);
1.130 +
1.131 +/**
1.132 + * Uninitializes the util subsystem.
1.133 + *
1.134 + * @since 2.3.0
1.135 + */
1.136 +void purple_util_uninit(void);
1.137 +
1.138 +/*@}*/
1.139 +
1.140 +/**************************************************************************/
1.141 +/** @name Base16 Functions */
1.142 +/**************************************************************************/
1.143 +/*@{*/
1.144 +
1.145 +/**
1.146 + * Converts a chunk of binary data to its base-16 equivalent.
1.147 + *
1.148 + * @param data The data to convert.
1.149 + * @param len The length of the data.
1.150 + *
1.151 + * @return The base-16 string in the ASCII encoding. Must be
1.152 + * g_free'd when no longer needed.
1.153 + *
1.154 + * @see purple_base16_decode()
1.155 + */
1.156 +gchar *purple_base16_encode(const guchar *data, gsize len);
1.157 +
1.158 +/**
1.159 + * Converts an ASCII string of base-16 encoded data to
1.160 + * the binary equivalent.
1.161 + *
1.162 + * @param str The base-16 string to convert to raw data.
1.163 + * @param ret_len The length of the returned data. You can
1.164 + * pass in NULL if you're sure that you know
1.165 + * the length of the decoded data, or if you
1.166 + * know you'll be able to use strlen to
1.167 + * determine the length, etc.
1.168 + *
1.169 + * @return The raw data. Must be g_free'd when no longer needed.
1.170 + *
1.171 + * @see purple_base16_encode()
1.172 + */
1.173 +guchar *purple_base16_decode(const char *str, gsize *ret_len);
1.174 +
1.175 +/**
1.176 + * Converts a chunk of binary data to a chunked base-16 representation
1.177 + * (handy for key fingerprints)
1.178 + *
1.179 + * Example output: 01:23:45:67:89:AB:CD:EF
1.180 + *
1.181 + * @param data The data to convert.
1.182 + * @param len The length of the data.
1.183 + *
1.184 + * @return The base-16 string in the ASCII chunked encoding. Must be
1.185 + * g_free'd when no longer needed.
1.186 + */
1.187 +gchar *purple_base16_encode_chunked(const guchar *data, gsize len);
1.188 +
1.189 +
1.190 +/*@}*/
1.191 +
1.192 +/**************************************************************************/
1.193 +/** @name Base64 Functions */
1.194 +/**************************************************************************/
1.195 +/*@{*/
1.196 +
1.197 +/**
1.198 + * Converts a chunk of binary data to its base-64 equivalent.
1.199 + *
1.200 + * @param data The data to convert.
1.201 + * @param len The length of the data.
1.202 + *
1.203 + * @return The base-64 string in the ASCII encoding. Must be
1.204 + * g_free'd when no longer needed.
1.205 + *
1.206 + * @see purple_base64_decode()
1.207 + */
1.208 +gchar *purple_base64_encode(const guchar *data, gsize len);
1.209 +
1.210 +/**
1.211 + * Converts an ASCII string of base-64 encoded data to
1.212 + * the binary equivalent.
1.213 + *
1.214 + * @param str The base-64 string to convert to raw data.
1.215 + * @param ret_len The length of the returned data. You can
1.216 + * pass in NULL if you're sure that you know
1.217 + * the length of the decoded data, or if you
1.218 + * know you'll be able to use strlen to
1.219 + * determine the length, etc.
1.220 + *
1.221 + * @return The raw data. Must be g_free'd when no longer needed.
1.222 + *
1.223 + * @see purple_base64_encode()
1.224 + */
1.225 +guchar *purple_base64_decode(const char *str, gsize *ret_len);
1.226 +
1.227 +/*@}*/
1.228 +
1.229 +/**************************************************************************/
1.230 +/** @name Quoted Printable Functions */
1.231 +/**************************************************************************/
1.232 +/*@{*/
1.233 +
1.234 +/**
1.235 + * Converts a quoted printable string back to its readable equivalent.
1.236 + * What is a quoted printable string, you ask? It's an encoding used
1.237 + * to transmit binary data as ASCII. It's intended purpose is to send
1.238 + * emails containing non-ASCII characters. Wikipedia has a pretty good
1.239 + * explanation. Also see RFC 2045.
1.240 + *
1.241 + * @param str The quoted printable ASCII string to convert to raw data.
1.242 + * @param ret_len The length of the returned data.
1.243 + *
1.244 + * @return The readable string. Must be g_free'd when no longer needed.
1.245 + */
1.246 +guchar *purple_quotedp_decode(const char *str, gsize *ret_len);
1.247 +
1.248 +/*@}*/
1.249 +
1.250 +/**************************************************************************/
1.251 +/** @name MIME Functions */
1.252 +/**************************************************************************/
1.253 +/*@{*/
1.254 +
1.255 +/**
1.256 + * Converts a MIME header field string back to its readable equivalent
1.257 + * according to RFC 2047. Basically, a header is plain ASCII and can
1.258 + * contain any number of sections called "encoded-words." The format
1.259 + * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
1.260 + * =? designates the beginning of the encoded-word
1.261 + * ?= designates the end of the encoded-word
1.262 + *
1.263 + * An encoded word is segmented into three pieces by the use of a
1.264 + * question mark. The first piece is the character set, the second
1.265 + * piece is the encoding, and the third piece is the encoded text.
1.266 + *
1.267 + * @param str The ASCII string, possibly containing any number of
1.268 + * encoded-word sections.
1.269 + *
1.270 + * @return The string, with any encoded-word sections decoded and
1.271 + * converted to UTF-8. Must be g_free'd when no longer
1.272 + * needed.
1.273 + */
1.274 +char *purple_mime_decode_field(const char *str);
1.275 +
1.276 +/*@}*/
1.277 +
1.278 +
1.279 +/**************************************************************************/
1.280 +/** @name Date/Time Functions */
1.281 +/**************************************************************************/
1.282 +/*@{*/
1.283 +
1.284 +/**
1.285 + * Formats a time into the specified format.
1.286 + *
1.287 + * This is essentially strftime(), but it has a static buffer
1.288 + * and handles the UTF-8 conversion for the caller.
1.289 + *
1.290 + * This function also provides the GNU %z formatter if the underlying C
1.291 + * library doesn't. However, the format string parser is very naive, which
1.292 + * means that conversions specifiers to %z cannot be guaranteed. The GNU
1.293 + * strftime(3) man page describes %z as: 'The time-zone as hour offset from
1.294 + * GMT. Required to emit RFC822-conformant dates
1.295 + * (using "%a, %d %b %Y %H:%M:%S %z"). (GNU)'
1.296 + *
1.297 + * On Windows, this function also converts the results for %Z from a timezone
1.298 + * name (as returned by the system strftime() %Z format string) to a timezone
1.299 + * abbreviation (as is the case on Unix). As with %z, conversion specifiers
1.300 + * should not be used.
1.301 + *
1.302 + * @param format The format string, in UTF-8
1.303 + * @param tm The time to format, or @c NULL to use the current local time
1.304 + *
1.305 + * @return The formatted time, in UTF-8.
1.306 + *
1.307 + * @note @a format is required to be in UTF-8. This differs from strftime(),
1.308 + * where the format is provided in the locale charset.
1.309 + */
1.310 +const char *purple_utf8_strftime(const char *format, const struct tm *tm);
1.311 +
1.312 +/**
1.313 + * Gets a string representation of the local timezone offset
1.314 + *
1.315 + * @param tm The time to get the timezone for
1.316 + * @param iso TRUE to format the offset according to ISO-8601, FALSE to
1.317 + * not substitute 'Z' for 0 offset, and to not separate
1.318 + * hours and minutes with a colon.
1.319 + */
1.320 +const char *purple_get_tzoff_str(const struct tm *tm, gboolean iso);
1.321 +
1.322 +/**
1.323 + * Formats a time into the user's preferred short date format.
1.324 + *
1.325 + * The returned string is stored in a static buffer, so the result
1.326 + * should be g_strdup()'d if it's going to be kept.
1.327 + *
1.328 + * @param tm The time to format, or @c NULL to use the current local time
1.329 + *
1.330 + * @return The date, formatted as per the user's settings.
1.331 + */
1.332 +const char *purple_date_format_short(const struct tm *tm);
1.333 +
1.334 +/**
1.335 + * Formats a time into the user's preferred short date plus time format.
1.336 + *
1.337 + * The returned string is stored in a static buffer, so the result
1.338 + * should be g_strdup()'d if it's going to be kept.
1.339 + *
1.340 + * @param tm The time to format, or @c NULL to use the current local time
1.341 + *
1.342 + * @return The timestamp, formatted as per the user's settings.
1.343 + */
1.344 +const char *purple_date_format_long(const struct tm *tm);
1.345 +
1.346 +/**
1.347 + * Formats a time into the user's preferred full date and time format.
1.348 + *
1.349 + * The returned string is stored in a static buffer, so the result
1.350 + * should be g_strdup()'d if it's going to be kept.
1.351 + *
1.352 + * @param tm The time to format, or @c NULL to use the current local time
1.353 + *
1.354 + * @return The date and time, formatted as per the user's settings.
1.355 + */
1.356 +const char *purple_date_format_full(const struct tm *tm);
1.357 +
1.358 +/**
1.359 + * Formats a time into the user's preferred time format.
1.360 + *
1.361 + * The returned string is stored in a static buffer, so the result
1.362 + * should be g_strdup()'d if it's going to be kept.
1.363 + *
1.364 + * @param tm The time to format, or @c NULL to use the current local time
1.365 + *
1.366 + * @return The time, formatted as per the user's settings.
1.367 + */
1.368 +const char *purple_time_format(const struct tm *tm);
1.369 +
1.370 +/**
1.371 + * Builds a time_t from the supplied information.
1.372 + *
1.373 + * @param year The year.
1.374 + * @param month The month.
1.375 + * @param day The day.
1.376 + * @param hour The hour.
1.377 + * @param min The minute.
1.378 + * @param sec The second.
1.379 + *
1.380 + * @return A time_t.
1.381 + */
1.382 +time_t purple_time_build(int year, int month, int day, int hour,
1.383 + int min, int sec);
1.384 +
1.385 +/** Used by purple_str_to_time to indicate no timezone offset was
1.386 + * specified in the timestamp string. */
1.387 +#define PURPLE_NO_TZ_OFF -500000
1.388 +
1.389 +/**
1.390 + * Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns
1.391 + * a time_t.
1.392 + *
1.393 + * @param timestamp The timestamp
1.394 + * @param utc Assume UTC if no timezone specified
1.395 + * @param tm If not @c NULL, the caller can get a copy of the
1.396 + * struct tm used to calculate the time_t return value.
1.397 + * @param tz_off If not @c NULL, the caller can get a copy of the
1.398 + * timezone offset (from UTC) used to calculate the time_t
1.399 + * return value. Note: Zero is a valid offset. As such,
1.400 + * the value of the macro @c PURPLE_NO_TZ_OFF indicates no
1.401 + * offset was specified (which means that the local
1.402 + * timezone was used in the calculation).
1.403 + * @param rest If not @c NULL, the caller can get a pointer to the
1.404 + * part of @a timestamp left over after parsing is
1.405 + * completed, if it's not the end of @a timestamp.
1.406 + *
1.407 + * @return A time_t.
1.408 + */
1.409 +time_t purple_str_to_time(const char *timestamp, gboolean utc,
1.410 + struct tm *tm, long *tz_off, const char **rest);
1.411 +
1.412 +/*@}*/
1.413 +
1.414 +
1.415 +/**************************************************************************/
1.416 +/** @name Markup Functions */
1.417 +/**************************************************************************/
1.418 +/*@{*/
1.419 +
1.420 +/**
1.421 + * Escapes special characters in a plain-text string so they display
1.422 + * correctly as HTML. For example, & is replaced with & and < is
1.423 + * replaced with <
1.424 + *
1.425 + * This is exactly the same as g_markup_escape_text(), except that it
1.426 + * does not change ' to ' because ' is not a valid HTML 4 entity,
1.427 + * and is displayed literally in IE7.
1.428 + *
1.429 + * @since 2.6.0
1.430 + */
1.431 +gchar *purple_markup_escape_text(const gchar *text, gssize length);
1.432 +
1.433 +/**
1.434 + * Finds an HTML tag matching the given name.
1.435 + *
1.436 + * This locates an HTML tag's start and end, and stores its attributes
1.437 + * in a GData hash table. The names of the attributes are lower-cased
1.438 + * in the hash table, and the name of the tag is case insensitive.
1.439 + *
1.440 + * @param needle The name of the tag
1.441 + * @param haystack The null-delimited string to search in
1.442 + * @param start A pointer to the start of the tag if found
1.443 + * @param end A pointer to the end of the tag if found
1.444 + * @param attributes The attributes, if the tag was found. This should
1.445 + * be freed with g_datalist_clear().
1.446 + * @return TRUE if the tag was found
1.447 + */
1.448 +gboolean purple_markup_find_tag(const char *needle, const char *haystack,
1.449 + const char **start, const char **end,
1.450 + GData **attributes);
1.451 +
1.452 +/**
1.453 + * Extracts a field of data from HTML.
1.454 + *
1.455 + * This is a scary function. See protocols/msn/msn.c and
1.456 + * protocols/yahoo/yahoo_profile.c for example usage.
1.457 + *
1.458 + * @param str The string to parse.
1.459 + * @param len The size of str.
1.460 + * @param user_info The destination PurpleNotifyUserInfo to which the new
1.461 + * field info should be added.
1.462 + * @param start_token The beginning token.
1.463 + * @param skip The number of characters to skip after the
1.464 + * start token.
1.465 + * @param end_token The ending token.
1.466 + * @param check_value The value that the last character must meet.
1.467 + * @param no_value_token The token indicating no value is given.
1.468 + * @param display_name The short descriptive name to display for this token.
1.469 + * @param is_link TRUE if this should be a link, or FALSE otherwise.
1.470 + * @param link_prefix The prefix for the link.
1.471 + * @param format_cb A callback to format the value before adding it.
1.472 + *
1.473 + * @return TRUE if successful, or FALSE otherwise.
1.474 + */
1.475 +gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info,
1.476 + const char *start_token, int skip,
1.477 + const char *end_token, char check_value,
1.478 + const char *no_value_token,
1.479 + const char *display_name, gboolean is_link,
1.480 + const char *link_prefix,
1.481 + PurpleInfoFieldFormatCallback format_cb);
1.482 +
1.483 +/**
1.484 + * Converts HTML markup to XHTML.
1.485 + *
1.486 + * @param html The HTML markup.
1.487 + * @param dest_xhtml The destination XHTML output.
1.488 + * @param dest_plain The destination plain-text output.
1.489 + */
1.490 +void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,
1.491 + char **dest_plain);
1.492 +
1.493 +/**
1.494 + * Strips HTML tags from a string.
1.495 + *
1.496 + * @param str The string to strip HTML from.
1.497 + *
1.498 + * @return The new string without HTML. You must g_free this string
1.499 + * when finished with it.
1.500 + */
1.501 +char *purple_markup_strip_html(const char *str);
1.502 +
1.503 +/**
1.504 + * Adds the necessary HTML code to turn URIs into HTML links in a string.
1.505 + *
1.506 + * @param str The string to linkify.
1.507 + *
1.508 + * @return The new string with all URIs surrounded in standard
1.509 + * HTML <a href="whatever"></a> tags. You must g_free this
1.510 + * string when finished with it.
1.511 + */
1.512 +char *purple_markup_linkify(const char *str);
1.513 +
1.514 +/**
1.515 + * Unescapes HTML entities to their literal characters. Also translates
1.516 + * "<br>" to "\n".
1.517 + * For example "&" is replaced by '&' and so on.
1.518 + * Actually only "&", """, "<" and ">" are currently
1.519 + * supported.
1.520 + *
1.521 + * @param html The string in which to unescape any HTML entities
1.522 + *
1.523 + * @return The text with HTML entities literalized. You must g_free
1.524 + * this string when finished with it.
1.525 + */
1.526 +char *purple_unescape_html(const char *html);
1.527 +
1.528 +/**
1.529 + * Returns a newly allocated substring of the HTML UTF-8 string "str".
1.530 + * The markup is preserved such that the substring will have the same
1.531 + * formatting as original string, even though some tags may have been
1.532 + * opened before "x", or may close after "y". All open tags are closed
1.533 + * at the end of the returned string, in the proper order.
1.534 + *
1.535 + * Note that x and y are in character offsets, not byte offsets, and
1.536 + * are offsets into an unformatted version of str. Because of this,
1.537 + * this function may be sensitive to changes in GtkIMHtml and may break
1.538 + * when used with other UI's. libpurple users are encouraged to report and
1.539 + * work out any problems encountered.
1.540 + *
1.541 + * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string.
1.542 + * @param x The character offset into an unformatted version of str to
1.543 + * begin at.
1.544 + * @param y The character offset (into an unformatted vesion of str) of
1.545 + * one past the last character to include in the slice.
1.546 + *
1.547 + * @return The HTML slice of string, with all formatting retained.
1.548 + */
1.549 +char *purple_markup_slice(const char *str, guint x, guint y);
1.550 +
1.551 +/**
1.552 + * Returns a newly allocated string containing the name of the tag
1.553 + * located at "tag". Tag is expected to point to a '<', and contain
1.554 + * a '>' sometime after that. If there is no '>' and the string is
1.555 + * not NUL terminated, this function can be expected to segfault.
1.556 + *
1.557 + * @param tag The string starting a HTML tag.
1.558 + * @return A string containing the name of the tag.
1.559 + */
1.560 +char *purple_markup_get_tag_name(const char *tag);
1.561 +
1.562 +/**
1.563 + * Returns a constant string of the character representation of the HTML
1.564 + * entity pointed to by @a text. For example, purple_markup_unescape_entity("&")
1.565 + * will return "&". The @a text variable is expected to point to an '&',
1.566 + * the first character of the entity. If given an unrecognized entity, the function
1.567 + * returns @c NULL.
1.568 + *
1.569 + * Note that this function, unlike purple_unescape_html(), does not search
1.570 + * the string for the entity, does not replace the entity, and does not
1.571 + * return a newly allocated string.
1.572 + *
1.573 + * @param text A string containing an HTML entity.
1.574 + * @param length If not @c NULL, the string length of the entity is stored in this location.
1.575 + *
1.576 + * @return A constant string containing the character representation of the given entity.
1.577 + */
1.578 +const char * purple_markup_unescape_entity(const char *text, int *length);
1.579 +
1.580 +/**
1.581 + * Returns a newly allocated string containing the value of the CSS property specified
1.582 + * in opt. The @a style argument is expected to point to a HTML inline CSS.
1.583 + * The function will seek for the CSS property and return its value.
1.584 + *
1.585 + * For example, purple_markup_get_css_property("direction:rtl;color:#dc4d1b;",
1.586 + * "color") would return "#dc4d1b".
1.587 + *
1.588 + * On error or if the requested property was not found, the function returns
1.589 + * @c NULL.
1.590 + *
1.591 + * @param style A string containing the inline CSS text.
1.592 + * @param opt The requested CSS property.
1.593 + *
1.594 + * @return The value of the requested CSS property.
1.595 + */
1.596 +char * purple_markup_get_css_property(const gchar *style, const gchar *opt);
1.597 +
1.598 +/**
1.599 + * Check if the given HTML contains RTL text.
1.600 + *
1.601 + * @param html The HTML text.
1.602 + *
1.603 + * @return TRUE if the text contains RTL text, FALSE otherwise.
1.604 + *
1.605 + * @since 2.6.0
1.606 + */
1.607 +gboolean purple_markup_is_rtl(const char *html);
1.608 +
1.609 +/*@}*/
1.610 +
1.611 +
1.612 +/**************************************************************************/
1.613 +/** @name Path/Filename Functions */
1.614 +/**************************************************************************/
1.615 +/*@{*/
1.616 +
1.617 +/**
1.618 + * Returns the user's home directory.
1.619 + *
1.620 + * @return The user's home directory.
1.621 + *
1.622 + * @see purple_user_dir()
1.623 + */
1.624 +const gchar *purple_home_dir(void);
1.625 +
1.626 +/**
1.627 + * Returns the purple settings directory in the user's home directory.
1.628 + * This is usually ~/.purple
1.629 + *
1.630 + * @return The purple settings directory.
1.631 + *
1.632 + * @see purple_home_dir()
1.633 + */
1.634 +const char *purple_user_dir(void);
1.635 +
1.636 +/**
1.637 + * Define a custom purple settings directory, overriding the default (user's home directory/.purple)
1.638 + * @param dir The custom settings directory
1.639 + */
1.640 +void purple_util_set_user_dir(const char *dir);
1.641 +
1.642 +/**
1.643 + * Builds a complete path from the root, making any directories along
1.644 + * the path which do not already exist.
1.645 + *
1.646 + * @param path The path you wish to create. Note that it must start
1.647 + * from the root or this function will fail.
1.648 + * @param mode Unix-style permissions for this directory.
1.649 + *
1.650 + * @return 0 for success, nonzero on any error.
1.651 + */
1.652 +int purple_build_dir(const char *path, int mode);
1.653 +
1.654 +/**
1.655 + * Write a string of data to a file of the given name in the Purple
1.656 + * user directory ($HOME/.purple by default). The data is typically
1.657 + * a serialized version of one of Purple's config files, such as
1.658 + * prefs.xml, accounts.xml, etc. And the string is typically
1.659 + * obtained using xmlnode_to_formatted_str. However, this function
1.660 + * should work fine for saving binary files as well.
1.661 + *
1.662 + * @param filename The basename of the file to write in the purple_user_dir.
1.663 + * @param data A null-terminated string of data to write.
1.664 + * @param size The size of the data to save. If data is
1.665 + * null-terminated you can pass in -1.
1.666 + *
1.667 + * @return TRUE if the file was written successfully. FALSE otherwise.
1.668 + */
1.669 +gboolean purple_util_write_data_to_file(const char *filename, const char *data,
1.670 + gssize size);
1.671 +
1.672 +/**
1.673 + * Write data to a file using the absolute path.
1.674 + *
1.675 + * This exists for Glib backwards compatibility reasons.
1.676 + *
1.677 + * @param filename_full Filename to write to
1.678 + * @param data A null-terminated string of data to write.
1.679 + * @param size The size of the data to save. If data is
1.680 + * null-terminated you can pass in -1.
1.681 + *
1.682 + * @return TRUE if the file was written successfully. FALSE otherwise.
1.683 + *
1.684 + * @todo Remove this function (use g_file_set_contents instead) when 3.0.0
1.685 + * rolls around.
1.686 + * @see purple_util_write_data_to_file()
1.687 + *
1.688 + */
1.689 +gboolean
1.690 +purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size);
1.691 +
1.692 +/**
1.693 + * Read the contents of a given file and parse the results into an
1.694 + * xmlnode tree structure. This is intended to be used to read
1.695 + * Purple's configuration xml files (prefs.xml, pounces.xml, etc.)
1.696 + *
1.697 + * @param filename The basename of the file to open in the purple_user_dir.
1.698 + * @param description A very short description of the contents of this
1.699 + * file. This is used in error messages shown to the
1.700 + * user when the file can not be opened. For example,
1.701 + * "preferences," or "buddy pounces."
1.702 + *
1.703 + * @return An xmlnode tree of the contents of the given file. Or NULL, if
1.704 + * the file does not exist or there was an error reading the file.
1.705 + */
1.706 +xmlnode *purple_util_read_xml_from_file(const char *filename,
1.707 + const char *description);
1.708 +
1.709 +/**
1.710 + * Creates a temporary file and returns a file pointer to it.
1.711 + *
1.712 + * This is like mkstemp(), but returns a file pointer and uses a
1.713 + * pre-set template. It uses the semantics of tempnam() for the
1.714 + * directory to use and allocates the space for the file path.
1.715 + *
1.716 + * The caller is responsible for closing the file and removing it when
1.717 + * done, as well as freeing the space pointed to by @a path with
1.718 + * g_free().
1.719 + *
1.720 + * @param path The returned path to the temp file.
1.721 + * @param binary Text or binary, for platforms where it matters.
1.722 + *
1.723 + * @return A file pointer to the temporary file, or @c NULL on failure.
1.724 + */
1.725 +FILE *purple_mkstemp(char **path, gboolean binary);
1.726 +
1.727 +/**
1.728 + * Returns an extension corresponding to the image data's file type.
1.729 + *
1.730 + * @param data A pointer to the image data
1.731 + * @param len The length of the image data
1.732 + *
1.733 + * @return The appropriate extension, or "icon" if unknown.
1.734 + */
1.735 +const char *
1.736 +purple_util_get_image_extension(gconstpointer data, size_t len);
1.737 +
1.738 +/**
1.739 + * Returns a SHA-1 hash string of the data passed in.
1.740 + */
1.741 +char *purple_util_get_image_checksum(gconstpointer image_data, size_t image_len);
1.742 +
1.743 +/**
1.744 + * @return A hex encoded version of the SHA-1 hash of the data passed
1.745 + * in with the correct file extention appended. The file
1.746 + * extension is determined by calling
1.747 + * purple_util_get_image_extension(). This return value must
1.748 + * be g_freed by the caller.
1.749 + */
1.750 +char *purple_util_get_image_filename(gconstpointer image_data, size_t image_len);
1.751 +
1.752 +/*@}*/
1.753 +
1.754 +
1.755 +/**************************************************************************/
1.756 +/** @name Environment Detection Functions */
1.757 +/**************************************************************************/
1.758 +/*@{*/
1.759 +
1.760 +/**
1.761 + * Checks if the given program name is valid and executable.
1.762 + *
1.763 + * @param program The file name of the application.
1.764 + *
1.765 + * @return TRUE if the program is runable.
1.766 + */
1.767 +gboolean purple_program_is_valid(const char *program);
1.768 +
1.769 +/**
1.770 + * Check if running GNOME.
1.771 + *
1.772 + * @return TRUE if running GNOME, FALSE otherwise.
1.773 + */
1.774 +gboolean purple_running_gnome(void);
1.775 +
1.776 +/**
1.777 + * Check if running KDE.
1.778 + *
1.779 + * @return TRUE if running KDE, FALSE otherwise.
1.780 + */
1.781 +gboolean purple_running_kde(void);
1.782 +
1.783 +/**
1.784 + * Check if running OS X.
1.785 + *
1.786 + * @return TRUE if running OS X, FALSE otherwise.
1.787 + */
1.788 +gboolean purple_running_osx(void);
1.789 +
1.790 +/**
1.791 + * Returns the IP address from a socket file descriptor.
1.792 + *
1.793 + * @param fd The socket file descriptor.
1.794 + *
1.795 + * @return The IP address, or @c NULL on error.
1.796 + */
1.797 +char *purple_fd_get_ip(int fd);
1.798 +
1.799 +/*@}*/
1.800 +
1.801 +
1.802 +/**************************************************************************/
1.803 +/** @name String Functions */
1.804 +/**************************************************************************/
1.805 +/*@{*/
1.806 +
1.807 +/**
1.808 + * Tests two strings for equality.
1.809 + *
1.810 + * Unlike strcmp(), this function will not crash if one or both of the
1.811 + * strings are @c NULL.
1.812 + *
1.813 + * @param left A string
1.814 + * @param right A string to compare with left
1.815 + *
1.816 + * @return @c TRUE if the strings are the same, else @c FALSE.
1.817 + *
1.818 + * @since 2.6.0
1.819 + */
1.820 +gboolean purple_strequal(const gchar *left, const gchar *right);
1.821 +
1.822 +/**
1.823 + * Normalizes a string, so that it is suitable for comparison.
1.824 + *
1.825 + * The returned string will point to a static buffer, so if the
1.826 + * string is intended to be kept long-term, you <i>must</i>
1.827 + * g_strdup() it. Also, calling normalize() twice in the same line
1.828 + * will lead to problems.
1.829 + *
1.830 + * @param account The account the string belongs to, or NULL if you do
1.831 + * not know the account. If you use NULL, the string
1.832 + * will still be normalized, but if the PRPL uses a
1.833 + * custom normalization function then the string may
1.834 + * not be normalized correctly.
1.835 + * @param str The string to normalize.
1.836 + *
1.837 + * @return A pointer to the normalized version stored in a static buffer.
1.838 + */
1.839 +const char *purple_normalize(const PurpleAccount *account, const char *str);
1.840 +
1.841 +/**
1.842 + * Normalizes a string, so that it is suitable for comparison.
1.843 + *
1.844 + * This is one possible implementation for the PRPL callback
1.845 + * function "normalize." It returns a lowercase and UTF-8
1.846 + * normalized version of the string.
1.847 + *
1.848 + * @param account The account the string belongs to.
1.849 + * @param str The string to normalize.
1.850 + *
1.851 + * @return A pointer to the normalized version stored in a static buffer.
1.852 + */
1.853 +const char *purple_normalize_nocase(const PurpleAccount *account, const char *str);
1.854 +
1.855 +/**
1.856 + * Compares two strings to see if the first contains the second as
1.857 + * a proper prefix.
1.858 + *
1.859 + * @param s The string to check.
1.860 + * @param p The prefix in question.
1.861 + *
1.862 + * @return TRUE if p is a prefix of s, otherwise FALSE.
1.863 + */
1.864 +gboolean purple_str_has_prefix(const char *s, const char *p);
1.865 +
1.866 +/**
1.867 + * Compares two strings to see if the second is a proper suffix
1.868 + * of the first.
1.869 + *
1.870 + * @param s The string to check.
1.871 + * @param x The suffix in question.
1.872 + *
1.873 + * @return TRUE if x is a a suffix of s, otherwise FALSE.
1.874 + */
1.875 +gboolean purple_str_has_suffix(const char *s, const char *x);
1.876 +
1.877 +/**
1.878 + * Duplicates a string and replaces all newline characters from the
1.879 + * source string with HTML linebreaks.
1.880 + *
1.881 + * @param src The source string.
1.882 + *
1.883 + * @return The new string. Must be g_free'd by the caller.
1.884 + */
1.885 +gchar *purple_strdup_withhtml(const gchar *src);
1.886 +
1.887 +/**
1.888 + * Ensures that all linefeeds have a matching carriage return.
1.889 + *
1.890 + * @param str The source string.
1.891 + *
1.892 + * @return The string with carriage returns.
1.893 + */
1.894 +char *purple_str_add_cr(const char *str);
1.895 +
1.896 +/**
1.897 + * Strips all instances of the given character from the
1.898 + * given string. The string is modified in place. This
1.899 + * is useful for stripping new line characters, for example.
1.900 + *
1.901 + * Example usage:
1.902 + * purple_str_strip_char(my_dumb_string, '\n');
1.903 + *
1.904 + * @param str The string to strip characters from.
1.905 + * @param thechar The character to strip from the given string.
1.906 + */
1.907 +void purple_str_strip_char(char *str, char thechar);
1.908 +
1.909 +/**
1.910 + * Given a string, this replaces all instances of one character
1.911 + * with another. This happens inline (the original string IS
1.912 + * modified).
1.913 + *
1.914 + * @param string The string from which to replace stuff.
1.915 + * @param delimiter The character you want replaced.
1.916 + * @param replacement The character you want inserted in place
1.917 + * of the delimiting character.
1.918 + */
1.919 +void purple_util_chrreplace(char *string, char delimiter,
1.920 + char replacement);
1.921 +
1.922 +/**
1.923 + * Given a string, this replaces one substring with another
1.924 + * and returns a newly allocated string.
1.925 + *
1.926 + * @param string The string from which to replace stuff.
1.927 + * @param delimiter The substring you want replaced.
1.928 + * @param replacement The substring you want inserted in place
1.929 + * of the delimiting substring.
1.930 + *
1.931 + * @return A new string, after performing the substitution.
1.932 + * free this with g_free().
1.933 + */
1.934 +gchar *purple_strreplace(const char *string, const char *delimiter,
1.935 + const char *replacement);
1.936 +
1.937 +
1.938 +/**
1.939 + * Given a string, this replaces any utf-8 substrings in that string with
1.940 + * the corresponding numerical character reference, and returns a newly
1.941 + * allocated string.
1.942 + *
1.943 + * @param in The string which might contain utf-8 substrings
1.944 + *
1.945 + * @return A new string, with utf-8 replaced with numerical character
1.946 + * references, free this with g_free()
1.947 +*/
1.948 +char *purple_utf8_ncr_encode(const char *in);
1.949 +
1.950 +
1.951 +/**
1.952 + * Given a string, this replaces any numerical character references
1.953 + * in that string with the corresponding actual utf-8 substrings,
1.954 + * and returns a newly allocated string.
1.955 + *
1.956 + * @param in The string which might contain numerical character references.
1.957 + *
1.958 + * @return A new string, with numerical character references
1.959 + * replaced with actual utf-8, free this with g_free().
1.960 + */
1.961 +char *purple_utf8_ncr_decode(const char *in);
1.962 +
1.963 +
1.964 +/**
1.965 + * Given a string, this replaces one substring with another
1.966 + * ignoring case and returns a newly allocated string.
1.967 + *
1.968 + * @param string The string from which to replace stuff.
1.969 + * @param delimiter The substring you want replaced.
1.970 + * @param replacement The substring you want inserted in place
1.971 + * of the delimiting substring.
1.972 + *
1.973 + * @return A new string, after performing the substitution.
1.974 + * free this with g_free().
1.975 + */
1.976 +gchar *purple_strcasereplace(const char *string, const char *delimiter,
1.977 + const char *replacement);
1.978 +
1.979 +/**
1.980 + * This is like strstr, except that it ignores ASCII case in
1.981 + * searching for the substring.
1.982 + *
1.983 + * @param haystack The string to search in.
1.984 + * @param needle The substring to find.
1.985 + *
1.986 + * @return the location of the substring if found, or NULL if not
1.987 + */
1.988 +const char *purple_strcasestr(const char *haystack, const char *needle);
1.989 +
1.990 +/**
1.991 + * Returns a string representing a filesize in the appropriate
1.992 + * units (MB, KB, GB, etc.)
1.993 + *
1.994 + * @param size The size
1.995 + *
1.996 + * @return The string in units form. This must be freed.
1.997 + */
1.998 +char *purple_str_size_to_units(size_t size);
1.999 +
1.1000 +/**
1.1001 + * Converts seconds into a human-readable form.
1.1002 + *
1.1003 + * @param sec The seconds.
1.1004 + *
1.1005 + * @return A human-readable form, containing days, hours, minutes, and
1.1006 + * seconds.
1.1007 + */
1.1008 +char *purple_str_seconds_to_string(guint sec);
1.1009 +
1.1010 +/**
1.1011 + * Converts a binary string into a NUL terminated ascii string,
1.1012 + * replacing nonascii characters and characters below SPACE (including
1.1013 + * NUL) into \\xyy, where yy are two hex digits. Also backslashes are
1.1014 + * changed into two backslashes (\\\\). The returned, newly allocated
1.1015 + * string can be outputted to the console, and must be g_free()d.
1.1016 + *
1.1017 + * @param binary A string of random data, possibly with embedded NULs
1.1018 + * and such.
1.1019 + * @param len The length in bytes of the input string. Must not be 0.
1.1020 + *
1.1021 + * @return A newly allocated ASCIIZ string.
1.1022 + */
1.1023 +char *purple_str_binary_to_ascii(const unsigned char *binary, guint len);
1.1024 +/*@}*/
1.1025 +
1.1026 +
1.1027 +/**************************************************************************/
1.1028 +/** @name URI/URL Functions */
1.1029 +/**************************************************************************/
1.1030 +/*@{*/
1.1031 +
1.1032 +void purple_got_protocol_handler_uri(const char *uri);
1.1033 +
1.1034 +/**
1.1035 + * Parses a URL, returning its host, port, file path, username and password.
1.1036 + *
1.1037 + * The returned data must be freed.
1.1038 + *
1.1039 + * @param url The URL to parse.
1.1040 + * @param ret_host The returned host.
1.1041 + * @param ret_port The returned port.
1.1042 + * @param ret_path The returned path.
1.1043 + * @param ret_user The returned username.
1.1044 + * @param ret_passwd The returned password.
1.1045 + */
1.1046 +gboolean purple_url_parse(const char *url, char **ret_host, int *ret_port,
1.1047 + char **ret_path, char **ret_user, char **ret_passwd);
1.1048 +
1.1049 +/**
1.1050 + * This is the signature used for functions that act as the callback
1.1051 + * to purple_util_fetch_url() or purple_util_fetch_url_request().
1.1052 + *
1.1053 + * @param url_data The same value that was returned when you called
1.1054 + * purple_fetch_url() or purple_fetch_url_request().
1.1055 + * @param user_data The user data that your code passed into either
1.1056 + * purple_util_fetch_url() or purple_util_fetch_url_request().
1.1057 + * @param url_text This will be NULL on error. Otherwise this
1.1058 + * will contain the contents of the URL.
1.1059 + * @param len 0 on error, otherwise this is the length of buf.
1.1060 + * @param error_message If something went wrong then this will contain
1.1061 + * a descriptive error message, and buf will be
1.1062 + * NULL and len will be 0.
1.1063 + */
1.1064 +typedef void (*PurpleUtilFetchUrlCallback)(PurpleUtilFetchUrlData *url_data, gpointer user_data, const gchar *url_text, gsize len, const gchar *error_message);
1.1065 +
1.1066 +/**
1.1067 + * Fetches the data from a URL, and passes it to a callback function.
1.1068 + *
1.1069 + * @param url The URL.
1.1070 + * @param full TRUE if this is the full URL, or FALSE if it's a
1.1071 + * partial URL.
1.1072 + * @param user_agent The user agent field to use, or NULL.
1.1073 + * @param http11 TRUE if HTTP/1.1 should be used to download the file.
1.1074 + * @param cb The callback function.
1.1075 + * @param data The user data to pass to the callback function.
1.1076 + */
1.1077 +#define purple_util_fetch_url(url, full, user_agent, http11, cb, data) \
1.1078 + purple_util_fetch_url_request(url, full, user_agent, http11, NULL, \
1.1079 + FALSE, cb, data);
1.1080 +
1.1081 +/**
1.1082 + * Fetches the data from a URL, and passes it to a callback function.
1.1083 + *
1.1084 + * @param url The URL.
1.1085 + * @param full TRUE if this is the full URL, or FALSE if it's a
1.1086 + * partial URL.
1.1087 + * @param user_agent The user agent field to use, or NULL.
1.1088 + * @param http11 TRUE if HTTP/1.1 should be used to download the file.
1.1089 + * @param max_len The maximum number of bytes to retrieve (-1 for unlimited)
1.1090 + * @param cb The callback function.
1.1091 + * @param data The user data to pass to the callback function.
1.1092 + * @deprecated In 3.0.0, we'll rename this to "purple_util_fetch_url" and get rid of the old one
1.1093 + */
1.1094 +#define purple_util_fetch_url_len(url, full, user_agent, http11, max_len, cb, data) \
1.1095 + purple_util_fetch_url_request_len(url, full, user_agent, http11, NULL, \
1.1096 + FALSE, max_len, cb, data);
1.1097 +
1.1098 +/**
1.1099 + * Fetches the data from a URL, and passes it to a callback function.
1.1100 + *
1.1101 + * @param url The URL.
1.1102 + * @param full TRUE if this is the full URL, or FALSE if it's a
1.1103 + * partial URL.
1.1104 + * @param user_agent The user agent field to use, or NULL.
1.1105 + * @param http11 TRUE if HTTP/1.1 should be used to download the file.
1.1106 + * @param request A HTTP request to send to the server instead of the
1.1107 + * standard GET
1.1108 + * @param include_headers
1.1109 + * If TRUE, include the HTTP headers in the response.
1.1110 + * @param callback The callback function.
1.1111 + * @param data The user data to pass to the callback function.
1.1112 + */
1.1113 +PurpleUtilFetchUrlData *purple_util_fetch_url_request(const gchar *url,
1.1114 + gboolean full, const gchar *user_agent, gboolean http11,
1.1115 + const gchar *request, gboolean include_headers,
1.1116 + PurpleUtilFetchUrlCallback callback, gpointer data);
1.1117 +
1.1118 +/**
1.1119 + * Fetches the data from a URL, and passes it to a callback function.
1.1120 + *
1.1121 + * @param url The URL.
1.1122 + * @param full TRUE if this is the full URL, or FALSE if it's a
1.1123 + * partial URL.
1.1124 + * @param user_agent The user agent field to use, or NULL.
1.1125 + * @param http11 TRUE if HTTP/1.1 should be used to download the file.
1.1126 + * @param request A HTTP request to send to the server instead of the
1.1127 + * standard GET
1.1128 + * @param include_headers
1.1129 + * If TRUE, include the HTTP headers in the response.
1.1130 + * @param max_len The maximum number of bytes to retrieve (-1 for unlimited)
1.1131 + * @param callback The callback function.
1.1132 + * @param data The user data to pass to the callback function.
1.1133 + * @deprecated In 3.0.0, this will go away.
1.1134 + */
1.1135 +PurpleUtilFetchUrlData *purple_util_fetch_url_request_len(const gchar *url,
1.1136 + gboolean full, const gchar *user_agent, gboolean http11,
1.1137 + const gchar *request, gboolean include_headers, gssize max_len,
1.1138 + PurpleUtilFetchUrlCallback callback, gpointer data);
1.1139 +
1.1140 +/**
1.1141 + * Fetches the data from a URL, and passes it to a callback function.
1.1142 + *
1.1143 + * @param account The account for which the request is needed, or NULL.
1.1144 + * @param url The URL.
1.1145 + * @param full TRUE if this is the full URL, or FALSE if it's a
1.1146 + * partial URL.
1.1147 + * @param user_agent The user agent field to use, or NULL.
1.1148 + * @param http11 TRUE if HTTP/1.1 should be used to download the file.
1.1149 + * @param request A HTTP request to send to the server instead of the
1.1150 + * standard GET
1.1151 + * @param include_headers
1.1152 + * If TRUE, include the HTTP headers in the response.
1.1153 + * @param max_len The maximum number of bytes to retrieve (-1 for unlimited)
1.1154 + * @param callback The callback function.
1.1155 + * @param data The user data to pass to the callback function.
1.1156 + * @deprecated In 3.0.0, we'll rename this to "purple_util_fetch_url_request" and get rid of the old one
1.1157 + */
1.1158 +PurpleUtilFetchUrlData *purple_util_fetch_url_request_len_with_account(
1.1159 + PurpleAccount *account, const gchar *url,
1.1160 + gboolean full, const gchar *user_agent, gboolean http11,
1.1161 + const gchar *request, gboolean include_headers, gssize max_len,
1.1162 + PurpleUtilFetchUrlCallback callback, gpointer data);
1.1163 +
1.1164 +/**
1.1165 + * Cancel a pending URL request started with either
1.1166 + * purple_util_fetch_url_request() or purple_util_fetch_url().
1.1167 + *
1.1168 + * @param url_data The data returned when you initiated the URL fetch.
1.1169 + */
1.1170 +void purple_util_fetch_url_cancel(PurpleUtilFetchUrlData *url_data);
1.1171 +
1.1172 +/**
1.1173 + * Decodes a URL into a plain string.
1.1174 + *
1.1175 + * This will change hex codes and such to their ascii equivalents.
1.1176 + *
1.1177 + * @param str The string to translate.
1.1178 + *
1.1179 + * @return The resulting string.
1.1180 + */
1.1181 +const char *purple_url_decode(const char *str);
1.1182 +
1.1183 +/**
1.1184 + * Encodes a URL into an escaped string.
1.1185 + *
1.1186 + * This will change non-alphanumeric characters to hex codes.
1.1187 + *
1.1188 + * @param str The string to translate.
1.1189 + *
1.1190 + * @return The resulting string.
1.1191 + */
1.1192 +const char *purple_url_encode(const char *str);
1.1193 +
1.1194 +/**
1.1195 + * Checks if the given email address is syntactically valid.
1.1196 + *
1.1197 + * @param address The email address to validate.
1.1198 + *
1.1199 + * @return True if the email address is syntactically correct.
1.1200 + */
1.1201 +gboolean purple_email_is_valid(const char *address);
1.1202 +
1.1203 +/**
1.1204 + * Checks if the given IP address is a syntactically valid IPv4 address.
1.1205 + *
1.1206 + * @param ip The IP address to validate.
1.1207 + *
1.1208 + * @return True if the IP address is syntactically correct.
1.1209 + * @deprecated This function will be replaced with one that validates
1.1210 + * as either IPv4 or IPv6 in 3.0.0. If you don't want this,
1.1211 + * behavior, use one of the more specific functions.
1.1212 + */
1.1213 +gboolean purple_ip_address_is_valid(const char *ip);
1.1214 +
1.1215 +/**
1.1216 + * Checks if the given IP address is a syntactically valid IPv4 address.
1.1217 + *
1.1218 + * @param ip The IP address to validate.
1.1219 + *
1.1220 + * @return True if the IP address is syntactically correct.
1.1221 + * @since 2.6.0
1.1222 + */
1.1223 +gboolean purple_ipv4_address_is_valid(const char *ip);
1.1224 +
1.1225 +/**
1.1226 + * Checks if the given IP address is a syntactically valid IPv6 address.
1.1227 + *
1.1228 + * @param ip The IP address to validate.
1.1229 + *
1.1230 + * @return True if the IP address is syntactically correct.
1.1231 + * @since 2.6.0
1.1232 + */
1.1233 +gboolean purple_ipv6_address_is_valid(const char *ip);
1.1234 +
1.1235 +/**
1.1236 + * This function extracts a list of URIs from the a "text/uri-list"
1.1237 + * string. It was "borrowed" from gnome_uri_list_extract_uris
1.1238 + *
1.1239 + * @param uri_list An uri-list in the standard format.
1.1240 + *
1.1241 + * @return A GList containing strings allocated with g_malloc
1.1242 + * that have been splitted from uri-list.
1.1243 + */
1.1244 +GList *purple_uri_list_extract_uris(const gchar *uri_list);
1.1245 +
1.1246 +/**
1.1247 + * This function extracts a list of filenames from a
1.1248 + * "text/uri-list" string. It was "borrowed" from
1.1249 + * gnome_uri_list_extract_filenames
1.1250 + *
1.1251 + * @param uri_list A uri-list in the standard format.
1.1252 + *
1.1253 + * @return A GList containing strings allocated with g_malloc that
1.1254 + * contain the filenames in the uri-list. Note that unlike
1.1255 + * purple_uri_list_extract_uris() function, this will discard
1.1256 + * any non-file uri from the result value.
1.1257 + */
1.1258 +GList *purple_uri_list_extract_filenames(const gchar *uri_list);
1.1259 +
1.1260 +/*@}*/
1.1261 +
1.1262 +/**************************************************************************
1.1263 + * UTF8 String Functions
1.1264 + **************************************************************************/
1.1265 +/*@{*/
1.1266 +
1.1267 +/**
1.1268 + * Attempts to convert a string to UTF-8 from an unknown encoding.
1.1269 + *
1.1270 + * This function checks the locale and tries sane defaults.
1.1271 + *
1.1272 + * @param str The source string.
1.1273 + *
1.1274 + * @return The UTF-8 string, or @c NULL if it could not be converted.
1.1275 + */
1.1276 +gchar *purple_utf8_try_convert(const char *str);
1.1277 +
1.1278 +/**
1.1279 + * Salvages the valid UTF-8 characters from a string, replacing any
1.1280 + * invalid characters with a filler character (currently hardcoded to
1.1281 + * '?').
1.1282 + *
1.1283 + * @param str The source string.
1.1284 + *
1.1285 + * @return A valid UTF-8 string.
1.1286 + */
1.1287 +gchar *purple_utf8_salvage(const char *str);
1.1288 +
1.1289 +/**
1.1290 + * Removes unprintable characters from a UTF-8 string. These characters
1.1291 + * (in particular low-ASCII characters) are invalid in XML 1.0 and thus
1.1292 + * are not allowed in XMPP and are rejected by libxml2 by default. This
1.1293 + * function uses g_unichar_isprint to determine what characters should
1.1294 + * be stripped. The returned string must be freed by the caller.
1.1295 + *
1.1296 + * @param str A valid UTF-8 string.
1.1297 + *
1.1298 + * @return A newly allocated UTF-8 string without the unprintable characters.
1.1299 + * @since 2.6.0
1.1300 + *
1.1301 + * @see g_unichar_isprint
1.1302 + */
1.1303 +gchar *purple_utf8_strip_unprintables(const gchar *str);
1.1304 +
1.1305 +/**
1.1306 + * Return the UTF-8 version of gai_strerror(). It calls gai_strerror()
1.1307 + * then converts the result to UTF-8. This function is analogous to
1.1308 + * g_strerror().
1.1309 + *
1.1310 + * @param errnum The error code.
1.1311 + *
1.1312 + * @return The UTF-8 error message.
1.1313 + * @since 2.4.0
1.1314 + */
1.1315 +G_CONST_RETURN gchar *purple_gai_strerror(gint errnum);
1.1316 +
1.1317 +/**
1.1318 + * Compares two UTF-8 strings case-insensitively. This comparison is
1.1319 + * more expensive than a simple g_utf8_collate() comparison because
1.1320 + * it calls g_utf8_casefold() on each string, which allocates new
1.1321 + * strings.
1.1322 + *
1.1323 + * @param a The first string.
1.1324 + * @param b The second string.
1.1325 + *
1.1326 + * @return -1 if @a is less than @a b.
1.1327 + * 0 if @a is equal to @a b.
1.1328 + * 1 if @a is greater than @a b.
1.1329 + */
1.1330 +int purple_utf8_strcasecmp(const char *a, const char *b);
1.1331 +
1.1332 +/**
1.1333 + * Case insensitive search for a word in a string. The needle string
1.1334 + * must be contained in the haystack string and not be immediately
1.1335 + * preceded or immediately followed by another alpha-numeric character.
1.1336 + *
1.1337 + * @param haystack The string to search in.
1.1338 + * @param needle The substring to find.
1.1339 + *
1.1340 + * @return TRUE if haystack has the word, otherwise FALSE
1.1341 + */
1.1342 +gboolean purple_utf8_has_word(const char *haystack, const char *needle);
1.1343 +
1.1344 +/**
1.1345 + * Prints a UTF-8 message to the given file stream. The function
1.1346 + * tries to convert the UTF-8 message to user's locale. If this
1.1347 + * is not possible, the original UTF-8 text will be printed.
1.1348 + *
1.1349 + * @param filestream The file stream (e.g. STDOUT or STDERR)
1.1350 + * @param message The message to print.
1.1351 + */
1.1352 +void purple_print_utf8_to_console(FILE *filestream, char *message);
1.1353 +
1.1354 +/**
1.1355 + * Checks for messages starting (post-HTML) with "/me ", including the space.
1.1356 + *
1.1357 + * @param message The message to check
1.1358 + * @param len The message length, or -1
1.1359 + *
1.1360 + * @return TRUE if it starts with "/me ", and it has been removed, otherwise
1.1361 + * FALSE
1.1362 + */
1.1363 +gboolean purple_message_meify(char *message, gssize len);
1.1364 +
1.1365 +/**
1.1366 + * Removes the underscore characters from a string used identify the mnemonic
1.1367 + * character.
1.1368 + *
1.1369 + * @param in The string to strip
1.1370 + *
1.1371 + * @return The stripped string
1.1372 + */
1.1373 +char *purple_text_strip_mnemonic(const char *in);
1.1374 +
1.1375 +/*@}*/
1.1376 +
1.1377 +/**
1.1378 + * Adds 8 to something.
1.1379 + *
1.1380 + * Blame SimGuy.
1.1381 + *
1.1382 + * @param x The number to add 8 to.
1.1383 + *
1.1384 + * @return x + 8
1.1385 + */
1.1386 +#define purple_add_eight(x) ((x)+8)
1.1387 +
1.1388 +/**
1.1389 + * Does the reverse of purple_escape_filename
1.1390 + *
1.1391 + * This will change hex codes and such to their ascii equivalents.
1.1392 + *
1.1393 + * @param str The string to translate.
1.1394 + *
1.1395 + * @return The resulting string.
1.1396 + */
1.1397 +const char *purple_unescape_filename(const char *str);
1.1398 +
1.1399 +/**
1.1400 + * Escapes filesystem-unfriendly characters from a filename
1.1401 + *
1.1402 + * @param str The string to translate.
1.1403 + *
1.1404 + * @return The resulting string.
1.1405 + */
1.1406 +const char *purple_escape_filename(const char *str);
1.1407 +
1.1408 +/**
1.1409 + * This is added temporarily to assist the split of oscar into aim and icq.
1.1410 + * This should not be used by plugins.
1.1411 + */
1.1412 +const char *_purple_oscar_convert(const char *act, const char *protocol);
1.1413 +
1.1414 +/**
1.1415 + * Restore default signal handlers for signals which might reasonably have
1.1416 + * handlers. This should be called by a fork()'d child process, since child processes
1.1417 + * inherit the handlers of the parent.
1.1418 + */
1.1419 +void purple_restore_default_signal_handlers(void);
1.1420 +
1.1421 +/**
1.1422 + * Gets the host name of the machine. If it not possible to determine the
1.1423 + * host name, "localhost" is returned
1.1424 + *
1.1425 + * @constreturn The hostname
1.1426 + */
1.1427 +const gchar *purple_get_host_name(void);
1.1428 +
1.1429 +#ifdef __cplusplus
1.1430 +}
1.1431 +#endif
1.1432 +
1.1433 +#endif /* _PURPLE_UTIL_H_ */