1.1 --- a/Frameworks/libpurple.framework/Versions/0.5.6/Headers/log.h Sun Jun 21 22:04:11 2009 -0400
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,570 +0,0 @@
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 (screenname, 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 - * Tests whether a log is deletable
1.301 - *
1.302 - * A return value of @c FALSE indicates that purple_log_delete() will fail on this
1.303 - * log, unless something changes between the two calls. A return value of @c TRUE,
1.304 - * however, does not guarantee the log can be deleted.
1.305 - *
1.306 - * @param log The log
1.307 - * @return A boolean indicating if the log is deletable
1.308 - */
1.309 -gboolean purple_log_is_deletable(PurpleLog *log);
1.310 -
1.311 -/**
1.312 - * Deletes a log
1.313 - *
1.314 - * @param log The log
1.315 - * @return A boolean indicating success or failure
1.316 - */
1.317 -gboolean purple_log_delete(PurpleLog *log);
1.318 -
1.319 -/**
1.320 - * Returns the default logger directory Purple uses for a given account
1.321 - * and username. This would be where Purple stores logs created by
1.322 - * the built-in text or HTML loggers.
1.323 - *
1.324 - * @param type The type of the log.
1.325 - * @param name The name of the log.
1.326 - * @param account The account.
1.327 - * @return The default logger directory for Purple.
1.328 - */
1.329 -char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account);
1.330 -
1.331 -/**
1.332 - * Implements GCompareFunc for PurpleLogs
1.333 - *
1.334 - * @param y A PurpleLog
1.335 - * @param z Another PurpleLog
1.336 - * @return A value as specified by GCompareFunc
1.337 - */
1.338 -gint purple_log_compare(gconstpointer y, gconstpointer z);
1.339 -
1.340 -/**
1.341 - * Implements GCompareFunc for PurpleLogSets
1.342 - *
1.343 - * @param y A PurpleLogSet
1.344 - * @param z Another PurpleLogSet
1.345 - * @return A value as specified by GCompareFunc
1.346 - */
1.347 -gint purple_log_set_compare(gconstpointer y, gconstpointer z);
1.348 -
1.349 -/**
1.350 - * Frees a log set
1.351 - *
1.352 - * @param set The log set to destroy
1.353 - */
1.354 -void purple_log_set_free(PurpleLogSet *set);
1.355 -
1.356 -/*@}*/
1.357 -
1.358 -/******************************************/
1.359 -/** @name Common Logger Functions */
1.360 -/******************************************/
1.361 -/*@{*/
1.362 -
1.363 -/**
1.364 - * Opens a new log file in the standard Purple log location
1.365 - * with the given file extension, named for the current time,
1.366 - * for writing. If a log file is already open, the existing
1.367 - * file handle is retained. The log's logger_data value is
1.368 - * set to a PurpleLogCommonLoggerData struct containing the log
1.369 - * file handle and log path.
1.370 - *
1.371 - * This function is intended to be used as a "common"
1.372 - * implementation of a logger's @c write function.
1.373 - * It should only be passed to purple_log_logger_new() and never
1.374 - * called directly.
1.375 - *
1.376 - * @param log The log to write to.
1.377 - * @param ext The file extension to give to this log file.
1.378 - */
1.379 -void purple_log_common_writer(PurpleLog *log, const char *ext);
1.380 -
1.381 -/**
1.382 - * Returns a sorted GList of PurpleLogs of the requested type.
1.383 - *
1.384 - * This function should only be used with logs that are written
1.385 - * with purple_log_common_writer(). It's intended to be used as
1.386 - * a "common" implementation of a logger's @c list function.
1.387 - * It should only be passed to purple_log_logger_new() and never
1.388 - * called directly.
1.389 - *
1.390 - * @param type The type of the logs being listed.
1.391 - * @param name The name of the log.
1.392 - * @param account The account of the log.
1.393 - * @param ext The file extension this log format uses.
1.394 - * @param logger A reference to the logger struct for this log.
1.395 - *
1.396 - * @return A sorted GList of PurpleLogs matching the parameters.
1.397 - */
1.398 -GList *purple_log_common_lister(PurpleLogType type, const char *name,
1.399 - PurpleAccount *account, const char *ext,
1.400 - PurpleLogLogger *logger);
1.401 -
1.402 -/**
1.403 - * Returns the total size of all the logs for a given user, with
1.404 - * a given extension.
1.405 - *
1.406 - * This function should only be used with logs that are written
1.407 - * with purple_log_common_writer(). It's intended to be used as
1.408 - * a "common" implementation of a logger's @c total_size function.
1.409 - * It should only be passed to purple_log_logger_new() and never
1.410 - * called directly.
1.411 - *
1.412 - * @param type The type of the logs being sized.
1.413 - * @param name The name of the logs to size
1.414 - * (e.g. the username or chat name).
1.415 - * @param account The account of the log.
1.416 - * @param ext The file extension this log format uses.
1.417 - *
1.418 - * @return The size of all the logs with the specified extension
1.419 - * for the specified user.
1.420 - */
1.421 -int purple_log_common_total_sizer(PurpleLogType type, const char *name,
1.422 - PurpleAccount *account, const char *ext);
1.423 -
1.424 -/**
1.425 - * Returns the size of a given PurpleLog.
1.426 - *
1.427 - * This function should only be used with logs that are written
1.428 - * with purple_log_common_writer(). It's intended to be used as
1.429 - * a "common" implementation of a logger's @c size function.
1.430 - * It should only be passed to purple_log_logger_new() and never
1.431 - * called directly.
1.432 - *
1.433 - * @param log The PurpleLog to size.
1.434 - *
1.435 - * @return An integer indicating the size of the log in bytes.
1.436 - */
1.437 -int purple_log_common_sizer(PurpleLog *log);
1.438 -
1.439 -/**
1.440 - * Deletes a log
1.441 - *
1.442 - * This function should only be used with logs that are written
1.443 - * with purple_log_common_writer(). It's intended to be used as
1.444 - * a "common" implementation of a logger's @c delete function.
1.445 - * It should only be passed to purple_log_logger_new() and never
1.446 - * called directly.
1.447 - *
1.448 - * @param log The PurpleLog to delete.
1.449 - *
1.450 - * @return A boolean indicating success or failure.
1.451 - */
1.452 -gboolean purple_log_common_deleter(PurpleLog *log);
1.453 -
1.454 -/**
1.455 - * Checks to see if a log is deletable
1.456 - *
1.457 - * This function should only be used with logs that are written
1.458 - * with purple_log_common_writer(). It's intended to be used as
1.459 - * a "common" implementation of a logger's @c is_deletable function.
1.460 - * It should only be passed to purple_log_logger_new() and never
1.461 - * called directly.
1.462 - *
1.463 - * @param log The PurpleLog to check.
1.464 - *
1.465 - * @return A boolean indicating if the log is deletable.
1.466 - */
1.467 -gboolean purple_log_common_is_deletable(PurpleLog *log);
1.468 -
1.469 -/*@}*/
1.470 -
1.471 -/******************************************/
1.472 -/** @name Logger Functions */
1.473 -/******************************************/
1.474 -/*@{*/
1.475 -
1.476 -/**
1.477 - * Creates a new logger
1.478 - *
1.479 - * @param id The logger's id.
1.480 - * @param name The logger's name.
1.481 - * @param functions The number of functions being passed. The following
1.482 - * functions are currently available (in order): @c create,
1.483 - * @c write, @c finalize, @c list, @c read, @c size,
1.484 - * @c total_size, @c list_syslog, @c get_log_sets,
1.485 - * @c remove, @c is_deletable.
1.486 - * For details on these functions, see PurpleLogLogger.
1.487 - * Functions may not be skipped. For example, passing
1.488 - * @c create and @c write is acceptable (for a total of
1.489 - * two functions). Passing @c create and @c finalize,
1.490 - * however, is not. To accomplish that, the caller must
1.491 - * pass @c create, @c NULL (a placeholder for @c write),
1.492 - * and @c finalize (for a total of 3 functions).
1.493 - *
1.494 - * @return The new logger
1.495 - */
1.496 -PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...);
1.497 -
1.498 -/**
1.499 - * Frees a logger
1.500 - *
1.501 - * @param logger The logger to free
1.502 - */
1.503 -void purple_log_logger_free(PurpleLogLogger *logger);
1.504 -
1.505 -/**
1.506 - * Adds a new logger
1.507 - *
1.508 - * @param logger The new logger to add
1.509 - */
1.510 -void purple_log_logger_add (PurpleLogLogger *logger);
1.511 -
1.512 -/**
1.513 - *
1.514 - * Removes a logger
1.515 - *
1.516 - * @param logger The logger to remove
1.517 - */
1.518 -void purple_log_logger_remove (PurpleLogLogger *logger);
1.519 -
1.520 -/**
1.521 - *
1.522 - * Sets the current logger
1.523 - *
1.524 - * @param logger The logger to set
1.525 - */
1.526 -void purple_log_logger_set (PurpleLogLogger *logger);
1.527 -
1.528 -/**
1.529 - *
1.530 - * Returns the current logger
1.531 - *
1.532 - * @return logger The current logger
1.533 - */
1.534 -PurpleLogLogger *purple_log_logger_get (void);
1.535 -
1.536 -/**
1.537 - * Returns a GList containing the IDs and names of the registered
1.538 - * loggers.
1.539 - *
1.540 - * @return The list of IDs and names.
1.541 - */
1.542 -GList *purple_log_logger_get_options(void);
1.543 -
1.544 -/**************************************************************************/
1.545 -/** @name Log Subsystem */
1.546 -/**************************************************************************/
1.547 -/*@{*/
1.548 -
1.549 -/**
1.550 - * Initializes the log subsystem.
1.551 - */
1.552 -void purple_log_init(void);
1.553 -
1.554 -/**
1.555 - * Returns the log subsystem handle.
1.556 - *
1.557 - * @return The log subsystem handle.
1.558 - */
1.559 -void *purple_log_get_handle(void);
1.560 -
1.561 -/**
1.562 - * Uninitializes the log subsystem.
1.563 - */
1.564 -void purple_log_uninit(void);
1.565 -
1.566 -/*@}*/
1.567 -
1.568 -
1.569 -#ifdef __cplusplus
1.570 -}
1.571 -#endif
1.572 -
1.573 -#endif /* _PURPLE_LOG_H_ */