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