1.1 --- a/Frameworks/libpurple.framework/Versions/0.6.0/Headers/util.h Fri Aug 21 13:24:36 2009 -0700
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1430 +0,0 @@
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_ */