1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/Frameworks/libpurple.framework/Versions/0.6.2/Headers/log.h Fri Aug 21 13:25:11 2009 -0700
1.3 @@ -0,0 +1,583 @@
1.4 +/**
1.5 + * @file log.h Logging API
1.6 + * @ingroup core
1.7 + * @see @ref log-signals
1.8 + */
1.9 +
1.10 +/* purple
1.11 + *
1.12 + * Purple is the legal property of its developers, whose names are too numerous
1.13 + * to list here. Please refer to the COPYRIGHT file distributed with this
1.14 + * source distribution.
1.15 + *
1.16 + * This program is free software; you can redistribute it and/or modify
1.17 + * it under the terms of the GNU General Public License as published by
1.18 + * the Free Software Foundation; either version 2 of the License, or
1.19 + * (at your option) any later version.
1.20 + *
1.21 + * This program is distributed in the hope that it will be useful,
1.22 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
1.23 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1.24 + * GNU General Public License for more details.
1.25 + *
1.26 + * You should have received a copy of the GNU General Public License
1.27 + * along with this program; if not, write to the Free Software
1.28 + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
1.29 + */
1.30 +#ifndef _PURPLE_LOG_H_
1.31 +#define _PURPLE_LOG_H_
1.32 +
1.33 +#include <stdio.h>
1.34 +
1.35 +
1.36 +/********************************************************
1.37 + * DATA STRUCTURES **************************************
1.38 + ********************************************************/
1.39 +
1.40 +typedef struct _PurpleLog PurpleLog;
1.41 +typedef struct _PurpleLogLogger PurpleLogLogger;
1.42 +typedef struct _PurpleLogCommonLoggerData PurpleLogCommonLoggerData;
1.43 +typedef struct _PurpleLogSet PurpleLogSet;
1.44 +
1.45 +typedef enum {
1.46 + PURPLE_LOG_IM,
1.47 + PURPLE_LOG_CHAT,
1.48 + PURPLE_LOG_SYSTEM
1.49 +} PurpleLogType;
1.50 +
1.51 +typedef enum {
1.52 + PURPLE_LOG_READ_NO_NEWLINE = 1
1.53 +} PurpleLogReadFlags;
1.54 +
1.55 +#include "account.h"
1.56 +#include "conversation.h"
1.57 +
1.58 +typedef void (*PurpleLogSetCallback) (GHashTable *sets, PurpleLogSet *set);
1.59 +
1.60 +/**
1.61 + * A log logger.
1.62 + *
1.63 + * This struct gets filled out and is included in the PurpleLog. It contains everything
1.64 + * needed to write and read from logs.
1.65 + */
1.66 +struct _PurpleLogLogger {
1.67 + char *name; /**< The logger's name */
1.68 + char *id; /**< an identifier to refer to this logger */
1.69 +
1.70 + /** This gets called when the log is first created.
1.71 + I don't think this is actually needed. */
1.72 + void (*create)(PurpleLog *log);
1.73 +
1.74 + /** This is used to write to the log file */
1.75 + gsize (*write)(PurpleLog *log,
1.76 + PurpleMessageFlags type,
1.77 + const char *from,
1.78 + time_t time,
1.79 + const char *message);
1.80 +
1.81 + /** Called when the log is destroyed */
1.82 + void (*finalize)(PurpleLog *log);
1.83 +
1.84 + /** This function returns a sorted GList of available PurpleLogs */
1.85 + GList *(*list)(PurpleLogType type, const char *name, PurpleAccount *account);
1.86 +
1.87 + /** Given one of the logs returned by the logger's list function,
1.88 + * this returns the contents of the log in GtkIMHtml markup */
1.89 + char *(*read)(PurpleLog *log, PurpleLogReadFlags *flags);
1.90 +
1.91 + /** Given one of the logs returned by the logger's list function,
1.92 + * this returns the size of the log in bytes */
1.93 + int (*size)(PurpleLog *log);
1.94 +
1.95 + /** Returns the total size of all the logs. If this is undefined a default
1.96 + * implementation is used */
1.97 + int (*total_size)(PurpleLogType type, const char *name, PurpleAccount *account);
1.98 +
1.99 + /** This function returns a sorted GList of available system PurpleLogs */
1.100 + GList *(*list_syslog)(PurpleAccount *account);
1.101 +
1.102 + /** Adds PurpleLogSets to a GHashTable. By passing the data in the PurpleLogSets
1.103 + * to list, the caller can get every available PurpleLog from the logger.
1.104 + * Loggers using purple_log_common_writer() (or otherwise storing their
1.105 + * logs in the same directory structure as the stock loggers) do not
1.106 + * need to implement this function.
1.107 + *
1.108 + * Loggers which implement this function must create a PurpleLogSet,
1.109 + * then call @a cb with @a sets and the newly created PurpleLogSet. */
1.110 + void (*get_log_sets)(PurpleLogSetCallback cb, GHashTable *sets);
1.111 +
1.112 + /* Attempts to delete the specified log, indicating success or failure */
1.113 + gboolean (*remove)(PurpleLog *log);
1.114 +
1.115 + /* Tests whether a log is deletable */
1.116 + gboolean (*is_deletable)(PurpleLog *log);
1.117 +
1.118 + void (*_purple_reserved1)(void);
1.119 + void (*_purple_reserved2)(void);
1.120 + void (*_purple_reserved3)(void);
1.121 + void (*_purple_reserved4)(void);
1.122 +};
1.123 +
1.124 +/**
1.125 + * A log. Not the wooden type.
1.126 + */
1.127 +struct _PurpleLog {
1.128 + PurpleLogType type; /**< The type of log this is */
1.129 + char *name; /**< The name of this log */
1.130 + PurpleAccount *account; /**< The account this log is taking
1.131 + place on */
1.132 + PurpleConversation *conv; /**< The conversation being logged */
1.133 + time_t time; /**< The time this conversation
1.134 + started, converted to the local timezone */
1.135 +
1.136 + PurpleLogLogger *logger; /**< The logging mechanism this log
1.137 + is to use */
1.138 + void *logger_data; /**< Data used by the log logger */
1.139 + struct tm *tm; /**< The time this conversation
1.140 + started, saved with original
1.141 + timezone data, if available and
1.142 + if struct tm has the BSD
1.143 + timezone fields, else @c NULL.
1.144 + Do NOT modify anything in this struct.*/
1.145 +
1.146 + /* IMPORTANT: Some code in log.c allocates these without zeroing them.
1.147 + * IMPORTANT: Update that code if you add members here. */
1.148 +};
1.149 +
1.150 +/**
1.151 + * A common logger_data struct containing a file handle and path, as well
1.152 + * as a pointer to something else for additional data.
1.153 + */
1.154 +struct _PurpleLogCommonLoggerData {
1.155 + char *path;
1.156 + FILE *file;
1.157 + void *extra_data;
1.158 +};
1.159 +
1.160 +/**
1.161 + * Describes available logs.
1.162 + *
1.163 + * By passing the elements of this struct to purple_log_get_logs(), the caller
1.164 + * can get all available PurpleLogs.
1.165 + */
1.166 +struct _PurpleLogSet {
1.167 + PurpleLogType type; /**< The type of logs available */
1.168 + char *name; /**< The name of the logs available */
1.169 + PurpleAccount *account; /**< The account the available logs
1.170 + took place on. This will be
1.171 + @c NULL if the account no longer
1.172 + exists. (Depending on a
1.173 + logger's implementation of
1.174 + list, it may not be possible
1.175 + to load such logs.) */
1.176 + gboolean buddy; /**< Is this (account, name) a buddy
1.177 + on the buddy list? */
1.178 + char *normalized_name; /**< The normalized version of
1.179 + @a name. It must be set, and
1.180 + may be set to the same pointer
1.181 + value as @a name. */
1.182 +
1.183 + /* IMPORTANT: Some code in log.c allocates these without zeroing them.
1.184 + * IMPORTANT: Update that code if you add members here. */
1.185 +};
1.186 +
1.187 +#ifdef __cplusplus
1.188 +extern "C" {
1.189 +#endif
1.190 +
1.191 +/***************************************/
1.192 +/** @name Log Functions */
1.193 +/***************************************/
1.194 +/*@{*/
1.195 +
1.196 +/**
1.197 + * Creates a new log
1.198 + *
1.199 + * @param type The type of log this is.
1.200 + * @param name The name of this conversation (buddy name, chat name,
1.201 + * etc.)
1.202 + * @param account The account the conversation is occurring on
1.203 + * @param conv The conversation being logged
1.204 + * @param time The time this conversation started
1.205 + * @param tm The time this conversation started, with timezone data,
1.206 + * if available and if struct tm has the BSD timezone fields.
1.207 + * @return The new log
1.208 + */
1.209 +PurpleLog *purple_log_new(PurpleLogType type, const char *name, PurpleAccount *account,
1.210 + PurpleConversation *conv, time_t time, const struct tm *tm);
1.211 +
1.212 +/**
1.213 + * Frees a log
1.214 + *
1.215 + * @param log The log to destroy
1.216 + */
1.217 +void purple_log_free(PurpleLog *log);
1.218 +
1.219 +/**
1.220 + * Writes to a log file. Assumes you have checked preferences already.
1.221 + *
1.222 + * @param log The log to write to
1.223 + * @param type The type of message being logged
1.224 + * @param from Whom this message is coming from, or @c NULL for
1.225 + * system messages
1.226 + * @param time A timestamp in UNIX time
1.227 + * @param message The message to log
1.228 + */
1.229 +void purple_log_write(PurpleLog *log,
1.230 + PurpleMessageFlags type,
1.231 + const char *from,
1.232 + time_t time,
1.233 + const char *message);
1.234 +
1.235 +/**
1.236 + * Reads from a log
1.237 + *
1.238 + * @param log The log to read from
1.239 + * @param flags The returned logging flags.
1.240 + *
1.241 + * @return The contents of this log in Purple Markup.
1.242 + */
1.243 +char *purple_log_read(PurpleLog *log, PurpleLogReadFlags *flags);
1.244 +
1.245 +/**
1.246 + * Returns a list of all available logs
1.247 + *
1.248 + * @param type The type of the log
1.249 + * @param name The name of the log
1.250 + * @param account The account
1.251 + * @return A sorted list of PurpleLogs
1.252 + */
1.253 +GList *purple_log_get_logs(PurpleLogType type, const char *name, PurpleAccount *account);
1.254 +
1.255 +/**
1.256 + * Returns a GHashTable of PurpleLogSets.
1.257 + *
1.258 + * A "log set" here means the information necessary to gather the
1.259 + * PurpleLogs for a given buddy/chat. This information would be passed
1.260 + * to purple_log_list to get a list of PurpleLogs.
1.261 + *
1.262 + * The primary use of this function is to get a list of everyone the
1.263 + * user has ever talked to (assuming he or she uses logging).
1.264 + *
1.265 + * The GHashTable that's returned will free all log sets in it when
1.266 + * destroyed. If a PurpleLogSet is removed from the GHashTable, it
1.267 + * must be freed with purple_log_set_free().
1.268 + *
1.269 + * @return A GHashTable of all available unique PurpleLogSets
1.270 + */
1.271 +GHashTable *purple_log_get_log_sets(void);
1.272 +
1.273 +/**
1.274 + * Returns a list of all available system logs
1.275 + *
1.276 + * @param account The account
1.277 + * @return A sorted list of PurpleLogs
1.278 + */
1.279 +GList *purple_log_get_system_logs(PurpleAccount *account);
1.280 +
1.281 +/**
1.282 + * Returns the size of a log
1.283 + *
1.284 + * @param log The log
1.285 + * @return The size of the log, in bytes
1.286 + */
1.287 +int purple_log_get_size(PurpleLog *log);
1.288 +
1.289 +/**
1.290 + * Returns the size, in bytes, of all available logs in this conversation
1.291 + *
1.292 + * @param type The type of the log
1.293 + * @param name The name of the log
1.294 + * @param account The account
1.295 + * @return The size in bytes
1.296 + */
1.297 +int purple_log_get_total_size(PurpleLogType type, const char *name, PurpleAccount *account);
1.298 +
1.299 +/**
1.300 + * Returns the activity score of a log, based on total size in bytes,
1.301 + * which is then decayed based on age
1.302 + *
1.303 + * @param type The type of the log
1.304 + * @param name The name of the log
1.305 + * @param account The account
1.306 + * @return The activity score
1.307 + *
1.308 + * @since 2.6.0
1.309 + */
1.310 +int purple_log_get_activity_score(PurpleLogType type, const char *name, PurpleAccount *account);
1.311 +
1.312 +/**
1.313 + * Tests whether a log is deletable
1.314 + *
1.315 + * A return value of @c FALSE indicates that purple_log_delete() will fail on this
1.316 + * log, unless something changes between the two calls. A return value of @c TRUE,
1.317 + * however, does not guarantee the log can be deleted.
1.318 + *
1.319 + * @param log The log
1.320 + * @return A boolean indicating if the log is deletable
1.321 + */
1.322 +gboolean purple_log_is_deletable(PurpleLog *log);
1.323 +
1.324 +/**
1.325 + * Deletes a log
1.326 + *
1.327 + * @param log The log
1.328 + * @return A boolean indicating success or failure
1.329 + */
1.330 +gboolean purple_log_delete(PurpleLog *log);
1.331 +
1.332 +/**
1.333 + * Returns the default logger directory Purple uses for a given account
1.334 + * and username. This would be where Purple stores logs created by
1.335 + * the built-in text or HTML loggers.
1.336 + *
1.337 + * @param type The type of the log.
1.338 + * @param name The name of the log.
1.339 + * @param account The account.
1.340 + * @return The default logger directory for Purple.
1.341 + */
1.342 +char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account);
1.343 +
1.344 +/**
1.345 + * Implements GCompareFunc for PurpleLogs
1.346 + *
1.347 + * @param y A PurpleLog
1.348 + * @param z Another PurpleLog
1.349 + * @return A value as specified by GCompareFunc
1.350 + */
1.351 +gint purple_log_compare(gconstpointer y, gconstpointer z);
1.352 +
1.353 +/**
1.354 + * Implements GCompareFunc for PurpleLogSets
1.355 + *
1.356 + * @param y A PurpleLogSet
1.357 + * @param z Another PurpleLogSet
1.358 + * @return A value as specified by GCompareFunc
1.359 + */
1.360 +gint purple_log_set_compare(gconstpointer y, gconstpointer z);
1.361 +
1.362 +/**
1.363 + * Frees a log set
1.364 + *
1.365 + * @param set The log set to destroy
1.366 + */
1.367 +void purple_log_set_free(PurpleLogSet *set);
1.368 +
1.369 +/*@}*/
1.370 +
1.371 +/******************************************/
1.372 +/** @name Common Logger Functions */
1.373 +/******************************************/
1.374 +/*@{*/
1.375 +
1.376 +/**
1.377 + * Opens a new log file in the standard Purple log location
1.378 + * with the given file extension, named for the current time,
1.379 + * for writing. If a log file is already open, the existing
1.380 + * file handle is retained. The log's logger_data value is
1.381 + * set to a PurpleLogCommonLoggerData struct containing the log
1.382 + * file handle and log path.
1.383 + *
1.384 + * This function is intended to be used as a "common"
1.385 + * implementation of a logger's @c write function.
1.386 + * It should only be passed to purple_log_logger_new() and never
1.387 + * called directly.
1.388 + *
1.389 + * @param log The log to write to.
1.390 + * @param ext The file extension to give to this log file.
1.391 + */
1.392 +void purple_log_common_writer(PurpleLog *log, const char *ext);
1.393 +
1.394 +/**
1.395 + * Returns a sorted GList of PurpleLogs of the requested type.
1.396 + *
1.397 + * This function should only be used with logs that are written
1.398 + * with purple_log_common_writer(). It's intended to be used as
1.399 + * a "common" implementation of a logger's @c list function.
1.400 + * It should only be passed to purple_log_logger_new() and never
1.401 + * called directly.
1.402 + *
1.403 + * @param type The type of the logs being listed.
1.404 + * @param name The name of the log.
1.405 + * @param account The account of the log.
1.406 + * @param ext The file extension this log format uses.
1.407 + * @param logger A reference to the logger struct for this log.
1.408 + *
1.409 + * @return A sorted GList of PurpleLogs matching the parameters.
1.410 + */
1.411 +GList *purple_log_common_lister(PurpleLogType type, const char *name,
1.412 + PurpleAccount *account, const char *ext,
1.413 + PurpleLogLogger *logger);
1.414 +
1.415 +/**
1.416 + * Returns the total size of all the logs for a given user, with
1.417 + * a given extension.
1.418 + *
1.419 + * This function should only be used with logs that are written
1.420 + * with purple_log_common_writer(). It's intended to be used as
1.421 + * a "common" implementation of a logger's @c total_size function.
1.422 + * It should only be passed to purple_log_logger_new() and never
1.423 + * called directly.
1.424 + *
1.425 + * @param type The type of the logs being sized.
1.426 + * @param name The name of the logs to size
1.427 + * (e.g. the username or chat name).
1.428 + * @param account The account of the log.
1.429 + * @param ext The file extension this log format uses.
1.430 + *
1.431 + * @return The size of all the logs with the specified extension
1.432 + * for the specified user.
1.433 + */
1.434 +int purple_log_common_total_sizer(PurpleLogType type, const char *name,
1.435 + PurpleAccount *account, const char *ext);
1.436 +
1.437 +/**
1.438 + * Returns the size of a given PurpleLog.
1.439 + *
1.440 + * This function should only be used with logs that are written
1.441 + * with purple_log_common_writer(). It's intended to be used as
1.442 + * a "common" implementation of a logger's @c size function.
1.443 + * It should only be passed to purple_log_logger_new() and never
1.444 + * called directly.
1.445 + *
1.446 + * @param log The PurpleLog to size.
1.447 + *
1.448 + * @return An integer indicating the size of the log in bytes.
1.449 + */
1.450 +int purple_log_common_sizer(PurpleLog *log);
1.451 +
1.452 +/**
1.453 + * Deletes a log
1.454 + *
1.455 + * This function should only be used with logs that are written
1.456 + * with purple_log_common_writer(). It's intended to be used as
1.457 + * a "common" implementation of a logger's @c delete function.
1.458 + * It should only be passed to purple_log_logger_new() and never
1.459 + * called directly.
1.460 + *
1.461 + * @param log The PurpleLog to delete.
1.462 + *
1.463 + * @return A boolean indicating success or failure.
1.464 + */
1.465 +gboolean purple_log_common_deleter(PurpleLog *log);
1.466 +
1.467 +/**
1.468 + * Checks to see if a log is deletable
1.469 + *
1.470 + * This function should only be used with logs that are written
1.471 + * with purple_log_common_writer(). It's intended to be used as
1.472 + * a "common" implementation of a logger's @c is_deletable function.
1.473 + * It should only be passed to purple_log_logger_new() and never
1.474 + * called directly.
1.475 + *
1.476 + * @param log The PurpleLog to check.
1.477 + *
1.478 + * @return A boolean indicating if the log is deletable.
1.479 + */
1.480 +gboolean purple_log_common_is_deletable(PurpleLog *log);
1.481 +
1.482 +/*@}*/
1.483 +
1.484 +/******************************************/
1.485 +/** @name Logger Functions */
1.486 +/******************************************/
1.487 +/*@{*/
1.488 +
1.489 +/**
1.490 + * Creates a new logger
1.491 + *
1.492 + * @param id The logger's id.
1.493 + * @param name The logger's name.
1.494 + * @param functions The number of functions being passed. The following
1.495 + * functions are currently available (in order): @c create,
1.496 + * @c write, @c finalize, @c list, @c read, @c size,
1.497 + * @c total_size, @c list_syslog, @c get_log_sets,
1.498 + * @c remove, @c is_deletable.
1.499 + * For details on these functions, see PurpleLogLogger.
1.500 + * Functions may not be skipped. For example, passing
1.501 + * @c create and @c write is acceptable (for a total of
1.502 + * two functions). Passing @c create and @c finalize,
1.503 + * however, is not. To accomplish that, the caller must
1.504 + * pass @c create, @c NULL (a placeholder for @c write),
1.505 + * and @c finalize (for a total of 3 functions).
1.506 + *
1.507 + * @return The new logger
1.508 + */
1.509 +PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...);
1.510 +
1.511 +/**
1.512 + * Frees a logger
1.513 + *
1.514 + * @param logger The logger to free
1.515 + */
1.516 +void purple_log_logger_free(PurpleLogLogger *logger);
1.517 +
1.518 +/**
1.519 + * Adds a new logger
1.520 + *
1.521 + * @param logger The new logger to add
1.522 + */
1.523 +void purple_log_logger_add (PurpleLogLogger *logger);
1.524 +
1.525 +/**
1.526 + *
1.527 + * Removes a logger
1.528 + *
1.529 + * @param logger The logger to remove
1.530 + */
1.531 +void purple_log_logger_remove (PurpleLogLogger *logger);
1.532 +
1.533 +/**
1.534 + *
1.535 + * Sets the current logger
1.536 + *
1.537 + * @param logger The logger to set
1.538 + */
1.539 +void purple_log_logger_set (PurpleLogLogger *logger);
1.540 +
1.541 +/**
1.542 + *
1.543 + * Returns the current logger
1.544 + *
1.545 + * @return logger The current logger
1.546 + */
1.547 +PurpleLogLogger *purple_log_logger_get (void);
1.548 +
1.549 +/**
1.550 + * Returns a GList containing the IDs and names of the registered
1.551 + * loggers.
1.552 + *
1.553 + * @return The list of IDs and names.
1.554 + */
1.555 +GList *purple_log_logger_get_options(void);
1.556 +
1.557 +/**************************************************************************/
1.558 +/** @name Log Subsystem */
1.559 +/**************************************************************************/
1.560 +/*@{*/
1.561 +
1.562 +/**
1.563 + * Initializes the log subsystem.
1.564 + */
1.565 +void purple_log_init(void);
1.566 +
1.567 +/**
1.568 + * Returns the log subsystem handle.
1.569 + *
1.570 + * @return The log subsystem handle.
1.571 + */
1.572 +void *purple_log_get_handle(void);
1.573 +
1.574 +/**
1.575 + * Uninitializes the log subsystem.
1.576 + */
1.577 +void purple_log_uninit(void);
1.578 +
1.579 +/*@}*/
1.580 +
1.581 +
1.582 +#ifdef __cplusplus
1.583 +}
1.584 +#endif
1.585 +
1.586 +#endif /* _PURPLE_LOG_H_ */