pidgin 2.14.14dev
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
38typedef 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
51extern "C" {
52#endif
53
55{
56 char *label;
57 PurpleCallback callback;
58 gpointer data;
59 GList *children;
60};
61
62typedef char *(*PurpleInfoFieldFormatCallback)(const char *field, size_t len);
63
71{
72 gchar *key;
73 void *value;
74
75};
76
88PurpleMenuAction *purple_menu_action_new(const char *label, PurpleCallback callback,
89 gpointer data, GList *children);
90
97
106void purple_util_set_current_song(const char *title, const char *artist,
107 const char *album);
108
120char * purple_util_format_song_info(const char *title, const char *artist,
121 const char *album, gpointer unused);
122
123/**************************************************************************/
125/**************************************************************************/
134
141
144/**************************************************************************/
146/**************************************************************************/
160gchar *purple_base16_encode(const guchar *data, gsize len);
161
177guchar *purple_base16_decode(const char *str, gsize *ret_len);
178
191gchar *purple_base16_encode_chunked(const guchar *data, gsize len);
192
193
196/**************************************************************************/
198/**************************************************************************/
212gchar *purple_base64_encode(const guchar *data, gsize len);
213
229guchar *purple_base64_decode(const char *str, gsize *ret_len);
230
233/**************************************************************************/
235/**************************************************************************/
250guchar *purple_quotedp_decode(const char *str, gsize *ret_len);
251
254/**************************************************************************/
256/**************************************************************************/
278char *purple_mime_decode_field(const char *str);
279
283/**************************************************************************/
285/**************************************************************************/
314const char *purple_utf8_strftime(const char *format, const struct tm *tm);
315
324const char *purple_get_tzoff_str(const struct tm *tm, gboolean iso);
325
336const char *purple_date_format_short(const struct tm *tm);
337
348const char *purple_date_format_long(const struct tm *tm);
349
360const char *purple_date_format_full(const struct tm *tm);
361
372const char *purple_time_format(const struct tm *tm);
373
386time_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
413time_t purple_str_to_time(const char *timestamp, gboolean utc,
414 struct tm *tm, long *tz_off, const char **rest);
415
419/**************************************************************************/
421/**************************************************************************/
435gchar *purple_markup_escape_text(const gchar *text, gssize length);
436
452gboolean purple_markup_find_tag(const char *needle, const char *haystack,
453 const char **start, const char **end,
454 GData **attributes);
455
479gboolean 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
494void purple_markup_html_to_xhtml(const char *html, char **dest_xhtml,
495 char **dest_plain);
496
505char *purple_markup_strip_html(const char *str);
506
516char *purple_markup_linkify(const char *str);
517
536char *purple_unescape_text(const char *text);
537
549char *purple_unescape_html(const char *html);
550
572char *purple_markup_slice(const char *str, guint x, guint y);
573
583char *purple_markup_get_tag_name(const char *tag);
584
601const char * purple_markup_unescape_entity(const char *text, int *length);
602
619char * purple_markup_get_css_property(const gchar *style, const gchar *opt);
620
630gboolean purple_markup_is_rtl(const char *html);
631
635/**************************************************************************/
637/**************************************************************************/
647const gchar *purple_home_dir(void);
648
657const char *purple_user_dir(void);
658
663void purple_util_set_user_dir(const char *dir);
664
675int purple_build_dir(const char *path, int mode);
676
692gboolean purple_util_write_data_to_file(const char *filename, const char *data,
693 gssize size);
694
712gboolean
713purple_util_write_data_to_file_absolute(const char *filename_full, const char *data, gssize size);
714
730 const char *description);
731
748FILE *purple_mkstemp(char **path, gboolean binary);
749
758const char *
759purple_util_get_image_extension(gconstpointer data, size_t len);
760
764char *purple_util_get_image_checksum(gconstpointer image_data, size_t image_len);
765
773char *purple_util_get_image_filename(gconstpointer image_data, size_t image_len);
774
778/**************************************************************************/
780/**************************************************************************/
790gboolean purple_program_is_valid(const char *program);
791
797gboolean purple_running_gnome(void);
798
804gboolean purple_running_kde(void);
805
811gboolean purple_running_osx(void);
812
820char *purple_fd_get_ip(int fd);
821
832
844
848/**************************************************************************/
850/**************************************************************************/
866gboolean purple_strequal(const gchar *left, const gchar *right);
867
885const char *purple_normalize(const PurpleAccount *account, const char *str);
886
899const char *purple_normalize_nocase(const PurpleAccount *account, const char *str);
900
910gboolean purple_str_has_prefix(const char *s, const char *p);
911
921gboolean purple_str_has_suffix(const char *s, const char *x);
922
931gchar *purple_strdup_withhtml(const gchar *src);
932
940char *purple_str_add_cr(const char *str);
941
953void purple_str_strip_char(char *str, char thechar);
954
965void purple_util_chrreplace(char *string, char delimiter,
966 char replacement);
967
980gchar *purple_strreplace(const char *string, const char *delimiter,
981 const char *replacement);
982
983
994char *purple_utf8_ncr_encode(const char *in);
995
996
1007char *purple_utf8_ncr_decode(const char *in);
1008
1009
1022gchar *purple_strcasereplace(const char *string, const char *delimiter,
1023 const char *replacement);
1024
1034const char *purple_strcasestr(const char *haystack, const char *needle);
1035
1044char *purple_str_size_to_units(size_t size);
1045
1055
1069char *purple_str_binary_to_ascii(const unsigned char *binary, guint len);
1073/**************************************************************************/
1075/**************************************************************************/
1078void purple_got_protocol_handler_uri(const char *uri);
1079
1092gboolean purple_url_parse(const char *url, char **ret_host, int *ret_port,
1093 char **ret_path, char **ret_user, char **ret_passwd);
1094
1110typedef 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
1254const char *purple_url_decode(const char *str);
1255
1265const char *purple_url_encode(const char *str);
1266
1274gboolean purple_email_is_valid(const char *address);
1275
1286gboolean purple_ip_address_is_valid(const char *ip);
1287
1296gboolean purple_ipv4_address_is_valid(const char *ip);
1297
1306gboolean purple_ipv6_address_is_valid(const char *ip);
1307
1317GList *purple_uri_list_extract_uris(const gchar *uri_list);
1318
1331GList *purple_uri_list_extract_filenames(const gchar *uri_list);
1332
1342char *purple_uri_escape_for_open(const char *unescaped);
1343
1346/**************************************************************************
1347 * UTF8 String Functions
1348 **************************************************************************/
1360gchar *purple_utf8_try_convert(const char *str);
1361
1371gchar *purple_utf8_salvage(const char *str);
1372
1385gchar *purple_utf8_strip_unprintables(const gchar *str);
1386
1397const gchar *purple_gai_strerror(gint errnum);
1398
1412int purple_utf8_strcasecmp(const char *a, const char *b);
1413
1424gboolean purple_utf8_has_word(const char *haystack, const char *needle);
1425
1434void purple_print_utf8_to_console(FILE *filestream, char *message);
1435
1445gboolean purple_message_meify(char *message, gssize len);
1446
1455char *purple_text_strip_mnemonic(const char *in);
1456
1468#define purple_add_eight(x) ((x)+8)
1469
1479const char *purple_unescape_filename(const char *str);
1480
1488const char *purple_escape_filename(const char *str);
1489
1498const char *_purple_oscar_convert(const char *act, const char *protocol);
1499
1506
1513const gchar *purple_get_host_name(void);
1514
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
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_text_strip_mnemonic(const char *in)
Removes the underscore characters from a string used identify the mnemonic character.
char * purple_util_format_song_info(const char *title, const char *artist, const char *album, gpointer unused)
Format song information.
const gchar * purple_get_host_name(void)
Gets the host name of the machine.
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 ...
char * purple_markup_strip_html(const char *str)
Strips HTML tags from a string.
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.
gboolean purple_ip_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv4 address.
const char * purple_user_dir(void)
Returns the purple settings directory in the user's home directory.
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.
char * purple_markup_get_tag_name(const char *tag)
Returns a newly allocated string containing the name of the tag located at "tag".
void purple_util_uninit(void)
Uninitializes the util subsystem.
const char * purple_unescape_filename(const char *str)
Does the reverse of purple_escape_filename.
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...
gchar * purple_utf8_salvage(const char *str)
Salvages the valid UTF-8 characters from a string, replacing any invalid characters with a filler cha...
const char * purple_date_format_short(const struct tm *tm)
Formats a time into the user's preferred short date format.
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.
const char * purple_normalize_nocase(const PurpleAccount *account, const char *str)
Normalizes a string, so that it is suitable for comparison.
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.
gchar * purple_base64_encode(const guchar *data, gsize len)
Converts a chunk of binary data to its base-64 equivalent.
guchar * purple_base16_decode(const char *str, gsize *ret_len)
Converts an ASCII string of base-16 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.
const char * purple_time_format(const struct tm *tm)
Formats a time into the user's preferred time format.
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.
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...
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.
char * purple_str_seconds_to_string(guint sec)
Converts seconds into a human-readable form.
FILE * purple_mkstemp(char **path, gboolean binary)
Creates a temporary file and returns a file pointer to it.
struct _PurpleUtilFetchUrlData PurpleUtilFetchUrlData
An opaque structure representing a URL request.
Definition: util.h:38
char * purple_utf8_ncr_decode(const char *in)
Given a string, this replaces any numerical character references in that string with the correspondin...
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.
const gchar * purple_gai_strerror(gint errnum)
Return the UTF-8 version of gai_strerror().
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.
const char * purple_normalize(const PurpleAccount *account, const char *str)
Normalizes a string, so that it is suitable for comparison.
guchar * purple_quotedp_decode(const char *str, gsize *ret_len)
Converts a quoted printable string back to its readable equivalent.
const gchar * purple_home_dir(void)
Returns the user's home directory.
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.
gchar * purple_markup_escape_text(const gchar *text, gssize length)
Escapes special characters in a plain-text string so they display correctly as HTML.
char * purple_util_get_image_filename(gconstpointer image_data, size_t image_len)
const char * purple_date_format_full(const struct tm *tm)
Formats a time into the user's preferred full date and time format.
const char * purple_url_decode(const char *str)
Decodes a URL into a plain string.
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.
gchar * purple_base16_encode(const guchar *data, gsize len)
Converts a chunk of binary data to its base-16 equivalent.
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.
gboolean purple_running_gnome(void)
Check if running GNOME.
gboolean purple_ipv4_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv4 address.
char * purple_markup_slice(const char *str, guint x, guint y)
Returns a newly allocated substring of the HTML UTF-8 string "str".
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_add_cr(const char *str)
Ensures that all linefeeds have a matching carriage return.
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_mime_decode_field(const char *str)
Converts a MIME header field string back to its readable equivalent according to RFC 2047.
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...
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.
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_utf8_strftime(const char *format, const struct tm *tm)
Formats a time into the specified format.
gboolean purple_message_meify(char *message, gssize len)
Checks for messages starting (post-HTML) with "/me ", including the space.
gboolean purple_ipv6_address_is_valid(const char *ip)
Checks if the given IP address is a syntactically valid IPv6 address.
const char * purple_date_format_long(const struct tm *tm)
Formats a time into the user's preferred short date plus time format.
gchar * purple_utf8_strip_unprintables(const gchar *str)
Removes unprintable characters from a UTF-8 string.
char * purple_unescape_text(const char *text)
Unescapes HTML entities to their literal characters in the 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_uuid_random(void)
Returns a type 4 (random) UUID.
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
PurpleMenuAction * purple_menu_action_new(const char *label, PurpleCallback callback, gpointer data, GList *children)
Creates a new PurpleMenuAction.
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_escape_filename(const char *str)
Escapes filesystem-unfriendly characters from a filename.
gboolean purple_running_osx(void)
Check if running OS X.
void purple_restore_default_signal_handlers(void)
Restore default signal handlers for signals which might reasonably have handlers.
gboolean purple_markup_is_rtl(const char *html)
Check if the given HTML contains RTL text.
gchar * purple_utf8_try_convert(const char *str)
Attempts to convert a string to UTF-8 from an unknown encoding.
void purple_str_strip_char(char *str, char thechar)
Strips all instances of the given character from the given string.
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.
char * purple_str_size_to_units(size_t size)
Returns a string representing a filesize in the appropriate units (MB, KB, GB, etc....
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_strdup_withhtml(const gchar *src)
Duplicates a string and replaces all newline characters from the source string with HTML linebreaks.
char * purple_markup_linkify(const char *str)
Adds the necessary HTML code to turn URIs into HTML links in a string.
GList * purple_uri_list_extract_uris(const gchar *uri_list)
This function extracts a list of URIs from the a "text/uri-list" string.
void purple_menu_action_free(PurpleMenuAction *act)
Frees a PurpleMenuAction.
char * purple_fd_get_ip(int fd)
Returns the IP address from a socket file descriptor.
const char * purple_get_tzoff_str(const struct tm *tm, gboolean iso)
Gets a string representation of the local timezone offset.
gboolean purple_socket_speaks_ipv4(int fd)
Returns TRUE if a socket is capable of speaking IPv4.
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 ...
void purple_util_init(void)
Initializes the utility subsystem.
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)
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...
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.
const char * purple_url_encode(const char *str)
Encodes a URL into an escaped string.
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_util_get_image_extension(gconstpointer data, size_t len)
Returns an extension corresponding to the image data's file type.
char * purple_unescape_html(const char *html)
Unescapes HTML entities to their literal characters and converts "<br>" to "\n".
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.
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.
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.