* 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 * 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., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA * @section_id: libpurple-log * @short_description: <filename>log.h</filename> * @see_also: <link linkend="chapter-signals-log">Log signals</link> #define PURPLE_TYPE_LOG (purple_log_get_type()) /******************************************************** * DATA STRUCTURES ************************************** ********************************************************/ typedef struct _PurpleLog PurpleLog; typedef struct _PurpleLogLogger PurpleLogLogger; typedef struct _PurpleLogCommonLoggerData PurpleLogCommonLoggerData; typedef struct _PurpleLogSet PurpleLogSet; PURPLE_LOG_READ_NO_NEWLINE = 1 #include "conversations.h" typedef void (*PurpleLogSetCallback) (GHashTable *sets, PurpleLogSet *set); * @name: The logger's name * @id: An identifier to refer to this logger * @create: This gets called when the log is first created. I don't think * this is actually needed. * @write: This is used to write to the log file * @finalize: Called when the log is destroyed * @list: This function returns a sorted #GList of available PurpleLogs * @read: Given one of the logs returned by the logger's list function, * this returns the contents of the log * @size: Given one of the logs returned by the logger's list function, * this returns the size of the log in bytes * @total_size: Returns the total size of all the logs. If this is undefined a * default implementation is used * @list_syslog: This function returns a sorted #GList of available system * @get_log_sets: Adds #PurpleLogSet's to a #GHashTable. By passing the data in * the #PurpleLogSet's 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. * <sbr/>Loggers which implement this function must create a * #PurpleLogSet, then call @cb with @sets and the newly created * @remove: Attempts to delete the specified log, indicating success or * @is_deletable: Tests whether a log is deletable * This struct gets filled out and is included in the PurpleLog. It contains * everything needed to write and read from logs. struct _PurpleLogLogger { void (*create)(PurpleLog *log); gsize (*write)(PurpleLog *log, void (*finalize)(PurpleLog *log); GList *(*list)(PurpleLogType type, const char *name, PurpleAccount *account); char *(*read)(PurpleLog *log, PurpleLogReadFlags *flags); int (*size)(PurpleLog *log); int (*total_size)(PurpleLogType type, const char *name, PurpleAccount *account); GList *(*list_syslog)(PurpleAccount *account); void (*get_log_sets)(PurpleLogSetCallback cb, GHashTable *sets); gboolean (*remove)(PurpleLog *log); gboolean (*is_deletable)(PurpleLog *log); void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); * @type: The type of log this is * @name: The name of this log * @account: The account this log is taking place on * @conv: The conversation being logged * @time: The time this conversation started, converted to the local * @logger: The logging mechanism this log is to use * @logger_data: Data used by the log logger * A log. Not the wooden type. PurpleConversation *conv; /* IMPORTANT: Some code in log.c allocates these without zeroing them. * IMPORTANT: Update that code if you add members here. */ * PurpleLogCommonLoggerData: * A common logger_data struct containing a file handle and path, as well * as a pointer to something else for additional data. struct _PurpleLogCommonLoggerData { * @type: The type of logs available * @name: The name of the logs available * @account: The account the available logs took place on. This will be * %NULL if the account no longer exists. (Depending on a * logger's implementation of list, it may not be possible to * @buddy: Is this (account, name) a buddy on the buddy list? * @normalized_name: The normalized version of @name. It must be set, and may * be set to the same pointer value as @name. * Describes available logs. * By passing the elements of this struct to purple_log_get_logs(), the caller * can get all available PurpleLogs. /* IMPORTANT: Some code in log.c allocates these without zeroing them. * IMPORTANT: Update that code if you add members here. */ /***************************************/ /***************************************/ * Returns: The #GType for the #PurpleLog boxed structure. /* TODO Boxing of PurpleLog is a temporary solution to having a GType for * logs. This should rather be a GObject instead of a GBoxed. GType purple_log_get_type(void); * @type: The type of log this is. * @name: The name of this conversation (buddy name, chat name, * @account: The account the conversation is occurring on * @conv: The conversation being logged * @time: The time this conversation started PurpleLog *purple_log_new(PurpleLogType type, const char *name, PurpleAccount *account, PurpleConversation *conv, GDateTime *time); * @log: The log to destroy void purple_log_free(PurpleLog *log); * @log: The log to write to * @type: The type of message being logged * @from: Whom this message is coming from, or %NULL for * @time: A timestamp in UNIX time * @message: The message to log * Writes to a log file. Assumes you have checked preferences already. void purple_log_write(PurpleLog *log, * @log: The log to read from * @flags: The returned logging flags. * Returns: The contents of this log in Purple Markup. char *purple_log_read(PurpleLog *log, PurpleLogReadFlags *flags); * @type: The type of the log * @name: The name of the log * Returns a list of all available logs * Returns: (element-type PurpleLog) (transfer full): A sorted list of logs. GList *purple_log_get_logs(PurpleLogType type, const char *name, PurpleAccount *account); * purple_log_get_log_sets: * 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(). * Returns: (element-type PurpleLogSet PurpleLogSet) (transfer full): All * available unique log sets. GHashTable *purple_log_get_log_sets(void); * purple_log_get_system_logs: * Returns a list of all available system logs * Returns: (element-type PurpleLog) (transfer full): A sorted list of logs. GList *purple_log_get_system_logs(PurpleAccount *account); * Returns the size of a log * Returns: The size of the log, in bytes int purple_log_get_size(PurpleLog *log); * purple_log_get_total_size: * @type: The type of the log * @name: The name of the log * Returns the size, in bytes, of all available logs in this conversation * Returns: The size in bytes int purple_log_get_total_size(PurpleLogType type, const char *name, PurpleAccount *account); * purple_log_get_activity_score: * @type: The type of the log * @name: The name of the log * Returns the activity score of a log, based on total size in bytes, * which is then decayed based on age * Returns: The activity score int purple_log_get_activity_score(PurpleLogType type, const char *name, PurpleAccount *account); * purple_log_is_deletable: * Tests whether a log is deletable * A return value of %FALSE indicates that purple_log_delete() will fail on this * log, unless something changes between the two calls. A return value of %TRUE, * however, does not guarantee the log can be deleted. * Returns: A boolean indicating if the log is deletable gboolean purple_log_is_deletable(PurpleLog *log); * Returns: A boolean indicating success or failure gboolean purple_log_delete(PurpleLog *log); * purple_log_get_log_dir: * @type: The type of the log. * @name: The name of the 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. * Returns: The default logger directory for Purple. char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account); * Implements GCompareFunc for PurpleLogs * Returns: A value as specified by GCompareFunc gint purple_log_compare(gconstpointer y, gconstpointer z); * purple_log_set_compare: * @z: Another PurpleLogSet * Implements GCompareFunc for PurpleLogSets * Returns: A value as specified by GCompareFunc gint purple_log_set_compare(gconstpointer y, gconstpointer z); * @set: The log set to destroy void purple_log_set_free(PurpleLogSet *set); /******************************************/ /* Common Logger Functions */ /******************************************/ * purple_log_common_writer: * @log: The log to write to. * @ext: The file extension to give to this log file. * 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 <literal>write</literal> function. * It should only be passed to purple_log_logger_new() and never void purple_log_common_writer(PurpleLog *log, const char *ext); * purple_log_common_lister: * @type: The type of the logs being listed. * @name: The name of the log. * @account: The account of the log. * @ext: The file extension this log format uses. * @logger: A reference to the logger struct for this log. * Returns a sorted list of logs 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 <literal>list</literal> function. * It should only be passed to purple_log_logger_new() and never * Returns: (element-type PurpleLog) (transfer full): A sorted list of logs * matching the parameters. GList *purple_log_common_lister(PurpleLogType type, const char *name, PurpleAccount *account, const char *ext, PurpleLogLogger *logger); * purple_log_common_total_sizer: * @type: The type of the logs being sized. * @name: The name of the logs to size * (e.g. the username or chat name). * @account: The account of the log. * @ext: The file extension this log format uses. * Returns the total size of all the logs for a given user, with * 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 <literal>total_size</literal> * function. It should only be passed to purple_log_logger_new() and never * Returns: 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); * purple_log_common_sizer: * @log: The PurpleLog to size. * 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 <literal>size</literal> function. * It should only be passed to purple_log_logger_new() and never * Returns: An integer indicating the size of the log in bytes. int purple_log_common_sizer(PurpleLog *log); * purple_log_common_deleter: * @log: The PurpleLog to delete. * 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 <literal>delete</literal> function. * It should only be passed to purple_log_logger_new() and never * Returns: A boolean indicating success or failure. gboolean purple_log_common_deleter(PurpleLog *log); * purple_log_common_is_deletable: * @log: The PurpleLog to check. * 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 <literal>is_deletable</literal> * function. It should only be passed to purple_log_logger_new() and never * Returns: A boolean indicating if the log is deletable. gboolean purple_log_common_is_deletable(PurpleLog *log); /******************************************/ /******************************************/ * @name: The logger's name. * @functions: The number of functions being passed. The following * functions are currently available (in order): * <literal>create</literal>, <literal>write</literal>, * <literal>finalize</literal>, <literal>list</literal>, * <literal>read</literal>, <literal>size</literal>, * <literal>total_size</literal>, <literal>list_syslog</literal>, * <literal>get_log_sets</literal>, <literal>remove</literal>, * <literal>is_deletable</literal>. * For details on these functions, see PurpleLogLogger. * Functions may not be skipped. For example, passing * <literal>create</literal> and <literal>write</literal> is * acceptable (for a total of two functions). Passing * <literal>create</literal> and <literal>finalize</literal>, * however, is not. To accomplish that, the caller must pass * <literal>create</literal>, %NULL (a placeholder for * <literal>write</literal>), and <literal>finalize</literal> * (for a total of 3 functions). * Returns: (transfer full): The new logger. PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...); * purple_log_logger_free: * @logger: The logger to free void purple_log_logger_free(PurpleLogLogger *logger); * @logger: The new logger to add void purple_log_logger_add (PurpleLogLogger *logger); * purple_log_logger_remove: * @logger: The logger to remove void purple_log_logger_remove (PurpleLogLogger *logger); * @logger: The logger to set * Sets the current logger void purple_log_logger_set (PurpleLogLogger *logger); * Returns the current logger * Returns: (transfer none): The current logger. PurpleLogLogger *purple_log_logger_get(void); * purple_log_logger_get_options: * Returns a GList containing the IDs and names of the registered * Returns: (element-type utf8) (transfer container): The list of IDs and names. GList *purple_log_logger_get_options(void); /**************************************************************************/ /**************************************************************************/ * Initializes the log subsystem. void purple_log_init(void); * Returns the log subsystem handle. * Returns: The log subsystem handle. void *purple_log_get_handle(void); * Uninitializes the log subsystem. void purple_log_uninit(void); #endif /* PURPLE_LOG_H */