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