gee
oldstatus
2005-09-19, Nathan Walp
* @file util.h Utility Functions * 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 * 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 /**************************************************************************/ /** @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. 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. const char *gaim_date_full(void); * Builds a time_t from the supplied information. * @param month The month. time_t gaim_time_build(int year, int month, int day, int hour, * 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 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, * 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 * @param start_token The beginning token. * @param skip The number of characters to skip after the * @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, * 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 "&" 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 "&" is replaced by '&' and so on. * Actually only "&", """, "<" and ">" are currently * @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 * @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. const gchar *gaim_home_dir(void); * Returns the gaim settings directory in the user's home directory. * @return The gaim settings directory. 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 * @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 * @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); * Normalizes a string, so that it is suitable for comparison. * This is one possible implementation for the PRPL callback * function "normalize." It returns a lowercase and UTF-8 * normalized version of the string. * @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_nocase(const GaimAccount *account, const char *str); * Compares two strings to see if the first contains the second as * @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 * @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.) * @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 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 * @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 full TRUE if this is the full URL, or FALSE if it's a * @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), * 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); /************************************************************************** **************************************************************************/ * 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 * @param in The string to strip * @return The stripped string char *gaim_text_strip_mnemonic(const char *in); * @param x The number to add 8 to. #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); #endif /* _GAIM_UTIL_H_ */