* 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 */
