--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/libpurple/log.h Sun Apr 15 03:56:08 2007 +0000
@@ -0,0 +1,563 @@
+/**
+ * @file log.h Logging API
+ * @ingroup core
+ *
+ * purple
+ *
+ * Purple is the legal property of its developers, whose names are too numerous
+ * to list here. Please refer to the COPYRIGHT file distributed with this
+ * source distribution.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+#ifndef _PURPLE_LOG_H_
+#define _PURPLE_LOG_H_
+
+#include <stdio.h>
+
+
+/********************************************************
+ * DATA STRUCTURES **************************************
+ ********************************************************/
+
+typedef struct _PurpleLog PurpleLog;
+typedef struct _PurpleLogLogger PurpleLogLogger;
+typedef struct _PurpleLogCommonLoggerData PurpleLogCommonLoggerData;
+typedef struct _PurpleLogSet PurpleLogSet;
+
+typedef enum {
+ PURPLE_LOG_IM,
+ PURPLE_LOG_CHAT,
+ PURPLE_LOG_SYSTEM
+} PurpleLogType;
+
+typedef enum {
+ PURPLE_LOG_READ_NO_NEWLINE = 1
+} PurpleLogReadFlags;
+
+#include "account.h"
+#include "conversation.h"
+
+typedef void (*PurpleLogSetCallback) (GHashTable *sets, PurpleLogSet *set);
+
+/**
+ * A log logger.
+ *
+ * This struct gets filled out and is included in the PurpleLog. It contains everything
+ * needed to write and read from logs.
+ */
+struct _PurpleLogLogger {
+ char *name; /**< The logger's name */
+ char *id; /**< an identifier to refer to this logger */
+
+ /** This gets called when the log is first created.
+ I don't think this is actually needed. */
+ void (*create)(PurpleLog *log);
+
+ /** This is used to write to the log file */
+ gsize (*write)(PurpleLog *log,
+ PurpleMessageFlags type,
+ const char *from,
+ time_t time,
+ const char *message);
+
+ /** Called when the log is destroyed */
+ void (*finalize)(PurpleLog *log);
+
+ /** This function returns a sorted GList of available PurpleLogs */
+ GList *(*list)(PurpleLogType type, const char *name, PurpleAccount *account);
+
+ /** Given one of the logs returned by the logger's list function,
+ * this returns the contents of the log in GtkIMHtml markup */
+ char *(*read)(PurpleLog *log, PurpleLogReadFlags *flags);
+
+ /** Given one of the logs returned by the logger's list function,
+ * this returns the size of the log in bytes */
+ int (*size)(PurpleLog *log);
+
+ /** Returns the total size of all the logs. If this is undefined a default
+ * implementation is used */
+ int (*total_size)(PurpleLogType type, const char *name, PurpleAccount *account);
+
+ /** This function returns a sorted GList of available system PurpleLogs */
+ GList *(*list_syslog)(PurpleAccount *account);
+
+ /** Adds PurpleLogSets to a GHashTable. By passing the data in the PurpleLogSets
+ * to list, the caller can get every available PurpleLog from the logger.
+ * Loggers using purple_log_common_writer() (or otherwise storing their
+ * logs in the same directory structure as the stock loggers) do not
+ * need to implement this function.
+ *
+ * Loggers which implement this function must create a PurpleLogSet,
+ * then call @a cb with @a sets and the newly created PurpleLogSet. */
+ void (*get_log_sets)(PurpleLogSetCallback cb, GHashTable *sets);
+
+ /* Attempts to delete the specified log, indicating success or failure */
+ gboolean (*remove)(PurpleLog *log);
+
+ /* Tests whether a log is deletable */
+ gboolean (*is_deletable)(PurpleLog *log);
+};
+
+/**
+ * A log. Not the wooden type.
+ */
+struct _PurpleLog {
+ PurpleLogType type; /**< The type of log this is */
+ char *name; /**< The name of this log */
+ PurpleAccount *account; /**< The account this log is taking
+ place on */
+ PurpleConversation *conv; /**< The conversation being logged */
+ time_t time; /**< The time this conversation
+ started, converted to the local timezone */
+
+ PurpleLogLogger *logger; /**< The logging mechanism this log
+ is to use */
+ void *logger_data; /**< Data used by the log logger */
+ struct tm *tm; /**< The time this conversation
+ started, saved with original
+ timezone data, if available and
+ if struct tm has the BSD
+ timezone fields, else @c NULL.
+ Do NOT modify anything in this struct.*/
+
+ /* IMPORTANT: Some code in log.c allocates these without zeroing them.
+ * IMPORTANT: Update that code if you add members here. */
+};
+
+/**
+ * A common logger_data struct containing a file handle and path, as well
+ * as a pointer to something else for additional data.
+ */
+struct _PurpleLogCommonLoggerData {
+ char *path;
+ FILE *file;
+ void *extra_data;
+};
+
+/**
+ * Describes available logs.
+ *
+ * By passing the elements of this struct to purple_log_get_logs(), the caller
+ * can get all available PurpleLogs.
+ */
+struct _PurpleLogSet {
+ PurpleLogType type; /**< The type of logs available */
+ char *name; /**< The name of the logs available */
+ PurpleAccount *account; /**< The account the available logs
+ took place on. This will be
+ @c NULL if the account no longer
+ exists. (Depending on a
+ logger's implementation of
+ list, it may not be possible
+ to load such logs.) */
+ gboolean buddy; /**< Is this (account, name) a buddy
+ on the buddy list? */
+ char *normalized_name; /**< The normalized version of
+ @a name. It must be set, and
+ may be set to the same pointer
+ value as @a name. */
+
+ /* IMPORTANT: Some code in log.c allocates these without zeroing them.
+ * IMPORTANT: Update that code if you add members here. */
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/***************************************/
+/** @name Log Functions */
+/***************************************/
+/*@{*/
+
+/**
+ * Creates a new log
+ *
+ * @param type The type of log this is.
+ * @param name The name of this conversation (screenname, chat name,
+ * etc.)
+ * @param account The account the conversation is occurring on
+ * @param conv The conversation being logged
+ * @param time The time this conversation started
+ * @param tm The time this conversation started, with timezone data,
+ * if available and if struct tm has the BSD timezone fields.
+ * @return The new log
+ */
+PurpleLog *purple_log_new(PurpleLogType type, const char *name, PurpleAccount *account,
+ PurpleConversation *conv, time_t time, const struct tm *tm);
+
+/**
+ * Frees a log
+ *
+ * @param log The log to destroy
+ */
+void purple_log_free(PurpleLog *log);
+
+/**
+ * Writes to a log file. Assumes you have checked preferences already.
+ *
+ * @param log The log to write to
+ * @param type The type of message being logged
+ * @param from Whom this message is coming from, or @c NULL for
+ * system messages
+ * @param time A timestamp in UNIX time
+ * @param message The message to log
+ */
+void purple_log_write(PurpleLog *log,
+ PurpleMessageFlags type,
+ const char *from,
+ time_t time,
+ const char *message);
+
+/**
+ * Reads from a log
+ *
+ * @param log The log to read from
+ * @param flags The returned logging flags.
+ *
+ * @return The contents of this log in Purple Markup.
+ */
+char *purple_log_read(PurpleLog *log, PurpleLogReadFlags *flags);
+
+/**
+ * Returns a list of all available logs
+ *
+ * @param type The type of the log
+ * @param name The name of the log
+ * @param account The account
+ * @return A sorted list of PurpleLogs
+ */
+GList *purple_log_get_logs(PurpleLogType type, const char *name, PurpleAccount *account);
+
+/**
+ * Returns a GHashTable of PurpleLogSets.
+ *
+ * A "log set" here means the information necessary to gather the
+ * PurpleLogs for a given buddy/chat. This information would be passed
+ * to purple_log_list to get a list of PurpleLogs.
+ *
+ * The primary use of this function is to get a list of everyone the
+ * user has ever talked to (assuming he or she uses logging).
+ *
+ * The GHashTable that's returned will free all log sets in it when
+ * destroyed. If a PurpleLogSet is removed from the GHashTable, it
+ * must be freed with purple_log_set_free().
+ *
+ * @return A GHashTable of all available unique PurpleLogSets
+ */
+GHashTable *purple_log_get_log_sets(void);
+
+/**
+ * Returns a list of all available system logs
+ *
+ * @param account The account
+ * @return A sorted list of PurpleLogs
+ */
+GList *purple_log_get_system_logs(PurpleAccount *account);
+
+/**
+ * Returns the size of a log
+ *
+ * @param log The log
+ * @return The size of the log, in bytes
+ */
+int purple_log_get_size(PurpleLog *log);
+
+/**
+ * Returns the size, in bytes, of all available logs in this conversation
+ *
+ * @param type The type of the log
+ * @param name The name of the log
+ * @param account The account
+ * @return The size in bytes
+ */
+int purple_log_get_total_size(PurpleLogType type, const char *name, PurpleAccount *account);
+
+/**
+ * Tests whether a log is deletable
+ *
+ * A return value of @c FALSE indicates that purple_log_delete() will fail on this
+ * log, unless something changes between the two calls. A return value of @c TRUE,
+ * however, does not guarantee the log can be deleted.
+ *
+ * @param log The log
+ * @return A boolean indicating if the log is deletable
+ */
+gboolean purple_log_is_deletable(PurpleLog *log);
+
+/**
+ * Deletes a log
+ *
+ * @param log The log
+ * @return A boolean indicating success or failure
+ */
+gboolean purple_log_delete(PurpleLog *log);
+
+/**
+ * Returns the default logger directory Purple uses for a given account
+ * and username. This would be where Purple stores logs created by
+ * the built-in text or HTML loggers.
+ *
+ * @param type The type of the log.
+ * @param name The name of the log.
+ * @param account The account.
+ * @return The default logger directory for Purple.
+ */
+char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account);
+
+/**
+ * Implements GCompareFunc for PurpleLogs
+ *
+ * @param y A PurpleLog
+ * @param z Another PurpleLog
+ * @return A value as specified by GCompareFunc
+ */
+gint purple_log_compare(gconstpointer y, gconstpointer z);
+
+/**
+ * Implements GCompareFunc for PurpleLogSets
+ *
+ * @param y A PurpleLogSet
+ * @param z Another PurpleLogSet
+ * @return A value as specified by GCompareFunc
+ */
+gint purple_log_set_compare(gconstpointer y, gconstpointer z);
+
+/**
+ * Frees a log set
+ *
+ * @param set The log set to destroy
+ */
+void purple_log_set_free(PurpleLogSet *set);
+
+/*@}*/
+
+/******************************************/
+/** @name Common Logger Functions */
+/******************************************/
+/*@{*/
+
+/**
+ * Opens a new log file in the standard Purple log location
+ * with the given file extension, named for the current time,
+ * for writing. If a log file is already open, the existing
+ * file handle is retained. The log's logger_data value is
+ * set to a PurpleLogCommonLoggerData struct containing the log
+ * file handle and log path.
+ *
+ * This function is intended to be used as a "common"
+ * implementation of a logger's @c write function.
+ * It should only be passed to purple_log_logger_new() and never
+ * called directly.
+ *
+ * @param log The log to write to.
+ * @param ext The file extension to give to this log file.
+ */
+void purple_log_common_writer(PurpleLog *log, const char *ext);
+
+/**
+ * Returns a sorted GList of PurpleLogs of the requested type.
+ *
+ * This function should only be used with logs that are written
+ * with purple_log_common_writer(). It's intended to be used as
+ * a "common" implementation of a logger's @c list function.
+ * It should only be passed to purple_log_logger_new() and never
+ * called directly.
+ *
+ * @param type The type of the logs being listed.
+ * @param name The name of the log.
+ * @param account The account of the log.
+ * @param ext The file extension this log format uses.
+ * @param logger A reference to the logger struct for this log.
+ *
+ * @return A sorted GList of PurpleLogs matching the parameters.
+ */
+GList *purple_log_common_lister(PurpleLogType type, const char *name,
+ PurpleAccount *account, const char *ext,
+ PurpleLogLogger *logger);
+
+/**
+ * Returns the total size of all the logs for a given user, with
+ * a given extension.
+ *
+ * This function should only be used with logs that are written
+ * with purple_log_common_writer(). It's intended to be used as
+ * a "common" implementation of a logger's @c total_size function.
+ * It should only be passed to purple_log_logger_new() and never
+ * called directly.
+ *
+ * @param type The type of the logs being sized.
+ * @param name The name of the logs to size
+ * (e.g. the username or chat name).
+ * @param account The account of the log.
+ * @param ext The file extension this log format uses.
+ *
+ * @return The size of all the logs with the specified extension
+ * for the specified user.
+ */
+int purple_log_common_total_sizer(PurpleLogType type, const char *name,
+ PurpleAccount *account, const char *ext);
+
+/**
+ * Returns the size of a given PurpleLog.
+ *
+ * This function should only be used with logs that are written
+ * with purple_log_common_writer(). It's intended to be used as
+ * a "common" implementation of a logger's @c size function.
+ * It should only be passed to purple_log_logger_new() and never
+ * called directly.
+ *
+ * @param log The PurpleLog to size.
+ *
+ * @return An integer indicating the size of the log in bytes.
+ */
+int purple_log_common_sizer(PurpleLog *log);
+
+/**
+ * Deletes a log
+ *
+ * This function should only be used with logs that are written
+ * with purple_log_common_writer(). It's intended to be used as
+ * a "common" implementation of a logger's @c delete function.
+ * It should only be passed to purple_log_logger_new() and never
+ * called directly.
+ *
+ * @param log The PurpleLog to delete.
+ *
+ * @return A boolean indicating success or failure.
+ */
+gboolean purple_log_common_deleter(PurpleLog *log);
+
+/**
+ * Checks to see if a log is deletable
+ *
+ * This function should only be used with logs that are written
+ * with purple_log_common_writer(). It's intended to be used as
+ * a "common" implementation of a logger's @c is_deletable function.
+ * It should only be passed to purple_log_logger_new() and never
+ * called directly.
+ *
+ * @param log The PurpleLog to check.
+ *
+ * @return A boolean indicating if the log is deletable.
+ */
+gboolean purple_log_common_is_deletable(PurpleLog *log);
+
+/*@}*/
+
+/******************************************/
+/** @name Logger Functions */
+/******************************************/
+/*@{*/
+
+/**
+ * Creates a new logger
+ *
+ * @param id The logger's id.
+ * @param name The logger's name.
+ * @param functions The number of functions being passed. The following
+ * functions are currently available (in order): @c create,
+ * @c write, @c finalize, @c list, @c read, @c size,
+ * @c total_size, @c list_syslog, @c get_log_sets,
+ * @c remove, @c is_deletable.
+ * For details on these functions, see PurpleLogLogger.
+ * Functions may not be skipped. For example, passing
+ * @c create and @c write is acceptable (for a total of
+ * two functions). Passing @c create and @c finalize,
+ * however, is not. To accomplish that, the caller must
+ * pass @c create, @c NULL (a placeholder for @c write),
+ * and @c finalize (for a total of 3 functions).
+ *
+ * @return The new logger
+ */
+PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...);
+
+/**
+ * Frees a logger
+ *
+ * @param logger The logger to free
+ */
+void purple_log_logger_free(PurpleLogLogger *logger);
+
+/**
+ * Adds a new logger
+ *
+ * @param logger The new logger to add
+ */
+void purple_log_logger_add (PurpleLogLogger *logger);
+
+/**
+ *
+ * Removes a logger
+ *
+ * @param logger The logger to remove
+ */
+void purple_log_logger_remove (PurpleLogLogger *logger);
+
+/**
+ *
+ * Sets the current logger
+ *
+ * @param logger The logger to set
+ */
+void purple_log_logger_set (PurpleLogLogger *logger);
+
+/**
+ *
+ * Returns the current logger
+ *
+ * @return logger The current logger
+ */
+PurpleLogLogger *purple_log_logger_get (void);
+
+/**
+ * Returns a GList containing the IDs and names of the registered
+ * loggers.
+ *
+ * @return The list of IDs and names.
+ */
+GList *purple_log_logger_get_options(void);
+
+/**************************************************************************/
+/** @name Log Subsystem */
+/**************************************************************************/
+/*@{*/
+
+/**
+ * Initializes the log subsystem.
+ */
+void purple_log_init(void);
+
+/**
+ * Returns the log subsystem handle.
+ *
+ * @return The log subsystem handle.
+ */
+void *purple_log_get_handle(void);
+
+/**
+ * Uninitializes the log subsystem.
+ */
+void purple_log_uninit(void);
+
+/*@}*/
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _PURPLE_LOG_H_ */