Mercurial > pidgin
annotate src/util.h @ 6494:4f93f10ddc75
[gaim-migrate @ 7009]
Updates for new signal mechanism.. Nice job Christian.
committer: Tailor Script <tailor@pidgin.im>
author | Herman Bloggs <hermanator12002@yahoo.com> |
---|---|
date | Mon, 18 Aug 2003 17:50:24 +0000 |
parents | 2fed50891afa |
children | 41120df7ed94 |
rev | line source |
---|---|
4890 | 1 /** |
2 * @file util.h Utility Functions | |
5034
4691c5936c01
[gaim-migrate @ 5377]
Christian Hammond <chipx86@chipx86.com>
parents:
4890
diff
changeset
|
3 * @ingroup core |
4890 | 4 * |
5 * gaim | |
6 * | |
7 * Copyright (C) 2002-2003, Christian Hammond <chipx86@gnupdate.org> | |
8 * | |
9 * This program is free software; you can redistribute it and/or modify | |
10 * it under the terms of the GNU General Public License as published by | |
11 * the Free Software Foundation; either version 2 of the License, or | |
12 * (at your option) any later version. | |
13 * | |
14 * This program is distributed in the hope that it will be useful, | |
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 * GNU General Public License for more details. | |
18 * | |
19 * You should have received a copy of the GNU General Public License | |
20 * along with this program; if not, write to the Free Software | |
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
22 * | |
23 * @todo Rename the functions so that they live somewhere in the gaim | |
24 * namespace. | |
25 */ | |
26 #ifndef _GAIM_UTIL_H_ | |
27 #define _GAIM_UTIL_H_ | |
28 | |
6474
2fed50891afa
[gaim-migrate @ 6983]
Christian Hammond <chipx86@chipx86.com>
parents:
5944
diff
changeset
|
29 #include <stdio.h> |
2fed50891afa
[gaim-migrate @ 6983]
Christian Hammond <chipx86@chipx86.com>
parents:
5944
diff
changeset
|
30 |
5563
9eb5b13fd412
[gaim-migrate @ 5965]
Christian Hammond <chipx86@chipx86.com>
parents:
5532
diff
changeset
|
31 #include "account.h" |
9eb5b13fd412
[gaim-migrate @ 5965]
Christian Hammond <chipx86@chipx86.com>
parents:
5532
diff
changeset
|
32 |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
33 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
34 extern "C" { |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
35 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
36 |
4890 | 37 /** |
38 * Normalizes a string, so that it is suitable for comparison. | |
39 * | |
40 * The returned string will point to a static buffer, so if the | |
41 * string is intended to be kept long-term, you <i>must</i> | |
42 * g_strdup() it. Also, calling normalize() twice in the same line | |
43 * will lead to problems. | |
44 * | |
45 * @param str The string to normalize. | |
46 * | |
47 * @return A pointer to the normalized version stored in a static buffer. | |
48 */ | |
49 char *normalize(const char *str); | |
50 | |
51 /** | |
52 * Converts a string to its base-64 equivalent. | |
53 * | |
5426 | 54 * @param buf The data to convert. |
5532 | 55 * @param len The length of the data. |
4890 | 56 * |
57 * @return The base-64 version of @a str. | |
58 * | |
59 * @see frombase64() | |
60 */ | |
5426 | 61 char *tobase64(const unsigned char *buf, size_t len); |
4890 | 62 |
63 /** | |
64 * Converts a string back from its base-64 equivalent. | |
65 * | |
66 * @param str The string to convert back. | |
67 * @param ret_str The returned, non-base-64 string. | |
68 * @param ret_len The returned string length. | |
69 * | |
70 * @see tobase64() | |
71 */ | |
72 void frombase64(const char *str, char **ret_str, int *ret_len); | |
73 | |
74 /** | |
75 * Converts a string to its base-16 equivalent. | |
76 * | |
77 * @param str The string to convert. | |
78 * @param len The length of the string. | |
79 * | |
80 * @return The base-16 string. | |
81 * | |
82 * @see frombase16() | |
83 */ | |
5451 | 84 unsigned char *tobase16(const unsigned char *str, int len); |
4890 | 85 |
86 /** | |
87 * Converts a string back from its base-16 equivalent. | |
88 * | |
89 * @param str The string to convert back. | |
90 * @param ret_str The returned, non-base-16 string. | |
5451 | 91 * |
4890 | 92 * @return The length of the returned string. |
93 * | |
94 * @see tobase16() | |
95 */ | |
5497 | 96 int frombase16(const char *str, unsigned char **ret_str); |
4890 | 97 |
98 /** | |
99 * Waits for all child processes to terminate. | |
100 */ | |
101 void clean_pid(void); | |
102 | |
103 /** | |
104 * Returns the current local time in hour:minute:second form. | |
105 * | |
106 * The returned string is stored in a static buffer, so the result | |
107 * should be g_strdup()'d if it's intended to be used for long. | |
108 * | |
109 * @return The current local time. | |
110 * | |
111 * @see full_date() | |
112 */ | |
113 char *date(void); | |
114 | |
115 /** | |
116 * Adds the necessary HTML code to turn URIs into HTML links in a string. | |
117 * | |
5136 | 118 * @param str The string to linkify. |
4890 | 119 * |
5136 | 120 * @return The linkified text. |
4890 | 121 */ |
5136 | 122 char *linkify_text(const char *str); |
4890 | 123 |
124 /** | |
125 * Converts seconds into a human-readable form. | |
126 * | |
127 * @param sec The seconds. | |
128 * | |
129 * @return A human-readable form, containing days, hours, minutes, and | |
130 * seconds. | |
131 */ | |
132 char *sec_to_text(guint sec); | |
133 | |
134 /** | |
135 * Returns the date and time in human-readable form. | |
136 * | |
137 * The returned string is stored in a static buffer, so the result | |
138 * should be g_strdup()'d if it's intended to be used for long. | |
139 * | |
140 * @return The date and time in human-readable form. | |
141 * | |
142 * @see date() | |
143 */ | |
5563
9eb5b13fd412
[gaim-migrate @ 5965]
Christian Hammond <chipx86@chipx86.com>
parents:
5532
diff
changeset
|
144 char *full_date(void); |
4890 | 145 |
146 /** | |
147 * Looks for %n, %d, or %t in a string, and replaces them with the | |
148 * specified name, date, and time, respectively. | |
149 * | |
150 * The returned string is stored in a static buffer, so the result | |
151 * should be g_strdup()'d if it's intended to be used for long. | |
152 * | |
153 * @param str The string that may contain the special variables. | |
154 * @param name The sender name. | |
155 * | |
156 * @return A new string where the special variables are expanded. | |
157 */ | |
158 char *away_subs(const char *str, const char *name); | |
159 | |
160 /**` | |
161 * Returns the user's home directory. | |
162 * | |
163 * @return The user's home directory. | |
164 * | |
165 * @see gaim_user_dir() | |
166 */ | |
167 const gchar *gaim_home_dir(void); | |
168 | |
169 /** | |
170 * Returns the gaim settings directory in the user's home directory. | |
171 * | |
172 * @return The gaim settings directory. | |
173 * | |
174 * @see gaim_home_dir() | |
175 */ | |
176 char *gaim_user_dir(void); | |
177 | |
178 /** | |
179 * Copies a string and replaces all HTML linebreaks with newline characters. | |
180 * | |
181 * @param dest The destination string. | |
182 * @param src The source string. | |
183 * @param dest_len The destination string length. | |
184 * | |
185 * @see strncpy_withhtml() | |
186 * @see strdup_withhtml() | |
187 */ | |
188 void strncpy_nohtml(gchar *dest, const gchar *src, size_t dest_len); | |
189 | |
190 /** | |
191 * Copies a string and replaces all newline characters with HTML linebreaks. | |
192 * | |
193 * @param dest The destination string. | |
194 * @param src The source string. | |
195 * @param dest_len The destination string length. | |
196 * | |
197 * @see strncpy_nohtml() | |
198 * @see strdup_withhtml() | |
199 */ | |
200 void strncpy_withhtml(gchar *dest, const gchar *src, size_t dest_len); | |
201 | |
202 /** | |
203 * Duplicates a string and replaces all newline characters from the | |
204 * source string with HTML linebreaks. | |
205 * | |
206 * @param src The source string. | |
207 * | |
208 * @return The new string. | |
209 * | |
210 * @see strncpy_nohtml() | |
211 * @see strncpy_withhtml() | |
212 */ | |
213 gchar *strdup_withhtml(const gchar *src); | |
214 | |
215 /** | |
216 * Ensures that all linefeeds have a matching carriage return. | |
217 * | |
218 * @param str The source string. | |
219 * | |
220 * @return The string with carriage returns. | |
221 */ | |
5136 | 222 char *add_cr(const char *); |
4890 | 223 |
224 /** | |
225 * Strips all linefeeds from a string. | |
226 * | |
227 * @param str The string to strip linefeeds from. | |
228 */ | |
229 void strip_linefeed(char *str); | |
230 | |
231 /** | |
232 * Builds a time_t from the supplied information. | |
233 * | |
234 * @param year The year. | |
235 * @param month The month. | |
236 * @param day The day. | |
237 * @param hour The hour. | |
238 * @param min The minute. | |
239 * @param sec The second. | |
240 * | |
241 * @return A time_t. | |
242 */ | |
243 time_t get_time(int year, int month, int day, | |
5563
9eb5b13fd412
[gaim-migrate @ 5965]
Christian Hammond <chipx86@chipx86.com>
parents:
5532
diff
changeset
|
244 int hour, int min, int sec); |
4890 | 245 |
246 /** | |
247 * Creates a temporary file and returns a file pointer to it. | |
248 * | |
249 * This is like mkstemp(), but returns a file pointer and uses a | |
250 * pre-set template. It uses the semantics of tempnam() for the | |
251 * directory to use and allocates the space for the file path. | |
252 * | |
253 * The caller is responsible for closing the file and removing it when | |
254 * done, as well as freeing the space pointed to by @a path with | |
255 * g_free(). | |
256 * | |
257 * @param path The returned path to the temp file. | |
258 * | |
259 * @return A file pointer to the temporary file, or @c NULL on failure. | |
260 */ | |
261 FILE *gaim_mkstemp(gchar **path); | |
262 | |
263 /** | |
264 * Attempts to convert a string to UTF-8 from an unknown encoding. | |
265 * | |
266 * This function checks the locale and tries sane defaults. | |
267 * | |
268 * @param str The source string. | |
269 * | |
270 * @return The UTF-8 string, or @c NULL if it could not be converted. | |
271 */ | |
272 char *gaim_try_conv_to_utf8(const char *str); | |
273 | |
274 /** | |
275 * Returns the IP address from a socket file descriptor. | |
276 * | |
277 * @param fd The socket file descriptor. | |
278 * | |
279 * @return The IP address, or @c NULL on error. | |
280 */ | |
281 char *gaim_getip_from_fd(int fd); | |
282 | |
283 /** | |
284 * Compares two UTF-8 strings. | |
285 * | |
286 * @param a The first string. | |
287 * @param b The second string. | |
288 * | |
289 * @return -1 if @a is less than @a b. | |
290 * 0 if @a is equal to @a b. | |
291 * 1 if @a is greater than @a b. | |
292 */ | |
293 gint gaim_utf8_strcasecmp(const gchar *a, const gchar *b); | |
294 | |
5515 | 295 /** |
296 * Given a string, this replaces one substring with another | |
297 * and returns a newly allocated string. | |
298 * | |
299 * @param string The string from which to replace stuff. | |
300 * @param delimiter The substring you want replaced. | |
301 * @param replacement The substring you want inserted in place | |
302 * of the delimiting substring. | |
303 */ | |
5874
964e4f94fc56
[gaim-migrate @ 6306]
Christian Hammond <chipx86@chipx86.com>
parents:
5872
diff
changeset
|
304 gchar *gaim_strreplace(const gchar *string, const gchar *delimiter, |
964e4f94fc56
[gaim-migrate @ 6306]
Christian Hammond <chipx86@chipx86.com>
parents:
5872
diff
changeset
|
305 const gchar *replacement); |
5515 | 306 |
5826 | 307 /** |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
308 * Returns a string representing a filesize in the appropriate |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
309 * units (MB, KB, GB, etc.) |
5826 | 310 * |
311 * @param size The size | |
312 */ | |
313 char *gaim_get_size_string(size_t size); | |
314 | |
5944
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
315 #ifdef __cplusplus |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
316 } |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
317 #endif |
158196b2db19
[gaim-migrate @ 6385]
Christian Hammond <chipx86@chipx86.com>
parents:
5943
diff
changeset
|
318 |
4890 | 319 #endif /* _GAIM_UTIL_H_ */ |