Mercurial > pidgin3 / file comparison

comparison: src/util.h

src/util.h

changeset 4890
d87a9b5bbe57
child 5034
077678f7b048
equal deleted inserted replaced
4889:9c81754db28e 4890:d87a9b5bbe57
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_ */

Mercurial Repository: pidgin3

mercurial