pidgin  2.14.13
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;
40 typedef struct _PurpleMenuAction PurpleMenuAction;
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 
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 
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 
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 
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 
1234  const char *url, gboolean full, const char *user_agent, gboolean http11,
1235  const char *request, gsize request_len, gboolean include_headers, gssize max_len,
1236  PurpleUtilFetchUrlCallback callback, void *user_data);
1244 
1254 const char *purple_url_decode(const char *str);
1255 
1265 const char *purple_url_encode(const char *str);
1266 
1274 gboolean purple_email_is_valid(const char *address);
1275 
1286 gboolean purple_ip_address_is_valid(const char *ip);
1287 
1296 gboolean purple_ipv4_address_is_valid(const char *ip);
1297 
1306 gboolean purple_ipv6_address_is_valid(const char *ip);
1307 
1317 GList *purple_uri_list_extract_uris(const gchar *uri_list);
1318 
1331 GList *purple_uri_list_extract_filenames(const gchar *uri_list);
1332 
1342 char *purple_uri_escape_for_open(const char *unescaped);
1343 
1346 /**************************************************************************
1347  * UTF8 String Functions
1348  **************************************************************************/
1360 gchar *purple_utf8_try_convert(const char *str);
1361 
1371 gchar *purple_utf8_salvage(const char *str);
1372 
1385 gchar *purple_utf8_strip_unprintables(const gchar *str);
1386 
1397 const gchar *purple_gai_strerror(gint errnum);
1398 
1412 int purple_utf8_strcasecmp(const char *a, const char *b);
1413 
1424 gboolean purple_utf8_has_word(const char *haystack, const char *needle);
1425 
1434 void purple_print_utf8_to_console(FILE *filestream, char *message);
1435 
1445 gboolean purple_message_meify(char *message, gssize len);
1446 
1455 char *purple_text_strip_mnemonic(const char *in);
1456 
1468 #define purple_add_eight(x) ((x)+8)
1469 
1479 const char *purple_unescape_filename(const char *str);
1480 
1488 const char *purple_escape_filename(const char *str);
1489 
1498 const char *_purple_oscar_convert(const char *act, const char *protocol);
1499 
1506 
1513 const gchar *purple_get_host_name(void);
1514 
1521 gchar *purple_uuid_random(void);
1522 
1523 #ifdef __cplusplus
1524 }
1525 #endif
1526 
1527 #endif /* _PURPLE_UTIL_H_ */
Account API.
Notification API.
Signal API.
Structure representing an account.
Definition: account.h:170
A key-value pair.
Definition: util.h:71
const char * purple_date_format_short(const struct tm *tm)
Formats a time into the user's preferred short date format.
char * purple_util_get_image_checksum(gconstpointer image_data, size_t image_len)
Returns a SHA-1 hash string of the data passed in.
const char * purple_normalize(const PurpleAccount *account, const char *str)
Normalizes a string, so that it is suitable for comparison.
gboolean purple_ip_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv4 address.
char * purple_uri_escape_for_open(const char *unescaped)
This function escapes any characters that might be interpreted by the shell when executing a program ...
char * purple_text_strip_mnemonic(const char *in)
Removes the underscore characters from a string used identify the mnemonic character.
PurpleMenuAction * purple_menu_action_new(const char *label, PurpleCallback callback, gpointer data, GList *children)
Creates a new PurpleMenuAction.
const char * purple_url_encode(const char *str)
Encodes a URL into an escaped string.
void purple_util_uninit(void)
Uninitializes the util subsystem.
const gchar * purple_gai_strerror(gint errnum)
Return the UTF-8 version of gai_strerror().
char * purple_markup_strip_html(const char *str)
Strips HTML tags from a string.
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...
const char * purple_unescape_filename(const char *str)
Does the reverse of purple_escape_filename.
gboolean purple_strequal(const gchar *left, const gchar *right)
Tests two strings for equality.
int purple_utf8_strcasecmp(const char *a, const char *b)
Compares two UTF-8 strings case-insensitively.
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.
const char * purple_escape_filename(const char *str)
Escapes filesystem-unfriendly characters from a filename.
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_markup_linkify(const char *str)
Adds the necessary HTML code to turn URIs into HTML links in a string.
FILE * purple_mkstemp(char **path, gboolean binary)
Creates a temporary file and returns a file pointer to it.
GList * purple_uri_list_extract_uris(const gchar *uri_list)
This function extracts a list of URIs from the a "text/uri-list" string.
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.
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.
char * purple_util_get_image_filename(gconstpointer image_data, size_t image_len)
struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData
An opaque structure representing a URL request.
Definition: util.h:38
void purple_util_set_user_dir(const char *dir)
Define a custom purple settings directory, overriding the default (user's home directory/....
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.
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.
char * purple_str_size_to_units(size_t size)
Returns a string representing a filesize in the appropriate units (MB, KB, GB, etc....
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/....
gboolean purple_running_kde(void)
Check if running KDE.
char * purple_markup_get_tag_name(const char *tag)
Returns a newly allocated string containing the name of the tag located at "tag".
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.
const gchar * purple_get_host_name(void)
Gets the host name of the machine.
gboolean purple_running_gnome(void)
Check if running GNOME.
char * purple_utf8_ncr_decode(const char *in)
Given a string, this replaces any numerical character references in that string with the correspondin...
gboolean purple_ipv4_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv4 address.
char * purple_unescape_html(const char *html)
Unescapes HTML entities to their literal characters and converts "<br>" to "\n".
void purple_print_utf8_to_console(FILE *filestream, char *message)
Prints a UTF-8 message to the given file stream.
gboolean purple_email_is_valid(const char *address)
Checks if the given email address is syntactically valid.
char * purple_str_seconds_to_string(guint sec)
Converts seconds into a human-readable form.
gchar * purple_base16_encode(const guchar *data, gsize len)
Converts a chunk of binary data to its base-16 equivalent.
gchar * purple_utf8_try_convert(const char *str)
Attempts to convert a string to UTF-8 from an unknown encoding.
const gchar * purple_home_dir(void)
Returns the user's home directory.
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 ...
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.
const char * purple_date_format_full(const struct tm *tm)
Formats a time into the user's preferred full date and time format.
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...
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...
guchar * purple_base64_decode(const char *str, gsize *ret_len)
Converts an ASCII string of base-64 encoded data to the binary equivalent.
gchar * purple_base64_encode(const guchar *data, gsize len)
Converts a chunk of binary data to its base-64 equivalent.
char * purple_fd_get_ip(int fd)
Returns the IP address from a socket file descriptor.
gboolean purple_message_meify(char *message, gssize len)
Checks for messages starting (post-HTML) with "/me ", including the space.
char * purple_markup_slice(const char *str, guint x, guint y)
Returns a newly allocated substring of the HTML UTF-8 string "str".
gboolean purple_ipv6_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv6 address.
guchar * purple_base16_decode(const char *str, gsize *ret_len)
Converts an ASCII string of base-16 encoded data to the binary equivalent.
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
char * purple_str_add_cr(const char *str)
Ensures that all linefeeds have a matching carriage return.
const char * purple_time_format(const struct tm *tm)
Formats a time into the user's preferred time format.
gchar * purple_uuid_random(void)
Returns a type 4 (random) UUID.
gboolean purple_program_is_valid(const char *program)
Checks if the given program name is valid and executable.
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.
const char * purple_utf8_strftime(const char *format, const struct tm *tm)
Formats a time into the specified format.
gboolean purple_running_osx(void)
Check if running OS X.
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...
void purple_restore_default_signal_handlers(void)
Restore default signal handlers for signals which might reasonably have handlers.
const char * purple_normalize_nocase(const PurpleAccount *account, const char *str)
Normalizes a string, so that it is suitable for comparison.
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's preferred short date plus time format.
void purple_str_strip_char(char *str, char thechar)
Strips all instances of the given character from the given string.
guchar * purple_quotedp_decode(const char *str, gsize *ret_len)
Converts a quoted printable string back to its readable equivalent.
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.
PurpleUtilFetchUrlData * purple_util_fetch_url_request_data_len_with_account(PurpleAccount *account, const char *url, gboolean full, const char *user_agent, gboolean http11, const char *request, gsize request_len, gboolean include_headers, gssize max_len, PurpleUtilFetchUrlCallback callback, void *user_data)
Fetches the data from a URL, and passes it to a callback function.
const char * purple_get_tzoff_str(const struct tm *tm, gboolean iso)
Gets a string representation of the local timezone offset.
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.
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.
GList * purple_uri_list_extract_filenames(const gchar *uri_list)
This function extracts a list of filenames from a "text/uri-list" string.
gchar * purple_markup_escape_text(const gchar *text, gssize length)
Escapes special characters in a plain-text string so they display correctly as HTML.
gchar * purple_utf8_salvage(const char *str)
Salvages the valid UTF-8 characters from a string, replacing any invalid characters with a filler cha...
void purple_menu_action_free(PurpleMenuAction *act)
Frees a PurpleMenuAction.
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)
const char * purple_user_dir(void)
Returns the purple settings directory in the user's home directory.
gboolean purple_socket_speaks_ipv4(int fd)
Returns TRUE if a socket is capable of speaking IPv4.
void purple_util_init(void)
Initializes the utility subsystem.
char * purple_mime_decode_field(const char *str)
Converts a MIME header field string back to its readable equivalent according to RFC 2047.
char * purple_unescape_text(const char *text)
Unescapes HTML entities to their literal characters in the text.
gchar * purple_strdup_withhtml(const gchar *src)
Duplicates a string and replaces all newline characters from the source string with HTML linebreaks.
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.
char * purple_util_format_song_info(const char *title, const char *artist, const char *album, gpointer unused)
Format song information.
const char * purple_util_get_image_extension(gconstpointer data, size_t len)
Returns an extension corresponding to the image data's file type.
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.
gchar * purple_utf8_strip_unprintables(const gchar *str)
Removes unprintable characters from a UTF-8 string.
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.
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.
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.
gboolean purple_utf8_has_word(const char *haystack, const char *needle)
Case insensitive search for a word in a string.
void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml, char **dest_plain)
Converts HTML markup to XHTML.
const char * purple_url_decode(const char *str)
Decodes a URL into a plain string.
int purple_socket_get_family(int fd)
Returns the address family of a socket.
void purple_util_chrreplace(char *string, char delimiter, char replacement)
Given a string, this replaces all instances of one character with another.
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.
XML DOM functions.