gaim/gaim

This is basically the same scenario as the previous fix.
oldstatus v1_3_1
2005-06-09, Daniel Atallah
ddb659dd612d
This is basically the same scenario as the previous fix.
/**
* @file util.h Utility Functions
* @ingroup core
*
* gaim
*
* Gaim is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* @todo Rename the functions so that they live somewhere in the gaim
* namespace.
*/
#ifndef _GAIM_UTIL_H_
#define _GAIM_UTIL_H_
#include <stdio.h>
#include "account.h"
#ifdef __cplusplus
extern "C" {
#endif
/**************************************************************************/
/** @name Base16 Functions */
/**************************************************************************/
/*@{*/
/**
* Converts a string to its base-16 equivalent.
*
* @param str The string to convert.
* @param len The length of the string.
*
* @return The base-16 string.
*
* @see gaim_base16_decode()
*/
unsigned char *gaim_base16_encode(const unsigned char *str, int len);
/**
* Converts a string back from its base-16 equivalent.
*
* @param str The string to convert back.
* @param ret_str The returned, non-base-16 string.
*
* @return The length of the returned string.
*
* @see gaim_base16_encode()
*/
int gaim_base16_decode(const char *str, unsigned char **ret_str);
/*@}*/
/**************************************************************************/
/** @name Base64 Functions */
/**************************************************************************/
/*@{*/
/**
* Converts a string to its base-64 equivalent.
*
* @param buf The data to convert.
* @param len The length of the data.
*
* @return The base-64 version of @a str.
*
* @see gaim_base64_decode()
*/
unsigned char *gaim_base64_encode(const unsigned char *buf, size_t len);
/**
* Converts a string back from its base-64 equivalent.
*
* @param str The string to convert back.
* @param ret_str The returned, non-base-64 string.
* @param ret_len The returned string length.
*
* @see gaim_base64_encode()
*/
void gaim_base64_decode(const char *str, char **ret_str, int *ret_len);
/*@}*/
/**************************************************************************/
/** @name Quoted Printable Functions */
/**************************************************************************/
/*@{*/
/**
* Converts a quoted printable string back to its readable equivalent.
*
* @param str The string to convert back.
* @param ret_str The returned, readable string.
* @param ret_len The returned string length.
*/
void gaim_quotedp_decode (const char *str, char **ret_str, int *ret_len);
/*@}*/
/**************************************************************************/
/** @name MIME Functions */
/**************************************************************************/
/*@{*/
/**
* Converts a MIME header field string back to its readable equivalent
* according to RFC 2047. Basically, a header is plain ASCII and can
* contain any number of sections called "encoded-words." The format
* of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
* =? designates the beginning of the encoded-word
* ?= designates the end of the encoded-word
* ? segments the encoded word into three pieces. The first piece is
* the character set, the second piece is the encoding, and the
* third piece is the encoded text.
*
* @param str The string to convert back.
*
* @return The readable string.
*/
char *gaim_mime_decode_field (const char *str);
/*@}*/
/**************************************************************************/
/** @name Date/Time Functions */
/**************************************************************************/
/*@{*/
/**
* Returns the current local time in hour:minute:second form.
*
* The returned string is stored in a static buffer, so the result
* should be g_strdup()'d if it's intended to be used for long.
*
* @return The current local time.
*
* @see gaim_date_full()
*/
const char *gaim_date(void);
/**
* Returns the date and time in human-readable form.
*
* The returned string is stored in a static buffer, so the result
* should be g_strdup()'d if it's intended to be used for long.
*
* @return The date and time in human-readable form.
*
* @see gaim_date()
*/
const char *gaim_date_full(void);
/**
* Builds a time_t from the supplied information.
*
* @param year The year.
* @param month The month.
* @param day The day.
* @param hour The hour.
* @param min The minute.
* @param sec The second.
*
* @return A time_t.
*/
time_t gaim_time_build(int year, int month, int day, int hour,
int min, int sec);
/**
* Parses a timestamp in jabber or ISO8601 format and returns a time_t.
*
* @param timestamp The timestamp
* @param utc Assume UTC if no timezone specified
*
* @return A time_t.
*/
time_t gaim_str_to_time(const char *timestamp, gboolean utc);
/*@}*/
/**************************************************************************/
/** @name Markup Functions */
/**************************************************************************/
/*@{*/
/**
* Finds a HTML tag matching the given name.
*
* This locates an HTML tag's start and end, and stores its attributes
* in a GData hash table. The names of the attributes are lower-cased
* in the hash table, and the name of the tag is case insensitive.
*
* @param needle the name of the tag
* @param haystack the null-delimited string to search in
* @param start a pointer to the start of the tag if found
* @param end a pointer to the end of the tag if found
* @param attributes the attributes, if the tag was found
* @return TRUE if the tag was found
*/
gboolean gaim_markup_find_tag(const char *needle, const char *haystack,
const char **start, const char **end,
GData **attributes);
/**
* Extracts a field of data from HTML.
*
* This is a scary function. See protocols/msn/msn.c and
* protocols/yahoo/yahoo_profile.c for example usage.
*
* @param str The string to parse.
* @param len The size of str.
* @param dest The destination GString to append the new
* field info to.
* @param start_token The beginning token.
* @param skip The number of characters to skip after the
* start token.
* @param end_token The ending token.
* @param check_value The value that the last character must meet.
* @param no_value_token The token indicating no value is given.
* @param display_name The short descriptive name to display for this token.
* @param is_link TRUE if this should be a link, or FALSE otherwise.
* @param link_prefix The prefix for the link.
*
* @return TRUE if successful, or FALSE otherwise.
*/
gboolean gaim_markup_extract_info_field(const char *str, int len, GString *dest,
const char *start_token, int skip,
const char *end_token, char check_value,
const char *no_value_token,
const char *display_name, gboolean is_link,
const char *link_prefix);
/**
* Converts HTML markup to XHTML.
*
* @param html The HTML markup.
* @param dest_xhtml The destination XHTML output.
* @param dest_plain The destination plain-text output.
*/
void gaim_markup_html_to_xhtml(const char *html, char **dest_xhtml,
char **dest_plain);
/**
* Strips HTML tags from a string.
*
* @param str The string to strip HTML from.
*
* @return The new string without HTML. This must be freed.
*/
char *gaim_markup_strip_html(const char *str);
/**
* Adds the necessary HTML code to turn URIs into HTML links in a string.
*
* @param str The string to linkify.
*
* @return The linkified text.
*/
char *gaim_markup_linkify(const char *str);
/**
* Escapes HTML special characters to be displayed literally.
* For example '&' is replaced by "&amp;" and so on
*
* @param html The string in which to escape any HTML special characters
*
* @return the text with HTML special characters escaped
*/
char *gaim_escape_html(const char *html);
/**
* Unescapes HTML entities to their literal characters.
* For example "&amp;" is replaced by '&' and so on.
* Actually only "&amp;", "&quot;", "&lt;" and "&gt;" are currently
* supported.
*
* @param html The string in which to unescape any HTML entities
*
* @return the text with HTML entities literalized
*/
char *gaim_unescape_html(const char *html);
/**
* Returns a newly allocated substring of the HTML UTF-8 string "str".
* The markup is preserved such that the substring will have the same
* formatting as original string, even though some tags may have been
* opened before "x", or may close after "y". All open tags are closed
* at the end of the returned string, in the proper order.
*
* Note that x and y are in character offsets, not byte offsets, and
* are offsets into an unformatted version of str. Because of this,
* this function may be sensitive to changes in GtkIMHtml and may break
* when used with other UI's. libgaim users are encouraged to report and
* work out any problems encountered.
*
* @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string.
* @param x The character offset into an unformatted version of str to
* begin at.
* @param y The character offset (into an unformatted vesion of str) of
* one past the last character to include in the slice.
*
* @return The HTML slice of string, with all formatting retained.
*/
char *gaim_markup_slice(const char *str, guint x, guint y);
/**
* Returns a newly allocated string containing the name of the tag
* located at "tag". Tag is expected to point to a '<', and contain
* a '>' sometime after that. If there is no '>' and the string is
* not NUL terminated, this function can be expected to segfault.
*
* @param tag The string starting a HTML tag.
* @return A string containing the name of the tag.
*/
char *gaim_markup_get_tag_name(const char *tag);
/*@}*/
/**************************************************************************/
/** @name Path/Filename Functions */
/**************************************************************************/
/*@{*/
/**
* Returns the user's home directory.
*
* @return The user's home directory.
*
* @see gaim_user_dir()
*/
const gchar *gaim_home_dir(void);
/**
* Returns the gaim settings directory in the user's home directory.
*
* @return The gaim settings directory.
*
* @see gaim_home_dir()
*/
char *gaim_user_dir(void);
/**
* Define a custom gaim settings directory, overriding the default (user's home directory/.gaim)
* @param dir The custom settings directory
*/
void set_gaim_user_dir(const char *dir);
/**
* Builds a complete path from the root, making any directories along
* the path which do not already exist.
*
* @param path The path you wish to create. Note that it must start
* from the root or this function will fail.
* @param mode Unix-style permissions for this directory.
*
* @return 0 for success, nonzero on any error.
*/
int gaim_build_dir(const char *path, int mode);
/**
* Creates a temporary file and returns a file pointer to it.
*
* This is like mkstemp(), but returns a file pointer and uses a
* pre-set template. It uses the semantics of tempnam() for the
* directory to use and allocates the space for the file path.
*
* The caller is responsible for closing the file and removing it when
* done, as well as freeing the space pointed to by @a path with
* g_free().
*
* @param path The returned path to the temp file.
*
* @return A file pointer to the temporary file, or @c NULL on failure.
*/
FILE *gaim_mkstemp(char **path);
/**
* Checks if the given program name is valid and executable.
*
* @param program The file name of the application.
*
* @return True if the program is runable.
*/
gboolean gaim_program_is_valid(const char *program);
/**
* Returns the IP address from a socket file descriptor.
*
* @param fd The socket file descriptor.
*
* @return The IP address, or @c NULL on error.
*/
char *gaim_fd_get_ip(int fd);
/*@}*/
/**************************************************************************/
/** @name String Functions */
/**************************************************************************/
/*@{*/
/**
* Normalizes a string, so that it is suitable for comparison.
*
* The returned string will point to a static buffer, so if the
* string is intended to be kept long-term, you <i>must</i>
* g_strdup() it. Also, calling normalize() twice in the same line
* will lead to problems.
*
* @param account The account the string belongs to.
* @param str The string to normalize.
*
* @return A pointer to the normalized version stored in a static buffer.
*/
const char *gaim_normalize(const GaimAccount *account, const char *str);
/**
* Compares two strings to see if the first contains the second as
* a proper prefix.
*
* @param s The string to check.
* @param p The prefix in question.
*
* @return TRUE if p is a prefix of s, otherwise FALSE.
*/
gboolean gaim_str_has_prefix(const char *s, const char *p);
/**
* Compares two strings to see if the second is a proper suffix
* of the first.
*
* @param s The string to check.
* @param x The suffix in question.
*
* @return TRUE if x is a a suffix of s, otherwise FALSE.
*/
gboolean gaim_str_has_suffix(const char *s, const char *x);
/**
* Looks for %n, %d, or %t in a string, and replaces them with the
* specified name, date, and time, respectively.
*
* @param str The string that may contain the special variables.
* @param name The sender name.
*
* @return A newly allocated string where the special variables are
* expanded. This should be g_free'd by the caller.
*/
gchar *gaim_str_sub_away_formatters(const char *str, const char *name);
/**
* Duplicates a string and replaces all newline characters from the
* source string with HTML linebreaks.
*
* @param src The source string.
*
* @return The new string. Must be g_free'd by the caller.
*/
gchar *gaim_strdup_withhtml(const gchar *src);
/**
* Ensures that all linefeeds have a matching carriage return.
*
* @param str The source string.
*
* @return The string with carriage returns.
*/
char *gaim_str_add_cr(const char *str);
/**
* Strips all carriage returns from a string.
*
* @param str The string to strip carriage returns from.
*/
void gaim_str_strip_cr(char *str);
/**
* Given a string, this replaces one substring with another
* and returns a newly allocated string.
*
* @param string The string from which to replace stuff.
* @param delimiter The substring you want replaced.
* @param replacement The substring you want inserted in place
* of the delimiting substring.
*
* @return A new string, after performing the substitution.
* free this with g_free().
*/
gchar *gaim_strreplace(const char *string, const char *delimiter,
const char *replacement);
/**
* Given a string, this replaces any numerical character references
* in that string with the corresponding actual utf-8 substrings,
* and returns a newly allocated string.
*
* @param in The string which might contain numerical character references.
*
* @return A new string, with numerical character references
* replaced with actual utf-8, free this with g_free().
*/
char *gaim_utf8_ncr_decode(const char *in);
/**
* Given a string, this replaces one substring with another
* ignoring case and returns a newly allocated string.
*
* @param string The string from which to replace stuff.
* @param delimiter The substring you want replaced.
* @param replacement The substring you want inserted in place
* of the delimiting substring.
*
* @return A new string, after performing the substitution.
* free this with g_free().
*/
gchar *gaim_strcasereplace(const char *string, const char *delimiter,
const char *replacement);
/**
* This is like strstr, except that it ignores ASCII case in
* searching for the substring.
*
* @param haystack The string to search in.
* @param needle The substring to find.
*
* @return the location of the substring if found, or NULL if not
*/
const char *gaim_strcasestr(const char *haystack, const char *needle);
/**
* Returns a string representing a filesize in the appropriate
* units (MB, KB, GB, etc.)
*
* @param size The size
*
* @return The string in units form. This must be freed.
*/
char *gaim_str_size_to_units(size_t size);
/**
* Converts seconds into a human-readable form.
*
* @param sec The seconds.
*
* @return A human-readable form, containing days, hours, minutes, and
* seconds.
*/
char *gaim_str_seconds_to_string(guint sec);
/**
* Converts a binary string into a NUL terminated ascii string,
* replacing nonascii characters and characters below SPACE (including
* NUL) into \\xyy, where yy are two hex digits. Also backslashes are
* changed into two backslashes (\\\\). The returned, newly allocated
* string can be outputted to the console, and must be g_free()d.
*
* @param binary A string of random data, possibly with embedded NULs
* and such.
* @param len The length in bytes of the input string. Must not be 0.
*
* @return A newly allocated ASCIIZ string.
*/
char *gaim_str_binary_to_ascii(const unsigned char *binary, guint len);
/*@}*/
/**************************************************************************/
/** @name URI/URL Functions */
/**************************************************************************/
/*@{*/
/**
* Parses a URL, returning its host, port, file path, username and password.
*
* The returned data must be freed.
*
* @param url The URL to parse.
* @param ret_host The returned host.
* @param ret_port The returned port.
* @param ret_path The returned path.
* @param ret_user The returned username.
* @param ret_passwd The returned password.
*/
gboolean gaim_url_parse(const char *url, char **ret_host, int *ret_port,
char **ret_path, char **ret_user, char **ret_passwd);
/**
* Fetches the data from a URL, and passes it to a callback function.
*
* @param url The URL.
* @param full TRUE if this is the full URL, or FALSE if it's a
* partial URL.
* @param user_agent The user agent field to use, or NULL.
* @param http11 TRUE if HTTP/1.1 should be used to download the file.
* @param cb The callback function.
* @param data The user data to pass to the callback function.
*/
void gaim_url_fetch(const char *url, gboolean full,
const char *user_agent, gboolean http11,
void (*cb)(void *, const char *, size_t),
void *data);
/**
* Decodes a URL into a plain string.
*
* This will change hex codes and such to their ascii equivalents.
*
* @param str The string to translate.
*
* @return The resulting string.
*/
const char *gaim_url_decode(const char *str);
/**
* Encodes a URL into an escaped string.
*
* This will change non-alphanumeric characters to hex codes.
*
* @param str The string to translate.
*
* @return The resulting string.
*/
const char *gaim_url_encode(const char *str);
/**
* Checks if the given email address is syntactically valid.
*
* @param address The email address to validate.
*
* @return True if the email address is syntactically correct.
*/
gboolean gaim_email_is_valid(const char *address);
/**
* This function extracts a list of URIs from the a "text/uri-list" string
* It was "borrowed" from gnome_uri_list_extract_uris
*
* @param uri_list an uri-list in the standard format.
*
* @return a GList containing strings allocated with g_malloc that have been
* splitted from uri-list.
*/
GList* gaim_uri_list_extract_uris (const gchar* uri_list);
/**
* This function extracts a list of filenames from the a "text/uri-list" string
* It was "borrowed" from gnome_uri_list_extract_filenames
*
* @param uri_list an uri-list in the standard format.
*
* @return a GList containing strings allocated with g_malloc that contain the
* filenames in the uri-list. Note that unlike gaim_uri_list_extract_uris()
* function, this will discard any non-file uri from the result value.
*/
GList* gaim_uri_list_extract_filenames (const gchar* uri_list);
/*@}*/
/**************************************************************************
* UTF8 String Functions
**************************************************************************/
/*@{*/
/**
* Attempts to convert a string to UTF-8 from an unknown encoding.
*
* This function checks the locale and tries sane defaults.
*
* @param str The source string.
*
* @return The UTF-8 string, or @c NULL if it could not be converted.
*/
gchar *gaim_utf8_try_convert(const char *str);
/**
* Salvages the valid UTF-8 characters from a string, replacing any
* invalid characters with a filler character (currently hardcoded to
* '?').
*
* @param str The source string.
*
* @return A valid UTF-8 string.
*/
gchar *gaim_utf8_salvage(const char *str);
/**
* Compares two UTF-8 strings.
*
* @param a The first string.
* @param b The second string.
*
* @return -1 if @a is less than @a b.
* 0 if @a is equal to @a b.
* 1 if @a is greater than @a b.
*/
int gaim_utf8_strcasecmp(const char *a, const char *b);
/**
* Checks for messages starting with "/me "
*
* @param message The message to check
* @param len The message length, or -1
*
* @return TRUE if it starts with /me, and it has been removed, otherwise FALSE
*/
gboolean gaim_message_meify(char *message, size_t len);
/**
* Removes the underscore characters from a string used identify the mnemonic
* character.
*
* @param in The string to strip
*
* @return The stripped string
*/
char *gaim_text_strip_mnemonic(const char *in);
/*@}*/
/**
* Adds 8 to something.
*
* Blame SimGuy.
*
* @param x The number to add 8 to.
*
* @return x + 8
*/
#define gaim_add_eight(x) ((x)+8)
/**
* Does the reverse of gaim_escape_filename
*
* This will change hex codes and such to their ascii equivalents.
*
* @param str The string to translate.
*
* @return The resulting string.
*/
const char *gaim_unescape_filename(const char *str);
/**
* Escapes filesystem-unfriendly characters from a filename
*
* @param str The string to translate.
*
* @return The resulting string.
*/
const char *gaim_escape_filename(const char *str);
#ifdef __cplusplus
}
#endif
#endif /* _GAIM_UTIL_H_ */