Logging API. More...

#include <stdio.h>
#include "account.h"
#include "conversation.h"

Include dependency graph for log.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	_PurpleLogLogger
	A log logger. More...

struct	_PurpleLog
	A log. More...

struct	_PurpleLogCommonLoggerData
	A common logger_data struct containing a file handle and path, as well as a pointer to something else for additional data. More...

struct	_PurpleLogSet
	Describes available logs. More...

Typedefs
typedef struct _PurpleLog	PurpleLog

typedef struct _PurpleLogLogger	PurpleLogLogger

typedef struct _PurpleLogCommonLoggerData	PurpleLogCommonLoggerData

typedef struct _PurpleLogSet	PurpleLogSet

typedef void(*	PurpleLogSetCallback) (GHashTable sets, PurpleLogSet set)

Enumerations
enum	PurpleLogType { PURPLE_LOG_IM , PURPLE_LOG_CHAT , PURPLE_LOG_SYSTEM }

enum	PurpleLogReadFlags { PURPLE_LOG_READ_NO_NEWLINE = 1 }

Functions
Log Functions <br>
PurpleLog *	purple_log_new (PurpleLogType type, const char name, PurpleAccount account, PurpleConversation conv, time_t time, const struct tm tm)
	Creates a new log.

void	purple_log_free (PurpleLog *log)
	Frees a log.

void	purple_log_write (PurpleLog log, PurpleMessageFlags type, const char from, time_t time, const char *message)
	Writes to a log file.

char *	purple_log_read (PurpleLog log, PurpleLogReadFlags flags)
	Reads from a log.

GList *	purple_log_get_logs (PurpleLogType type, const char name, PurpleAccount account)
	Returns a list of all available logs.

GHashTable *	purple_log_get_log_sets (void)
	Returns a GHashTable of PurpleLogSets.

GList *	purple_log_get_system_logs (PurpleAccount *account)
	Returns a list of all available system logs.

int	purple_log_get_size (PurpleLog *log)
	Returns the size of a log.

int	purple_log_get_total_size (PurpleLogType type, const char name, PurpleAccount account)
	Returns the size, in bytes, of all available logs in this conversation.

int	purple_log_get_activity_score (PurpleLogType type, const char name, PurpleAccount account)
	Returns the activity score of a log, based on total size in bytes, which is then decayed based on age.

gboolean	purple_log_is_deletable (PurpleLog *log)
	Tests whether a log is deletable.

gboolean	purple_log_delete (PurpleLog *log)
	Deletes a log.

char *	purple_log_get_log_dir (PurpleLogType type, const char name, PurpleAccount account)
	Returns the default logger directory Purple uses for a given account and username.

gint	purple_log_compare (gconstpointer y, gconstpointer z)
	Implements GCompareFunc for PurpleLogs.

gint	purple_log_set_compare (gconstpointer y, gconstpointer z)
	Implements GCompareFunc for PurpleLogSets.

void	purple_log_set_free (PurpleLogSet *set)
	Frees a log set.

Common Logger Functions <br>
void	purple_log_common_writer (PurpleLog log, const char ext)
	Opens a new log file in the standard Purple log location with the given file extension, named for the current time, for writing.

GList *	purple_log_common_lister (PurpleLogType type, const char name, PurpleAccount account, const char ext, PurpleLogLogger logger)
	Returns a sorted GList of PurpleLogs of the requested type.

int	purple_log_common_total_sizer (PurpleLogType type, const char name, PurpleAccount account, const char *ext)
	Returns the total size of all the logs for a given user, with a given extension.

int	purple_log_common_sizer (PurpleLog *log)
	Returns the size of a given PurpleLog.

gboolean	purple_log_common_deleter (PurpleLog *log)
	Deletes a log.

gboolean	purple_log_common_is_deletable (PurpleLog *log)
	Checks to see if a log is deletable.

Logger Functions <br>
PurpleLogLogger *	purple_log_logger_new (const char id, const char name, int functions,...)
	Creates a new logger.

void	purple_log_logger_free (PurpleLogLogger *logger)
	Frees a logger.

void	purple_log_logger_add (PurpleLogLogger *logger)
	Adds a new logger.

void	purple_log_logger_remove (PurpleLogLogger *logger)
	Removes a logger.

void	purple_log_logger_set (PurpleLogLogger *logger)
	Sets the current logger.

PurpleLogLogger *	purple_log_logger_get (void)
	Returns the current logger.

GList *	purple_log_logger_get_options (void)
	Returns a GList containing the IDs and names of the registered loggers.

Log Subsystem <br>
void	purple_log_init (void)
	Initializes the log subsystem.

void *	purple_log_get_handle (void)
	Returns the log subsystem handle.

void	purple_log_uninit (void)
	Uninitializes the log subsystem.

Detailed Description

Logging API.

See also: Log Signals

Definition in file log.h.

Typedef Documentation

◆ PurpleLog

typedef struct _PurpleLog PurpleLog

Definition at line 37 of file log.h.

◆ PurpleLogCommonLoggerData

typedef struct _PurpleLogCommonLoggerData PurpleLogCommonLoggerData

Definition at line 39 of file log.h.

◆ PurpleLogLogger

typedef struct _PurpleLogLogger PurpleLogLogger

Definition at line 38 of file log.h.

◆ PurpleLogSet

typedef struct _PurpleLogSet PurpleLogSet

Definition at line 40 of file log.h.

◆ PurpleLogSetCallback

typedef void(* PurpleLogSetCallback) (GHashTable *sets, PurpleLogSet *set)

Definition at line 55 of file log.h.

Enumeration Type Documentation

◆ PurpleLogReadFlags

enum PurpleLogReadFlags

Definition at line 48 of file log.h.

◆ PurpleLogType

enum PurpleLogType

Definition at line 42 of file log.h.

Function Documentation

◆ purple_log_common_deleter()

gboolean purple_log_common_deleter ( 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 delete function. It should only be passed to purple_log_logger_new() and never called directly.

Parameters

log	The PurpleLog to delete.

Returns: A boolean indicating success or failure.

◆ purple_log_common_is_deletable()

gboolean purple_log_common_is_deletable ( 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 is_deletable function. It should only be passed to purple_log_logger_new() and never called directly.

Parameters

log	The PurpleLog to check.

Returns: A boolean indicating if the log is deletable.

◆ purple_log_common_lister()

GList * purple_log_common_lister	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account,
		const char *	ext,
		PurpleLogLogger *	logger
	)

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 list function. It should only be passed to purple_log_logger_new() and never called directly.

Parameters

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 GList of PurpleLogs matching the parameters.

◆ purple_log_common_sizer()

int purple_log_common_sizer ( PurpleLog * log )

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 size function. It should only be passed to purple_log_logger_new() and never called directly.

Parameters

log	The PurpleLog to size.

Returns: An integer indicating the size of the log in bytes.

◆ purple_log_common_total_sizer()

int purple_log_common_total_sizer	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account,
		const char *	ext
	)

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 total_size function. It should only be passed to purple_log_logger_new() and never called directly.

Parameters

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 size of all the logs with the specified extension for the specified user.

◆ purple_log_common_writer()

void purple_log_common_writer	(	PurpleLog *	log,
		const char *	ext
	)

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 write function. It should only be passed to purple_log_logger_new() and never called directly.

Parameters

log	The log to write to.
ext	The file extension to give to this log file.

◆ purple_log_compare()

gint purple_log_compare	(	gconstpointer	y,
		gconstpointer	z
	)

Implements GCompareFunc for PurpleLogs.

Parameters

y	A PurpleLog
z	Another PurpleLog

Returns: A value as specified by GCompareFunc

◆ purple_log_delete()

gboolean purple_log_delete ( PurpleLog * log )

Deletes a log.

Parameters

log The log

Returns: A boolean indicating success or failure

◆ purple_log_free()

void purple_log_free ( PurpleLog * log )

Frees a log.

Parameters

log	The log to destroy

◆ purple_log_get_activity_score()

int purple_log_get_activity_score	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account
	)

Returns the activity score of a log, based on total size in bytes, which is then decayed based on age.

Parameters

type	The type of the log
name	The name of the log
account	The account

Returns: The activity score

Since: 2.6.0

◆ purple_log_get_handle()

void * purple_log_get_handle ( void )

Returns the log subsystem handle.

Returns: The log subsystem handle.

◆ purple_log_get_log_dir()

char * purple_log_get_log_dir	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account
	)

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.

Parameters

type	The type of the log.
name	The name of the log.
account	The account.

Returns: The default logger directory for Purple.

◆ purple_log_get_log_sets()

GHashTable * purple_log_get_log_sets ( void )

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: A GHashTable of all available unique PurpleLogSets

◆ purple_log_get_logs()

GList * purple_log_get_logs	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account
	)

Returns a list of all available logs.

Parameters

type	The type of the log
name	The name of the log
account	The account

Returns: A sorted list of PurpleLogs

◆ purple_log_get_size()

int purple_log_get_size ( PurpleLog * log )

Returns the size of a log.

Parameters

log The log

Returns: The size of the log, in bytes

◆ purple_log_get_system_logs()

GList * purple_log_get_system_logs ( PurpleAccount * account )

Returns a list of all available system logs.

Parameters

account The account

Returns: A sorted list of PurpleLogs

◆ purple_log_get_total_size()

int purple_log_get_total_size	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account
	)

Returns the size, in bytes, of all available logs in this conversation.

Parameters

type	The type of the log
name	The name of the log
account	The account

Returns: The size in bytes

◆ purple_log_is_deletable()

gboolean purple_log_is_deletable ( PurpleLog * log )

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.

Parameters

log The log

Returns: A boolean indicating if the log is deletable

◆ purple_log_logger_add()

void purple_log_logger_add ( PurpleLogLogger * logger )

Adds a new logger.

Parameters

logger The new logger to add

◆ purple_log_logger_free()

void purple_log_logger_free ( PurpleLogLogger * logger )

Frees a logger.

Parameters

logger The logger to free

◆ purple_log_logger_get()

PurpleLogLogger * purple_log_logger_get ( void )

Returns the current logger.

Returns: logger The current logger

◆ purple_log_logger_get_options()

GList * purple_log_logger_get_options ( void )

Returns a GList containing the IDs and names of the registered loggers.

Returns: The list of IDs and names.

◆ purple_log_logger_new()

PurpleLogLogger * purple_log_logger_new	(	const char *	id,
		const char *	name,
		int	functions,
			...
	)

Creates a new logger.

Parameters

id	The logger's id.
name	The logger's name.
functions	The number of functions being passed. The following functions are currently available (in order): `create`, `write`, `finalize`, `list`, `read`, `size`, `total_size`, `list_syslog`, `get_log_sets`, `remove`, `is_deletable`. For details on these functions, see PurpleLogLogger. Functions may not be skipped. For example, passing `create` and `write` is acceptable (for a total of two functions). Passing `create` and `finalize`, however, is not. To accomplish that, the caller must pass `create`, `NULL` (a placeholder for `write`), and `finalize` (for a total of 3 functions).

Returns: The new logger

◆ purple_log_logger_remove()

void purple_log_logger_remove ( PurpleLogLogger * logger )

Removes a logger.

Parameters

logger The logger to remove

◆ purple_log_logger_set()

void purple_log_logger_set ( PurpleLogLogger * logger )

Sets the current logger.

Parameters

logger The logger to set

◆ purple_log_new()

PurpleLog * purple_log_new	(	PurpleLogType	type,
		const char *	name,
		PurpleAccount *	account,
		PurpleConversation *	conv,
		time_t	time,
		const struct tm *	tm
	)

Creates a new log.

Parameters

type	The type of log this is.
name	The name of this conversation (buddy name, chat name, etc.)
account	The account the conversation is occurring on
conv	The conversation being logged
time	The time this conversation started
tm	The time this conversation started, with timezone data, if available and if struct tm has the BSD timezone fields.

Returns: The new log

◆ purple_log_read()

char * purple_log_read	(	PurpleLog *	log,
		PurpleLogReadFlags *	flags
	)

Reads from a log.

Parameters

log	The log to read from
flags	The returned logging flags.

Returns: The contents of this log in Purple Markup.

◆ purple_log_set_compare()

gint purple_log_set_compare	(	gconstpointer	y,
		gconstpointer	z
	)

Implements GCompareFunc for PurpleLogSets.

Parameters

y	A PurpleLogSet
z	Another PurpleLogSet

Returns: A value as specified by GCompareFunc

◆ purple_log_set_free()

void purple_log_set_free ( PurpleLogSet * set )

Frees a log set.

Parameters

set	The log set to destroy

◆ purple_log_write()

void purple_log_write	(	PurpleLog *	log,
		PurpleMessageFlags	type,
		const char *	from,
		time_t	time,
		const char *	message
	)

Writes to a log file.

Assumes you have checked preferences already.

Parameters

log	The log to write to
type	The type of message being logged
from	Whom this message is coming from, or `NULL` for system messages
time	A timestamp in UNIX time
message	The message to log

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ PurpleLog

◆ PurpleLogCommonLoggerData

◆ PurpleLogLogger

◆ PurpleLogSet

◆ PurpleLogSetCallback

Enumeration Type Documentation

◆ PurpleLogReadFlags

◆ PurpleLogType

Function Documentation

◆ purple_log_common_deleter()

◆ purple_log_common_is_deletable()

◆ purple_log_common_lister()

◆ purple_log_common_sizer()

◆ purple_log_common_total_sizer()

◆ purple_log_common_writer()

◆ purple_log_compare()

◆ purple_log_delete()

◆ purple_log_free()

◆ purple_log_get_activity_score()

◆ purple_log_get_handle()

◆ purple_log_get_log_dir()

◆ purple_log_get_log_sets()

◆ purple_log_get_logs()

◆ purple_log_get_size()

◆ purple_log_get_system_logs()

◆ purple_log_get_total_size()

◆ purple_log_is_deletable()

◆ purple_log_logger_add()

◆ purple_log_logger_free()

◆ purple_log_logger_get()

◆ purple_log_logger_get_options()

◆ purple_log_logger_new()

◆ purple_log_logger_remove()

◆ purple_log_logger_set()

◆ purple_log_new()

◆ purple_log_read()

◆ purple_log_set_compare()

◆ purple_log_set_free()

◆ purple_log_write()