Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

util.h File Reference

Utility Functions. More...

#include <stdio.h>
#include "account.h"

Include dependency graph for util.h:

Include dependency graph

Go to the source code of this file.

Base16 Functions

unsigned char * gaim_base16_encode (const unsigned char *str, int len)
 Converts a string to its base-16 equivalent.
int gaim_base16_decode (const char *str, unsigned char **ret_str)
 Converts a string back from its base-16 equivalent.

Base64 Functions

unsigned char * gaim_base64_encode (const unsigned char *buf, size_t len)
 Converts a string to its base-64 equivalent.
void gaim_base64_decode (const char *str, char **ret_str, int *ret_len)
 Converts a string back from its base-64 equivalent.

Quoted Printable Functions

void gaim_quotedp_decode (const char *str, char **ret_str, int *ret_len)
 Converts a quoted printable string back to its readable equivalent.

MIME Functions

char * gaim_mime_decode_field (const char *str)
 Converts a MIME header field string back to its readable equivalent according to RFC 2047.

Date/Time Functions

const char * gaim_date (void)
 Returns the current local time in hour:minute:second form.
const char * gaim_date_full (void)
 Returns the date and time in human-readable form.
time_t gaim_time_build (int year, int month, int day, int hour, int min, int sec)
 Builds a time_t from the supplied information.
time_t gaim_str_to_time (const char *timestamp, gboolean utc)
 Parses a timestamp in jabber or ISO8601 format and returns a time_t.

Markup Functions

gboolean gaim_markup_find_tag (const char *needle, const char *haystack, const char **start, const char **end, GData **attributes)
 Finds a HTML tag matching the given name.
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)
 Extracts a field of data from HTML.
void gaim_markup_html_to_xhtml (const char *html, char **dest_xhtml, char **dest_plain)
 Converts HTML markup to XHTML.
char * gaim_markup_strip_html (const char *str)
 Strips HTML tags from a string.
char * gaim_markup_linkify (const char *str)
 Adds the necessary HTML code to turn URIs into HTML links in a string.
char * gaim_escape_html (const char *html)
 Escapes HTML special characters to be displayed literally.
char * gaim_unescape_html (const char *html)
 Unescapes HTML entities to their literal characters.
char * gaim_markup_slice (const char *str, guint x, guint y)
 Returns a newly allocated substring of the HTML UTF-8 string "str".
char * gaim_markup_get_tag_name (const char *tag)
 Returns a newly allocated string containing the name of the tag located at "tag".

Path/Filename Functions

const gchar * gaim_home_dir (void)
 Returns the user's home directory.
char * gaim_user_dir (void)
 Returns the gaim settings directory in the user's home directory.
void set_gaim_user_dir (const char *dir)
 Define a custom gaim settings directory, overriding the default (user's home directory/.gaim).
int gaim_build_dir (const char *path, int mode)
 Builds a complete path from the root, making any directories along the path which do not already exist.
FILE * gaim_mkstemp (char **path)
 Creates a temporary file and returns a file pointer to it.
gboolean gaim_program_is_valid (const char *program)
 Checks if the given program name is valid and executable.
char * gaim_fd_get_ip (int fd)
 Returns the IP address from a socket file descriptor.

String Functions

const char * gaim_normalize (const GaimAccount *account, const char *str)
 Normalizes a string, so that it is suitable for comparison.
gboolean gaim_str_has_prefix (const char *s, const char *p)
 Compares two strings to see if the first contains the second as a proper prefix.
gboolean gaim_str_has_suffix (const char *s, const char *x)
 Compares two strings to see if the second is a proper suffix of the first.
gchar * gaim_str_sub_away_formatters (const char *str, const char *name)
 Looks for n, d, or t in a string, and replaces them with the specified name, date, and time, respectively.
gchar * gaim_strdup_withhtml (const gchar *src)
 Duplicates a string and replaces all newline characters from the source string with HTML linebreaks.
char * gaim_str_add_cr (const char *str)
 Ensures that all linefeeds have a matching carriage return.
void gaim_str_strip_cr (char *str)
 Strips all carriage returns from a string.
gchar * gaim_strreplace (const char *string, const char *delimiter, const char *replacement)
 Given a string, this replaces one substring with another and returns a newly allocated string.
char * gaim_utf8_ncr_decode (const char *in)
 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.
gchar * gaim_strcasereplace (const char *string, const char *delimiter, const char *replacement)
 Given a string, this replaces one substring with another ignoring case and returns a newly allocated string.
const char * gaim_strcasestr (const char *haystack, const char *needle)
 This is like strstr, except that it ignores ASCII case in searching for the substring.
char * gaim_str_size_to_units (size_t size)
 Returns a string representing a filesize in the appropriate units (MB, KB, GB, etc.).
char * gaim_str_seconds_to_string (guint sec)
 Converts seconds into a human-readable form.
char * gaim_str_binary_to_ascii (const unsigned char *binary, guint len)
 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.

URI/URL Functions

gboolean gaim_url_parse (const char *url, char **ret_host, int *ret_port, char **ret_path, char **ret_user, char **ret_passwd)
 Parses a URL, returning its host, port, file path, username and password.
void gaim_url_fetch (const char *url, gboolean full, const char *user_agent, gboolean http11, void(*cb)(void *, const char *, size_t), void *data)
 Fetches the data from a URL, and passes it to a callback function.
const char * gaim_url_decode (const char *str)
 Decodes a URL into a plain string.
const char * gaim_url_encode (const char *str)
 Encodes a URL into an escaped string.
gboolean gaim_email_is_valid (const char *address)
 Checks if the given email address is syntactically valid.
GList * gaim_uri_list_extract_uris (const gchar *uri_list)
 This function extracts a list of URIs from the a "text/uri-list" string It was "borrowed" from gnome_uri_list_extract_uris.
GList * gaim_uri_list_extract_filenames (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.

Defines

#define gaim_add_eight(x)   ((x)+8)
 Adds 8 to something.

Functions

const char * gaim_unescape_filename (const char *str)
 Does the reverse of gaim_escape_filename.
const char * gaim_escape_filename (const char *str)
 Escapes filesystem-unfriendly characters from a filename.
void botch_ucs (gchar *ucs, gssize len)
void sanitize_ucs (gchar *ucs, gssize len)
void * botch_utf (const void *utf, size_t len, size_t *newlen)
void * sanitize_utf (unsigned char *msg, size_t len, size_t *newlen)


Detailed Description

Utility Functions.

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.

Define Documentation

#define gaim_add_eight  )     ((x)+8)
 

Adds 8 to something.

Blame SimGuy.

Parameters:
x The number to add 8 to.
Returns:
x + 8


Function Documentation

int gaim_base16_decode const char *  str,
unsigned char **  ret_str
 

Converts a string back from its base-16 equivalent.

Parameters:
str The string to convert back.
ret_str The returned, non-base-16 string.
Returns:
The length of the returned string.
See also:
gaim_base16_encode()

unsigned char* gaim_base16_encode const unsigned char *  str,
int  len
 

Converts a string to its base-16 equivalent.

Parameters:
str The string to convert.
len The length of the string.
Returns:
The base-16 string.
See also:
gaim_base16_decode()

void gaim_base64_decode const char *  str,
char **  ret_str,
int *  ret_len
 

Converts a string back from its base-64 equivalent.

Parameters:
str The string to convert back.
ret_str The returned, non-base-64 string.
ret_len The returned string length.
See also:
gaim_base64_encode()

unsigned char* gaim_base64_encode const unsigned char *  buf,
size_t  len
 

Converts a string to its base-64 equivalent.

Parameters:
buf The data to convert.
len The length of the data.
Returns:
The base-64 version of str.
See also:
gaim_base64_decode()

int gaim_build_dir const char *  path,
int  mode
 

Builds a complete path from the root, making any directories along the path which do not already exist.

Parameters:
path The path you wish to create. Note that it must start from the root or this function will fail.
mode Unix-style permissions for this directory.
Returns:
0 for success, nonzero on any error.

const char* gaim_date void   ) 
 

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.

Returns:
The current local time.
See also:
gaim_date_full()

const char* gaim_date_full 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.

Returns:
The date and time in human-readable form.
See also:
gaim_date()

gboolean gaim_email_is_valid const char *  address  ) 
 

Checks if the given email address is syntactically valid.

Parameters:
address The email address to validate.
Returns:
True if the email address is syntactically correct.

const char* gaim_escape_filename const char *  str  ) 
 

Escapes filesystem-unfriendly characters from a filename.

Parameters:
str The string to translate.
Returns:
The resulting string.

char* gaim_escape_html const char *  html  ) 
 

Escapes HTML special characters to be displayed literally.

For example '&' is replaced by "&amp;" and so on

Parameters:
html The string in which to escape any HTML special characters
Returns:
the text with HTML special characters escaped

char* gaim_fd_get_ip int  fd  ) 
 

Returns the IP address from a socket file descriptor.

Parameters:
fd The socket file descriptor.
Returns:
The IP address, or NULL on error.

const gchar* gaim_home_dir void   ) 
 

Returns the user's home directory.

Returns:
The user's home directory.
See also:
gaim_user_dir()

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
 

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.

Parameters:
str The string to parse.
len The size of str.
dest The destination GString to append the new field info to.
start_token The beginning token.
skip The number of characters to skip after the start token.
end_token The ending token.
check_value The value that the last character must meet.
no_value_token The token indicating no value is given.
display_name The short descriptive name to display for this token.
is_link TRUE if this should be a link, or FALSE otherwise.
link_prefix The prefix for the link.
Returns:
TRUE if successful, or FALSE otherwise.

gboolean gaim_markup_find_tag const char *  needle,
const char *  haystack,
const char **  start,
const char **  end,
GData **  attributes
 

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.

Parameters:
needle the name of the tag
haystack the null-delimited string to search in
start a pointer to the start of the tag if found
end a pointer to the end of the tag if found
attributes the attributes, if the tag was found
Returns:
TRUE if the tag was found

char* gaim_markup_get_tag_name const char *  tag  ) 
 

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.

Parameters:
tag The string starting a HTML tag.
Returns:
A string containing the name of the tag.

void gaim_markup_html_to_xhtml const char *  html,
char **  dest_xhtml,
char **  dest_plain
 

Converts HTML markup to XHTML.

Parameters:
html The HTML markup.
dest_xhtml The destination XHTML output.
dest_plain The destination plain-text output.

char* gaim_markup_linkify const char *  str  ) 
 

Adds the necessary HTML code to turn URIs into HTML links in a string.

Parameters:
str The string to linkify.
Returns:
The linkified text.

char* gaim_markup_slice const char *  str,
guint  x,
guint  y
 

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.

Parameters:
str The input NUL terminated, HTML, UTF-8 (or ASCII) string.
x The character offset into an unformatted version of str to begin at.
y The character offset (into an unformatted vesion of str) of one past the last character to include in the slice.
Returns:
The HTML slice of string, with all formatting retained.

char* gaim_markup_strip_html const char *  str  ) 
 

Strips HTML tags from a string.

Parameters:
str The string to strip HTML from.
Returns:
The new string without HTML. This must be freed.

gboolean gaim_message_meify char *  message,
size_t  len
 

Checks for messages starting with "/me ".

Parameters:
message The message to check
len The message length, or -1
Returns:
TRUE if it starts with /me, and it has been removed, otherwise FALSE

char* gaim_mime_decode_field const char *  str  ) 
 

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.

Parameters:
str The string to convert back.
Returns:
The readable string.

FILE* gaim_mkstemp char **  path  ) 
 

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 path with g_free().

Parameters:
path The returned path to the temp file.
Returns:
A file pointer to the temporary file, or NULL on failure.

const char* gaim_normalize const GaimAccount *  account,
const char *  str
 

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 must g_strdup() it. Also, calling normalize() twice in the same line will lead to problems.

Parameters:
account The account the string belongs to.
str The string to normalize.
Returns:
A pointer to the normalized version stored in a static buffer.

gboolean gaim_program_is_valid const char *  program  ) 
 

Checks if the given program name is valid and executable.

Parameters:
program The file name of the application.
Returns:
True if the program is runable.

void gaim_quotedp_decode const char *  str,
char **  ret_str,
int *  ret_len
 

Converts a quoted printable string back to its readable equivalent.

Parameters:
str The string to convert back.
ret_str The returned, readable string.
ret_len The returned string length.

char* gaim_str_add_cr const char *  str  ) 
 

Ensures that all linefeeds have a matching carriage return.

Parameters:
str The source string.
Returns:
The string with carriage returns.

char* gaim_str_binary_to_ascii const unsigned char *  binary,
guint  len
 

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.

Parameters:
binary A string of random data, possibly with embedded NULs and such.
len The length in bytes of the input string. Must not be 0.
Returns:
A newly allocated ASCIIZ string.

gboolean gaim_str_has_prefix const char *  s,
const char *  p
 

Compares two strings to see if the first contains the second as a proper prefix.

Parameters:
s The string to check.
p The prefix in question.
Returns:
TRUE if p is a prefix of s, otherwise FALSE.

gboolean gaim_str_has_suffix const char *  s,
const char *  x
 

Compares two strings to see if the second is a proper suffix of the first.

Parameters:
s The string to check.
x The suffix in question.
Returns:
TRUE if x is a a suffix of s, otherwise FALSE.

char* gaim_str_seconds_to_string guint  sec  ) 
 

Converts seconds into a human-readable form.

Parameters:
sec The seconds.
Returns:
A human-readable form, containing days, hours, minutes, and seconds.

char* gaim_str_size_to_units size_t  size  ) 
 

Returns a string representing a filesize in the appropriate units (MB, KB, GB, etc.).

Parameters:
size The size
Returns:
The string in units form. This must be freed.

void gaim_str_strip_cr char *  str  ) 
 

Strips all carriage returns from a string.

Parameters:
str The string to strip carriage returns from.

gchar* gaim_str_sub_away_formatters const char *  str,
const char *  name
 

Looks for n, d, or t in a string, and replaces them with the specified name, date, and time, respectively.

Parameters:
str The string that may contain the special variables.
name The sender name.
Returns:
A newly allocated string where the special variables are expanded. This should be g_free'd by the caller.

time_t gaim_str_to_time const char *  timestamp,
gboolean  utc
 

Parses a timestamp in jabber or ISO8601 format and returns a time_t.

Parameters:
timestamp The timestamp
utc Assume UTC if no timezone specified
Returns:
A time_t.

gchar* gaim_strcasereplace const char *  string,
const char *  delimiter,
const char *  replacement
 

Given a string, this replaces one substring with another ignoring case and returns a newly allocated string.

Parameters:
string The string from which to replace stuff.
delimiter The substring you want replaced.
replacement The substring you want inserted in place of the delimiting substring.
Returns:
A new string, after performing the substitution. free this with g_free().

const char* gaim_strcasestr const char *  haystack,
const char *  needle
 

This is like strstr, except that it ignores ASCII case in searching for the substring.

Parameters:
haystack The string to search in.
needle The substring to find.
Returns:
the location of the substring if found, or NULL if not

gchar* gaim_strdup_withhtml const gchar *  src  ) 
 

Duplicates a string and replaces all newline characters from the source string with HTML linebreaks.

Parameters:
src The source string.
Returns:
The new string. Must be g_free'd by the caller.

gchar* gaim_strreplace const char *  string,
const char *  delimiter,
const char *  replacement
 

Given a string, this replaces one substring with another and returns a newly allocated string.

Parameters:
string The string from which to replace stuff.
delimiter The substring you want replaced.
replacement The substring you want inserted in place of the delimiting substring.
Returns:
A new string, after performing the substitution. free this with g_free().

char* gaim_text_strip_mnemonic const char *  in  ) 
 

Removes the underscore characters from a string used identify the mnemonic character.

Parameters:
in The string to strip
Returns:
The stripped string

time_t gaim_time_build int  year,
int  month,
int  day,
int  hour,
int  min,
int  sec
 

Builds a time_t from the supplied information.

Parameters:
year The year.
month The month.
day The day.
hour The hour.
min The minute.
sec The second.
Returns:
A time_t.

const char* gaim_unescape_filename const char *  str  ) 
 

Does the reverse of gaim_escape_filename.

This will change hex codes and such to their ascii equivalents.

Parameters:
str The string to translate.
Returns:
The resulting string.

char* gaim_unescape_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.

Parameters:
html The string in which to unescape any HTML entities
Returns:
the text with HTML entities literalized

GList* gaim_uri_list_extract_filenames 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.

Parameters:
uri_list an uri-list in the standard format.
Returns:
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_uris const gchar *  uri_list  ) 
 

This function extracts a list of URIs from the a "text/uri-list" string It was "borrowed" from gnome_uri_list_extract_uris.

Parameters:
uri_list an uri-list in the standard format.
Returns:
a GList containing strings allocated with g_malloc that have been splitted from uri-list.

const char* gaim_url_decode const char *  str  ) 
 

Decodes a URL into a plain string.

This will change hex codes and such to their ascii equivalents.

Parameters:
str The string to translate.
Returns:
The resulting string.

const char* gaim_url_encode const char *  str  ) 
 

Encodes a URL into an escaped string.

This will change non-alphanumeric characters to hex codes.

Parameters:
str The string to translate.
Returns:
The resulting string.

void gaim_url_fetch const char *  url,
gboolean  full,
const char *  user_agent,
gboolean  http11,
void(*)(void *, const char *, size_t)  cb,
void *  data
 

Fetches the data from a URL, and passes it to a callback function.

Parameters:
url The URL.
full TRUE if this is the full URL, or FALSE if it's a partial URL.
user_agent The user agent field to use, or NULL.
http11 TRUE if HTTP/1.1 should be used to download the file.
cb The callback function.
data The user data to pass to the callback function.

gboolean gaim_url_parse const char *  url,
char **  ret_host,
int *  ret_port,
char **  ret_path,
char **  ret_user,
char **  ret_passwd
 

Parses a URL, returning its host, port, file path, username and password.

The returned data must be freed.

Parameters:
url The URL to parse.
ret_host The returned host.
ret_port The returned port.
ret_path The returned path.
ret_user The returned username.
ret_passwd The returned password.

char* gaim_user_dir void   ) 
 

Returns the gaim settings directory in the user's home directory.

Returns:
The gaim settings directory.
See also:
gaim_home_dir()

char* gaim_utf8_ncr_decode const char *  in  ) 
 

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.

Parameters:
in The string which might contain numerical character references.
Returns:
A new string, with numerical character references replaced with actual utf-8, free this with g_free().

gchar* gaim_utf8_salvage const char *  str  ) 
 

Salvages the valid UTF-8 characters from a string, replacing any invalid characters with a filler character (currently hardcoded to '?').

Parameters:
str The source string.
Returns:
A valid UTF-8 string.

int gaim_utf8_strcasecmp const char *  a,
const char *  b
 

Compares two UTF-8 strings.

Parameters:
a The first string.
b The second string.
Returns:
-1 if is less than b. 0 if is equal to b. 1 if is greater than b.

gchar* gaim_utf8_try_convert const char *  str  ) 
 

Attempts to convert a string to UTF-8 from an unknown encoding.

This function checks the locale and tries sane defaults.

Parameters:
str The source string.
Returns:
The UTF-8 string, or NULL if it could not be converted.

void set_gaim_user_dir const char *  dir  ) 
 

Define a custom gaim settings directory, overriding the default (user's home directory/.gaim).

Parameters:
dir The custom settings directory


Generated on Tue Aug 9 15:33:13 2005 for gaim by  doxygen 1.3.9.1