Mercurial > pidgin
comparison libgaim/log.h @ 14192:60b1bc8dbf37
[gaim-migrate @ 16863]
Renamed 'core' to 'libgaim'
committer: Tailor Script <tailor@pidgin.im>
author | Evan Schoenberg <evan.s@dreskin.net> |
---|---|
date | Sat, 19 Aug 2006 01:50:10 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
14191:009db0b357b5 | 14192:60b1bc8dbf37 |
---|---|
1 /** | |
2 * @file log.h Logging API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 */ | |
25 #ifndef _GAIM_LOG_H_ | |
26 #define _GAIM_LOG_H_ | |
27 | |
28 #include <stdio.h> | |
29 | |
30 | |
31 /******************************************************** | |
32 * DATA STRUCTURES ************************************** | |
33 ********************************************************/ | |
34 | |
35 typedef struct _GaimLog GaimLog; | |
36 typedef struct _GaimLogLogger GaimLogLogger; | |
37 typedef struct _GaimLogCommonLoggerData GaimLogCommonLoggerData; | |
38 typedef struct _GaimLogSet GaimLogSet; | |
39 | |
40 typedef enum { | |
41 GAIM_LOG_IM, | |
42 GAIM_LOG_CHAT, | |
43 GAIM_LOG_SYSTEM | |
44 } GaimLogType; | |
45 | |
46 typedef enum { | |
47 GAIM_LOG_READ_NO_NEWLINE = 1 | |
48 } GaimLogReadFlags; | |
49 | |
50 #include "account.h" | |
51 #include "conversation.h" | |
52 | |
53 typedef void (*GaimLogSetCallback) (GHashTable *sets, GaimLogSet *set); | |
54 | |
55 /** | |
56 * A log logger. | |
57 * | |
58 * This struct gets filled out and is included in the GaimLog. It contains everything | |
59 * needed to write and read from logs. | |
60 */ | |
61 struct _GaimLogLogger { | |
62 char *name; /**< The logger's name */ | |
63 char *id; /**< an identifier to refer to this logger */ | |
64 | |
65 /** This gets called when the log is first created. | |
66 I don't think this is actually needed. */ | |
67 void (*create)(GaimLog *log); | |
68 | |
69 /** This is used to write to the log file */ | |
70 gsize (*write)(GaimLog *log, | |
71 GaimMessageFlags type, | |
72 const char *from, | |
73 time_t time, | |
74 const char *message); | |
75 | |
76 /** Called when the log is destroyed */ | |
77 void (*finalize)(GaimLog *log); | |
78 | |
79 /** This function returns a sorted GList of available GaimLogs */ | |
80 GList *(*list)(GaimLogType type, const char *name, GaimAccount *account); | |
81 | |
82 /** Given one of the logs returned by the logger's list function, | |
83 * this returns the contents of the log in GtkIMHtml markup */ | |
84 char *(*read)(GaimLog *log, GaimLogReadFlags *flags); | |
85 | |
86 /** Given one of the logs returned by the logger's list function, | |
87 * this returns the size of the log in bytes */ | |
88 int (*size)(GaimLog *log); | |
89 | |
90 /** Returns the total size of all the logs. If this is undefined a default | |
91 * implementation is used */ | |
92 int (*total_size)(GaimLogType type, const char *name, GaimAccount *account); | |
93 | |
94 /** This function returns a sorted GList of available system GaimLogs */ | |
95 GList *(*list_syslog)(GaimAccount *account); | |
96 | |
97 /** Adds GaimLogSets to a GHashTable. By passing the data in the GaimLogSets | |
98 * to list, the caller can get every available GaimLog from the logger. | |
99 * Loggers using gaim_log_common_writer() (or otherwise storing their | |
100 * logs in the same directory structure as the stock loggers) do not | |
101 * need to implement this function. | |
102 * | |
103 * Loggers which implement this function must create a GaimLogSet, | |
104 * then call @a cb with @a sets and the newly created GaimLogSet. */ | |
105 void (*get_log_sets)(GaimLogSetCallback cb, GHashTable *sets); | |
106 }; | |
107 | |
108 /** | |
109 * A log. Not the wooden type. | |
110 */ | |
111 struct _GaimLog { | |
112 GaimLogType type; /**< The type of log this is */ | |
113 char *name; /**< The name of this log */ | |
114 GaimAccount *account; /**< The account this log is taking | |
115 place on */ | |
116 GaimConversation *conv; /**< The conversation being logged */ | |
117 time_t time; /**< The time this conversation | |
118 started, converted to the local timezone */ | |
119 | |
120 GaimLogLogger *logger; /**< The logging mechanism this log | |
121 is to use */ | |
122 void *logger_data; /**< Data used by the log logger */ | |
123 struct tm *tm; /**< The time this conversation | |
124 started, saved with original | |
125 timezone data, if available and | |
126 if struct tm has the BSD | |
127 timezone fields, else @c NULL. | |
128 Do NOT modify anything in this struct.*/ | |
129 | |
130 /* IMPORTANT: Some code in log.c allocates these without zeroing them. | |
131 * IMPORTANT: Update that code if you add members here. */ | |
132 }; | |
133 | |
134 /** | |
135 * A common logger_data struct containing a file handle and path, as well | |
136 * as a pointer to something else for additional data. | |
137 */ | |
138 struct _GaimLogCommonLoggerData { | |
139 char *path; | |
140 FILE *file; | |
141 void *extra_data; | |
142 }; | |
143 | |
144 /** | |
145 * Describes available logs. | |
146 * | |
147 * By passing the elements of this struct to gaim_log_get_logs(), the caller | |
148 * can get all available GaimLogs. | |
149 */ | |
150 struct _GaimLogSet { | |
151 GaimLogType type; /**< The type of logs available */ | |
152 char *name; /**< The name of the logs available */ | |
153 GaimAccount *account; /**< The account the available logs | |
154 took place on. This will be | |
155 @c NULL if the account no longer | |
156 exists. (Depending on a | |
157 logger's implementation of | |
158 list, it may not be possible | |
159 to load such logs.) */ | |
160 gboolean buddy; /**< Is this (account, name) a buddy | |
161 on the buddy list? */ | |
162 char *normalized_name; /**< The normalized version of | |
163 @a name. It must be set, and | |
164 may be set to the same pointer | |
165 value as @a name. */ | |
166 | |
167 /* IMPORTANT: Some code in log.c allocates these without zeroing them. | |
168 * IMPORTANT: Update that code if you add members here. */ | |
169 }; | |
170 | |
171 #ifdef __cplusplus | |
172 extern "C" { | |
173 #endif | |
174 | |
175 /***************************************/ | |
176 /** @name Log Functions */ | |
177 /***************************************/ | |
178 /*@{*/ | |
179 | |
180 /** | |
181 * Creates a new log | |
182 * | |
183 * @param type The type of log this is. | |
184 * @param name The name of this conversation (screenname, chat name, | |
185 * etc.) | |
186 * @param account The account the conversation is occurring on | |
187 * @param conv The conversation being logged | |
188 * @param time The time this conversation started | |
189 * @param tm The time this conversation started, with timezone data, | |
190 * if available and if struct tm has the BSD timezone fields. | |
191 * @return The new log | |
192 */ | |
193 GaimLog *gaim_log_new(GaimLogType type, const char *name, GaimAccount *account, | |
194 GaimConversation *conv, time_t time, const struct tm *tm); | |
195 | |
196 /** | |
197 * Frees a log | |
198 * | |
199 * @param log The log to destroy | |
200 */ | |
201 void gaim_log_free(GaimLog *log); | |
202 | |
203 /** | |
204 * Writes to a log file. Assumes you have checked preferences already. | |
205 * | |
206 * @param log The log to write to | |
207 * @param type The type of message being logged | |
208 * @param from Whom this message is coming from, or @c NULL for | |
209 * system messages | |
210 * @param time A timestamp in UNIX time | |
211 * @param message The message to log | |
212 */ | |
213 void gaim_log_write(GaimLog *log, | |
214 GaimMessageFlags type, | |
215 const char *from, | |
216 time_t time, | |
217 const char *message); | |
218 | |
219 /** | |
220 * Reads from a log | |
221 * | |
222 * @param log The log to read from | |
223 * @param flags The returned logging flags. | |
224 * | |
225 * @return The contents of this log in Gaim Markup. | |
226 */ | |
227 char *gaim_log_read(GaimLog *log, GaimLogReadFlags *flags); | |
228 | |
229 /** | |
230 * Returns a list of all available logs | |
231 * | |
232 * @param type The type of the log | |
233 * @param name The name of the log | |
234 * @param account The account | |
235 * @return A sorted list of GaimLogs | |
236 */ | |
237 GList *gaim_log_get_logs(GaimLogType type, const char *name, GaimAccount *account); | |
238 | |
239 /** | |
240 * Returns a GHashTable of GaimLogSets. | |
241 * | |
242 * A "log set" here means the information necessary to gather the | |
243 * GaimLogs for a given buddy/chat. This information would be passed | |
244 * to gaim_log_list to get a list of GaimLogs. | |
245 * | |
246 * The primary use of this function is to get a list of everyone the | |
247 * user has ever talked to (assuming he or she uses logging). | |
248 * | |
249 * The GHashTable that's returned will free all log sets in it when | |
250 * destroyed. If a GaimLogSet is removed from the GHashTable, it | |
251 * must be freed with gaim_log_set_free(). | |
252 * | |
253 * @return A GHashTable of all available unique GaimLogSets | |
254 */ | |
255 GHashTable *gaim_log_get_log_sets(void); | |
256 | |
257 /** | |
258 * Returns a list of all available system logs | |
259 * | |
260 * @param account The account | |
261 * @return A sorted list of GaimLogs | |
262 */ | |
263 GList *gaim_log_get_system_logs(GaimAccount *account); | |
264 | |
265 /** | |
266 * Returns the size of a log | |
267 * | |
268 * @param log The log | |
269 * @return The size of the log, in bytes | |
270 */ | |
271 int gaim_log_get_size(GaimLog *log); | |
272 | |
273 /** | |
274 * Returns the size, in bytes, of all available logs in this conversation | |
275 * | |
276 * @param type The type of the log | |
277 * @param name The name of the log | |
278 * @param account The account | |
279 * @return The size in bytes | |
280 */ | |
281 int gaim_log_get_total_size(GaimLogType type, const char *name, GaimAccount *account); | |
282 | |
283 /** | |
284 * Returns the default logger directory Gaim uses for a given account | |
285 * and username. This would be where Gaim stores logs created by | |
286 * the built-in text or HTML loggers. | |
287 * | |
288 * @param type The type of the log. | |
289 * @param name The name of the log. | |
290 * @param account The account. | |
291 * @return The default logger directory for Gaim. | |
292 */ | |
293 char *gaim_log_get_log_dir(GaimLogType type, const char *name, GaimAccount *account); | |
294 | |
295 /** | |
296 * Implements GCompareFunc for GaimLogs | |
297 * | |
298 * @param y A GaimLog | |
299 * @param z Another GaimLog | |
300 * @return A value as specified by GCompareFunc | |
301 */ | |
302 gint gaim_log_compare(gconstpointer y, gconstpointer z); | |
303 | |
304 /** | |
305 * Implements GCompareFunc for GaimLogSets | |
306 * | |
307 * @param y A GaimLogSet | |
308 * @param z Another GaimLogSet | |
309 * @return A value as specified by GCompareFunc | |
310 */ | |
311 gint gaim_log_set_compare(gconstpointer y, gconstpointer z); | |
312 | |
313 /** | |
314 * Frees a log set | |
315 * | |
316 * @param set The log set to destroy | |
317 */ | |
318 void gaim_log_set_free(GaimLogSet *set); | |
319 | |
320 /*@}*/ | |
321 | |
322 /******************************************/ | |
323 /** @name Common Logger Functions */ | |
324 /******************************************/ | |
325 /*@{*/ | |
326 | |
327 /** | |
328 * Opens a new log file in the standard Gaim log location | |
329 * with the given file extension, named for the current time, | |
330 * for writing. If a log file is already open, the existing | |
331 * file handle is retained. The log's logger_data value is | |
332 * set to a GaimLogCommonLoggerData struct containing the log | |
333 * file handle and log path. | |
334 * | |
335 * @param log The log to write to. | |
336 * @param ext The file extension to give to this log file. | |
337 */ | |
338 void gaim_log_common_writer(GaimLog *log, const char *ext); | |
339 | |
340 /** | |
341 * Returns a sorted GList of GaimLogs of the requested type. | |
342 * This function should only be used with logs that are written | |
343 * with gaim_log_common_writer(). | |
344 * | |
345 * @param type The type of the logs being listed. | |
346 * @param name The name of the log. | |
347 * @param account The account of the log. | |
348 * @param ext The file extension this log format uses. | |
349 * @param logger A reference to the logger struct for this log. | |
350 * | |
351 * @return A sorted GList of GaimLogs matching the parameters. | |
352 */ | |
353 GList *gaim_log_common_lister(GaimLogType type, const char *name, | |
354 GaimAccount *account, const char *ext, | |
355 GaimLogLogger *logger); | |
356 | |
357 /** | |
358 * Returns the total size of all the logs for a given user, with | |
359 * a given extension. This is the "common" implemention of a | |
360 * logger's total_size function. | |
361 * This function should only be used with logs that are written | |
362 * with gaim_log_common_writer(). | |
363 * | |
364 * @param type The type of the logs being sized. | |
365 * @param name The name of the logs to size | |
366 * (e.g. the username or chat name). | |
367 * @param account The account of the log. | |
368 * @param ext The file extension this log format uses. | |
369 * | |
370 * @return The size of all the logs with the specified extension | |
371 * for the specified user. | |
372 */ | |
373 int gaim_log_common_total_sizer(GaimLogType type, const char *name, | |
374 GaimAccount *account, const char *ext); | |
375 | |
376 /** | |
377 * Returns the size of a given GaimLog. | |
378 * This function should only be used with logs that are written | |
379 * with gaim_log_common_writer(). | |
380 * | |
381 * @param log The GaimLog to size. | |
382 * | |
383 * @return An integer indicating the size of the log in bytes. | |
384 */ | |
385 int gaim_log_common_sizer(GaimLog *log); | |
386 /*@}*/ | |
387 | |
388 /******************************************/ | |
389 /** @name Logger Functions */ | |
390 /******************************************/ | |
391 /*@{*/ | |
392 | |
393 /** | |
394 * Creates a new logger | |
395 * | |
396 * @param id The logger's id. | |
397 * @param name The logger's name. | |
398 * @param functions The number of functions being passed. The following | |
399 * functions are currently available (in order): @c create, | |
400 * @c write, @c finalize, @c list, @c read, @c size, | |
401 * @c total_size, @c list_syslog, @c get_log_sets. For | |
402 * details on these functions, see GaimLogLogger. | |
403 * Functions may not be skipped. For example, passing | |
404 * @c create and @c write is acceptable (for a total of | |
405 * two functions). Passing @c create and @c finalize, | |
406 * however, is not. To accomplish that, the caller must | |
407 * pass @c create, @c NULL (a placeholder for @c write), | |
408 * and @c finalize (for a total of 3 functions). | |
409 * | |
410 * @return The new logger | |
411 */ | |
412 GaimLogLogger *gaim_log_logger_new(const char *id, const char *name, int functions, ...); | |
413 | |
414 /** | |
415 * Frees a logger | |
416 * | |
417 * @param logger The logger to free | |
418 */ | |
419 void gaim_log_logger_free(GaimLogLogger *logger); | |
420 | |
421 /** | |
422 * Adds a new logger | |
423 * | |
424 * @param logger The new logger to add | |
425 */ | |
426 void gaim_log_logger_add (GaimLogLogger *logger); | |
427 | |
428 /** | |
429 * | |
430 * Removes a logger | |
431 * | |
432 * @param logger The logger to remove | |
433 */ | |
434 void gaim_log_logger_remove (GaimLogLogger *logger); | |
435 | |
436 /** | |
437 * | |
438 * Sets the current logger | |
439 * | |
440 * @param logger The logger to set | |
441 */ | |
442 void gaim_log_logger_set (GaimLogLogger *logger); | |
443 | |
444 /** | |
445 * | |
446 * Returns the current logger | |
447 * | |
448 * @return logger The current logger | |
449 */ | |
450 GaimLogLogger *gaim_log_logger_get (void); | |
451 | |
452 /** | |
453 * Returns a GList containing the IDs and names of the registered | |
454 * loggers. | |
455 * | |
456 * @return The list of IDs and names. | |
457 */ | |
458 GList *gaim_log_logger_get_options(void); | |
459 | |
460 /**************************************************************************/ | |
461 /** @name Log Subsystem */ | |
462 /**************************************************************************/ | |
463 /*@{*/ | |
464 | |
465 /** | |
466 * Initializes the log subsystem. | |
467 */ | |
468 void gaim_log_init(void); | |
469 | |
470 /** | |
471 * Returns the log subsystem handle. | |
472 * | |
473 * @return The log subsystem handle. | |
474 */ | |
475 void *gaim_log_get_handle(void); | |
476 | |
477 /** | |
478 * Uninitializes the log subsystem. | |
479 */ | |
480 void gaim_log_uninit(void); | |
481 | |
482 /*@}*/ | |
483 | |
484 | |
485 #ifdef __cplusplus | |
486 } | |
487 #endif | |
488 | |
489 #endif /* _GAIM_LOG_H_ */ |