Mercurial > pidgin3 / file comparison

comparison: src/log.h

src/log.h

branch
cpw.khc.msnp14
changeset 20472
6a6d2ef151e6
parent 13912
463b4fa9f067
parent 20469
b2836a24d81e
child 20473
91e1b3a49d10
equal deleted inserted replaced
13912:463b4fa9f067 20472:6a6d2ef151e6
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_ */

Mercurial Repository: pidgin3

mercurial