util.h
Go to the documentation of this file.
1 
6 /* purple
7  *
8  * Purple is the legal property of its developers, whose names are too numerous
9  * to list here. Please refer to the COPYRIGHT file distributed with this
10  * source distribution.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation; either version 2 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program; if not, write to the Free Software
24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
25  *
26  * @todo Rename the functions so that they live somewhere in the purple
27  * namespace.
28  */
29 #ifndef _PURPLE_UTIL_H_
30 #define _PURPLE_UTIL_H_
31 
32 #include <stdio.h>
33 
38 typedef struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData;
43 
44 #include "account.h"
45 #include "signals.h"
46 #include "xmlnode.h"
47 #include "notify.h"
48 
49 
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53 
55 {
56  char *label;
57  PurpleCallback callback;
58  gpointer data;
59  GList *children;
60 };
61 
62 typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);
63 
71 {
72  gchar *key;
73  void *value;
74 
75 };
76 
88 PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback,
89  gpointer data, GList *children);
90 
97 
106 void purple_util_set_current_song(const char *title, const char *artist,
107  const char *album);
108 
120 char * purple_util_format_song_info(const char *title, const char *artist,
121  const char *album, gpointer unused);
122 
123 /**************************************************************************/
125 /**************************************************************************/
133 void purple_util_init(void);
134 
140 void purple_util_uninit(void);
141 
144 /**************************************************************************/
146 /**************************************************************************/
160 gchar *purple_base16_encode(const guchar *data, gsize len);
161 
177 guchar *purple_base16_decode(const char *str, gsize *ret_len);
178 
191 gchar *purple_base16_encode_chunked(const guchar *data, gsize len);
192 
193 
196 /**************************************************************************/
198 /**************************************************************************/
212 gchar *purple_base64_encode(const guchar *data, gsize len);
213 
229 guchar *purple_base64_decode(const char *str, gsize *ret_len);
230 
233 /**************************************************************************/
235 /**************************************************************************/
250 guchar *purple_quotedp_decode(const char *str, gsize *ret_len);
251 
254 /**************************************************************************/
256 /**************************************************************************/
278 char *purple_mime_decode_field(const char *str);
279 
283 /**************************************************************************/
285 /**************************************************************************/
314 const char *purple_utf8_strftime(const char *format, const struct tm *tm);
315 
324 const char *purple_get_tzoff_str(const struct tm *tm, gboolean iso);
325 
336 const char *purple_date_format_short(const struct tm *tm);
337 
348 const char *purple_date_format_long(const struct tm *tm);
349 
360 const char *purple_date_format_full(const struct tm *tm);
361 
372 const char *purple_time_format(const struct tm *tm);
373 
386 time_t purple_time_build(int year, int month, int day, int hour,
387  int min, int sec);
388 
391 #define PURPLE_NO_TZ_OFF -500000
392 
413 time_t purple_str_to_time(const char *timestamp, gboolean utc,
414  struct tm *tm, long *tz_off, const char **rest);
415 
419 /**************************************************************************/
421 /**************************************************************************/
435 gchar *purple_markup_escape_text(const gchar *text, gssize length);
436 
452 gboolean purple_markup_find_tag(const char *needle, const char *haystack,
453  const char **start, const char **end,
454  GData **attributes);
455 
479 gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info,
480  const char *start_token, int skip,
481  const char *end_token, char check_value,
482  const char *no_value_token,
483  const char *display_name, gboolean is_link,
484  const char *link_prefix,
485  PurpleInfoFieldFormatCallback format_cb);
486 
494 void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,
495  char **dest_plain);
496 
505 char *purple_markup_strip_html(const char *str);
506 
516 char *purple_markup_linkify(const char *str);
517 
536 char *purple_unescape_text(const char *text);
537 
549 char *purple_unescape_html(const char *html);
550 
572 char *purple_markup_slice(const char *str, guint x, guint y);
573 
583 char *purple_markup_get_tag_name(const char *tag);
584 
601 const char * purple_markup_unescape_entity(const char *text, int *length);
602 
619 char * purple_markup_get_css_property(const gchar *style, const gchar *opt);
620 
630 gboolean purple_markup_is_rtl(const char *html);
631 
635 /**************************************************************************/
637 /**************************************************************************/
647 const gchar *purple_home_dir(void);
648 
657 const char *purple_user_dir(void);
658 
663 void purple_util_set_user_dir(const char *dir);
664 
675 int purple_build_dir(const char *path, int mode);
676 
692 gboolean purple_util_write_data_to_file(const char *filename, const char *data,
693  gssize size);
694 
712 gboolean
713 purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size);
714 
729 xmlnode *purple_util_read_xml_from_file(const char *filename,
730  const char *description);
731 
748 FILE *purple_mkstemp(char **path, gboolean binary);
749 
758 const char *
759 purple_util_get_image_extension(gconstpointer data, size_t len);
760 
764 char *purple_util_get_image_checksum(gconstpointer image_data, size_t image_len);
765 
773 char *purple_util_get_image_filename(gconstpointer image_data, size_t image_len);
774 
778 /**************************************************************************/
780 /**************************************************************************/
790 gboolean purple_program_is_valid(const char *program);
791 
797 gboolean purple_running_gnome(void);
798 
804 gboolean purple_running_kde(void);
805 
811 gboolean purple_running_osx(void);
812 
820 char *purple_fd_get_ip(int fd);
821 
831 int purple_socket_get_family(int fd);
832 
843 gboolean purple_socket_speaks_ipv4(int fd);
844 
848 /**************************************************************************/
850 /**************************************************************************/
866 gboolean purple_strequal(const gchar *left, const gchar *right);
867 
885 const char *purple_normalize(const PurpleAccount *account, const char *str);
886 
899 const char *purple_normalize_nocase(const PurpleAccount *account, const char *str);
900 
910 gboolean purple_str_has_prefix(const char *s, const char *p);
911 
921 gboolean purple_str_has_suffix(const char *s, const char *x);
922 
931 gchar *purple_strdup_withhtml(const gchar *src);
932 
940 char *purple_str_add_cr(const char *str);
941 
953 void purple_str_strip_char(char *str, char thechar);
954 
965 void purple_util_chrreplace(char *string, char delimiter,
966  char replacement);
967 
980 gchar *purple_strreplace(const char *string, const char *delimiter,
981  const char *replacement);
982 
983 
994 char *purple_utf8_ncr_encode(const char *in);
995 
996 
1007 char *purple_utf8_ncr_decode(const char *in);
1008 
1009 
1022 gchar *purple_strcasereplace(const char *string, const char *delimiter,
1023  const char *replacement);
1024 
1034 const char *purple_strcasestr(const char *haystack, const char *needle);
1035 
1044 char *purple_str_size_to_units(size_t size);
1045 
1054 char *purple_str_seconds_to_string(guint sec);
1055 
1069 char *purple_str_binary_to_ascii(const unsigned char *binary, guint len);
1073 /**************************************************************************/
1075 /**************************************************************************/
1078 void purple_got_protocol_handler_uri(const char *uri);
1079 
1092 gboolean purple_url_parse(const char *url, char **ret_host, int *ret_port,
1093  char **ret_path, char **ret_user, char **ret_passwd);
1094 
1110 typedef void (*PurpleUtilFetchUrlCallback)(PurpleUtilFetchUrlData *url_data, gpointer user_data, const gchar *url_text, gsize len, const gchar *error_message);
1111 
1123 #define purple_util_fetch_url(url, full, user_agent, http11, cb, data) \
1124  purple_util_fetch_url_request(url, full, user_agent, http11, NULL, \
1125  FALSE, cb, data);
1126 
1140 #define purple_util_fetch_url_len(url, full, user_agent, http11, max_len, cb, data) \
1141  purple_util_fetch_url_request_len(url, full, user_agent, http11, NULL, \
1142  FALSE, max_len, cb, data);
1143 
1160  gboolean full, const gchar *user_agent, gboolean http11,
1161  const gchar *request, gboolean include_headers,
1162  PurpleUtilFetchUrlCallback callback, gpointer data);
1163 
1182  gboolean full, const gchar *user_agent, gboolean http11,
1183  const gchar *request, gboolean include_headers, gssize max_len,
1184  PurpleUtilFetchUrlCallback callback, gpointer data);
1185 
1206  PurpleAccount *account, const gchar *url,
1207  gboolean full, const gchar *user_agent, gboolean http11,
1208  const gchar *request, gboolean include_headers, gssize max_len,
1209  PurpleUtilFetchUrlCallback callback, gpointer data);
1210 
1218 
1228 const char *purple_url_decode(const char *str);
1229 
1239 const char *purple_url_encode(const char *str);
1240 
1248 gboolean purple_email_is_valid(const char *address);
1249 
1260 gboolean purple_ip_address_is_valid(const char *ip);
1261 
1270 gboolean purple_ipv4_address_is_valid(const char *ip);
1271 
1280 gboolean purple_ipv6_address_is_valid(const char *ip);
1281 
1291 GList *purple_uri_list_extract_uris(const gchar *uri_list);
1292 
1305 GList *purple_uri_list_extract_filenames(const gchar *uri_list);
1306 
1309 /**************************************************************************
1310  * UTF8 String Functions
1311  **************************************************************************/
1323 gchar *purple_utf8_try_convert(const char *str);
1324 
1334 gchar *purple_utf8_salvage(const char *str);
1335 
1348 gchar *purple_utf8_strip_unprintables(const gchar *str);
1349 
1360 G_CONST_RETURN gchar *purple_gai_strerror(gint errnum);
1361 
1375 int purple_utf8_strcasecmp(const char *a, const char *b);
1376 
1387 gboolean purple_utf8_has_word(const char *haystack, const char *needle);
1388 
1397 void purple_print_utf8_to_console(FILE *filestream, char *message);
1398 
1408 gboolean purple_message_meify(char *message, gssize len);
1409 
1418 char *purple_text_strip_mnemonic(const char *in);
1419 
1431 #define purple_add_eight(x) ((x)+8)
1432 
1442 const char *purple_unescape_filename(const char *str);
1443 
1451 const char *purple_escape_filename(const char *str);
1452 
1461 const char *_purple_oscar_convert(const char *act, const char *protocol);
1462 
1469 
1476 const gchar *purple_get_host_name(void);
1477 
1484 gchar *purple_uuid_random(void);
1485 
1486 #ifdef __cplusplus
1487 }
1488 #endif
1489 
1490 #endif /* _PURPLE_UTIL_H_ */
Notification API.
char * purple_utf8_ncr_encode(const char *in)
Given a string, this replaces any utf-8 substrings in that string with the corresponding numerical ch...
const char * purple_url_decode(const char *str)
Decodes a URL into a plain string.
char * purple_utf8_ncr_decode(const char *in)
Given a string, this replaces any numerical character references in that string with the correspondin...
char * purple_markup_get_tag_name(const char *tag)
Returns a newly allocated string containing the name of the tag located at "tag". ...
const gchar * purple_home_dir(void)
Returns the user&#39;s home directory.
void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml, char **dest_plain)
Converts HTML markup to XHTML.
gboolean purple_message_meify(char *message, gssize len)
Checks for messages starting (post-HTML) with "/me ", including the space.
char * purple_str_size_to_units(size_t size)
Returns a string representing a filesize in the appropriate units (MB, KB, GB, etc.)
GList * purple_uri_list_extract_uris(const gchar *uri_list)
This function extracts a list of URIs from the a "text/uri-list" string.
const char * purple_time_format(const struct tm *tm)
Formats a time into the user&#39;s preferred time format.
PurpleUtilFetchUrlData * purple_util_fetch_url_request(const gchar *url, gboolean full, const gchar *user_agent, gboolean http11, const gchar *request, gboolean include_headers, PurpleUtilFetchUrlCallback callback, gpointer data)
Fetches the data from a URL, and passes it to a callback function.
char * purple_markup_slice(const char *str, guint x, guint y)
Returns a newly allocated substring of the HTML UTF-8 string "str".
struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData
An opaque structure representing a URL request.
Definition: util.h:38
int purple_utf8_strcasecmp(const char *a, const char *b)
Compares two UTF-8 strings case-insensitively.
void purple_util_uninit(void)
Uninitializes the util subsystem.
gboolean purple_ip_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv4 address.
int purple_build_dir(const char *path, int mode)
Builds a complete path from the root, making any directories along the path which do not already exis...
void purple_menu_action_free(PurpleMenuAction *act)
Frees a PurpleMenuAction.
time_t purple_time_build(int year, int month, int day, int hour, int min, int sec)
Builds a time_t from the supplied information.
xmlnode * purple_util_read_xml_from_file(const char *filename, const char *description)
Read the contents of a given file and parse the results into an xmlnode tree structure.
void purple_util_chrreplace(char *string, char delimiter, char replacement)
Given a string, this replaces all instances of one character with another.
void purple_print_utf8_to_console(FILE *filestream, char *message)
Prints a UTF-8 message to the given file stream.
char * purple_util_format_song_info(const char *title, const char *artist, const char *album, gpointer unused)
Format song information.
gboolean purple_socket_speaks_ipv4(int fd)
Returns TRUE if a socket is capable of speaking IPv4.
PurpleUtilFetchUrlData * purple_util_fetch_url_request_len(const gchar *url, gboolean full, const gchar *user_agent, gboolean http11, const gchar *request, gboolean include_headers, gssize max_len, PurpleUtilFetchUrlCallback callback, gpointer data)
Fetches the data from a URL, and passes it to a callback function.
const char * purple_normalize(const PurpleAccount *account, const char *str)
Normalizes a string, so that it is suitable for comparison.
char * purple_str_add_cr(const char *str)
Ensures that all linefeeds have a matching carriage return.
char * purple_mime_decode_field(const char *str)
Converts a MIME header field string back to its readable equivalent according to RFC 2047...
gboolean purple_markup_find_tag(const char *needle, const char *haystack, const char **start, const char **end, GData **attributes)
Finds an HTML tag matching the given name.
gboolean purple_email_is_valid(const char *address)
Checks if the given email address is syntactically valid.
char * purple_markup_strip_html(const char *str)
Strips HTML tags from a string.
char * purple_str_binary_to_ascii(const unsigned char *binary, guint len)
Converts a binary string into a NUL terminated ascii string, replacing nonascii characters and charac...
Structure representing an account.
Definition: account.h:126
guchar * purple_quotedp_decode(const char *str, gsize *ret_len)
Converts a quoted printable string back to its readable equivalent.
gchar * purple_base16_encode(const guchar *data, gsize len)
Converts a chunk of binary data to its base-16 equivalent.
gboolean purple_running_kde(void)
Check if running KDE.
gboolean purple_markup_is_rtl(const char *html)
Check if the given HTML contains RTL text.
const char * purple_date_format_long(const struct tm *tm)
Formats a time into the user&#39;s preferred short date plus time format.
char * purple_markup_get_css_property(const gchar *style, const gchar *opt)
Returns a newly allocated string containing the value of the CSS property specified in opt...
gboolean purple_strequal(const gchar *left, const gchar *right)
Tests two strings for equality.
void purple_util_set_user_dir(const char *dir)
Define a custom purple settings directory, overriding the default (user&#39;s home directory/.purple)
XML DOM functions.
char * purple_unescape_html(const char *html)
Unescapes HTML entities to their literal characters and converts "<br>" to "\n".
const char * purple_unescape_filename(const char *str)
Does the reverse of purple_escape_filename.
const char * purple_url_encode(const char *str)
Encodes a URL into an escaped string.
gboolean purple_ipv4_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv4 address.
gboolean purple_running_osx(void)
Check if running OS X.
PurpleMenuAction * purple_menu_action_new(const char *label, PurpleCallback callback, gpointer data, GList *children)
Creates a new PurpleMenuAction.
gchar * purple_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...
const char * purple_util_get_image_extension(gconstpointer data, size_t len)
Returns an extension corresponding to the image data&#39;s file type.
gchar * purple_utf8_try_convert(const char *str)
Attempts to convert a string to UTF-8 from an unknown encoding.
gboolean purple_ipv6_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv6 address.
char * purple_util_get_image_filename(gconstpointer image_data, size_t image_len)
const char * purple_escape_filename(const char *str)
Escapes filesystem-unfriendly characters from a filename.
gboolean purple_str_has_prefix(const char *s, const char *p)
Compares two strings to see if the first contains the second as a proper prefix.
A key-value pair.
Definition: util.h:70
const char * purple_normalize_nocase(const PurpleAccount *account, const char *str)
Normalizes a string, so that it is suitable for comparison.
int purple_socket_get_family(int fd)
Returns the address family of a socket.
GList * purple_uri_list_extract_filenames(const gchar *uri_list)
This function extracts a list of filenames from a "text/uri-list" string.
void purple_restore_default_signal_handlers(void)
Restore default signal handlers for signals which might reasonably have handlers. ...
gboolean purple_markup_extract_info_field(const char *str, int len, PurpleNotifyUserInfo *user_info, 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, PurpleInfoFieldFormatCallback format_cb)
Extracts a field of data from HTML.
gchar * purple_markup_escape_text(const gchar *text, gssize length)
Escapes special characters in a plain-text string so they display correctly as HTML.
gboolean purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size)
Write data to a file using the absolute path.
gboolean purple_utf8_has_word(const char *haystack, const char *needle)
Case insensitive search for a word in a string.
gboolean purple_str_has_suffix(const char *s, const char *x)
Compares two strings to see if the second is a proper suffix of the first.
void(* PurpleUtilFetchUrlCallback)(PurpleUtilFetchUrlData *url_data, gpointer user_data, const gchar *url_text, gsize len, const gchar *error_message)
This is the signature used for functions that act as the callback to purple_util_fetch_url() or purpl...
Definition: util.h:1110
guchar * purple_base64_decode(const char *str, gsize *ret_len)
Converts an ASCII string of base-64 encoded data to the binary equivalent.
void purple_util_set_current_song(const char *title, const char *artist, const char *album)
Set the appropriate presence values for the currently playing song.
char * purple_fd_get_ip(int fd)
Returns the IP address from a socket file descriptor.
const char * purple_utf8_strftime(const char *format, const struct tm *tm)
Formats a time into the specified format.
char * purple_str_seconds_to_string(guint sec)
Converts seconds into a human-readable form.
const char * purple_markup_unescape_entity(const char *text, int *length)
Returns a constant string of the character representation of the HTML entity pointed to by text...
gchar * purple_utf8_strip_unprintables(const gchar *str)
Removes unprintable characters from a UTF-8 string.
Account API.
const char * purple_date_format_full(const struct tm *tm)
Formats a time into the user&#39;s preferred full date and time format.
time_t purple_str_to_time(const char *timestamp, gboolean utc, struct tm *tm, long *tz_off, const char **rest)
Parses a timestamp in jabber, ISO8601, or MM/DD/YYYY format and returns a time_t. ...
gchar * purple_base16_encode_chunked(const guchar *data, gsize len)
Converts a chunk of binary data to a chunked base-16 representation (handy for key fingerprints) ...
void purple_str_strip_char(char *str, char thechar)
Strips all instances of the given character from the given string.
gboolean purple_running_gnome(void)
Check if running GNOME.
gboolean purple_program_is_valid(const char *program)
Checks if the given program name is valid and executable.
void purple_util_fetch_url_cancel(PurpleUtilFetchUrlData *url_data)
Cancel a pending URL request started with either purple_util_fetch_url_request() or purple_util_fetch...
char * purple_unescape_text(const char *text)
Unescapes HTML entities to their literal characters in the text.
FILE * purple_mkstemp(char **path, gboolean binary)
Creates a temporary file and returns a file pointer to it.
gchar * purple_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 ...
const char * purple_strcasestr(const char *haystack, const char *needle)
This is like strstr, except that it ignores ASCII case in searching for the substring.
void purple_util_init(void)
Initializes the utility subsystem.
Signal API.
gchar * purple_base64_encode(const guchar *data, gsize len)
Converts a chunk of binary data to its base-64 equivalent.
gchar * purple_uuid_random(void)
Returns a type 4 (random) UUID.
const char * purple_user_dir(void)
Returns the purple settings directory in the user&#39;s home directory.
G_CONST_RETURN gchar * purple_gai_strerror(gint errnum)
Return the UTF-8 version of gai_strerror().
const gchar * purple_get_host_name(void)
Gets the host name of the machine.
const char * purple_get_tzoff_str(const struct tm *tm, gboolean iso)
Gets a string representation of the local timezone offset.
gchar * purple_utf8_salvage(const char *str)
Salvages the valid UTF-8 characters from a string, replacing any invalid characters with a filler cha...
PurpleUtilFetchUrlData * purple_util_fetch_url_request_len_with_account(PurpleAccount *account, const gchar *url, gboolean full, const gchar *user_agent, gboolean http11, const gchar *request, gboolean include_headers, gssize max_len, PurpleUtilFetchUrlCallback callback, gpointer data)
Fetches the data from a URL, and passes it to a callback function.
char * purple_text_strip_mnemonic(const char *in)
Removes the underscore characters from a string used identify the mnemonic character.
char * purple_util_get_image_checksum(gconstpointer image_data, size_t image_len)
Returns a SHA-1 hash string of the data passed in.
char * purple_markup_linkify(const char *str)
Adds the necessary HTML code to turn URIs into HTML links in a string.
gboolean purple_util_write_data_to_file(const char *filename, const char *data, gssize size)
Write a string of data to a file of the given name in the Purple user directory ($HOME/.purple by default).
guchar * purple_base16_decode(const char *str, gsize *ret_len)
Converts an ASCII string of base-16 encoded data to the binary equivalent.
const char * _purple_oscar_convert(const char *act, const char *protocol)
This is added temporarily to assist the split of oscar into aim and icq.
const char * purple_date_format_short(const struct tm *tm)
Formats a time into the user&#39;s preferred short date format.
gchar * purple_strdup_withhtml(const gchar *src)
Duplicates a string and replaces all newline characters from the source string with HTML linebreaks...
gboolean purple_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.