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:

Go to the source code of 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
PurpleLogpurple_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
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
PurpleLogLoggerpurple_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.
PurpleLogLoggerpurple_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
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.

Function Documentation

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
logThe PurpleLog to delete.
Returns
A boolean indicating success or failure.
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
logThe PurpleLog to check.
Returns
A boolean indicating if the log is deletable.
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
typeThe type of the logs being listed.
nameThe name of the log.
accountThe account of the log.
extThe file extension this log format uses.
loggerA reference to the logger struct for this log.
Returns
A sorted GList of PurpleLogs matching the parameters.
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
logThe PurpleLog to size.
Returns
An integer indicating the size of the log in bytes.
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
typeThe type of the logs being sized.
nameThe name of the logs to size (e.g. the username or chat name).
accountThe account of the log.
extThe file extension this log format uses.
Returns
The size of all the logs with the specified extension for the specified user.
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
logThe log to write to.
extThe file extension to give to this log file.
gint purple_log_compare ( gconstpointer  y,
gconstpointer  z 
)

Implements GCompareFunc for PurpleLogs.

Parameters
yA PurpleLog
zAnother PurpleLog
Returns
A value as specified by GCompareFunc
gboolean purple_log_delete ( PurpleLog log)

Deletes a log.

Parameters
logThe log
Returns
A boolean indicating success or failure
void purple_log_free ( PurpleLog log)

Frees a log.

Parameters
logThe log to destroy
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
typeThe type of the log
nameThe name of the log
accountThe account
Returns
The activity score
Since
2.6.0
void* purple_log_get_handle ( void  )

Returns the log subsystem handle.

Returns
The log subsystem handle.
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
typeThe type of the log.
nameThe name of the log.
accountThe account.
Returns
The default logger directory for Purple.
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
GList* purple_log_get_logs ( PurpleLogType  type,
const char *  name,
PurpleAccount account 
)

Returns a list of all available logs.

Parameters
typeThe type of the log
nameThe name of the log
accountThe account
Returns
A sorted list of PurpleLogs
int purple_log_get_size ( PurpleLog log)

Returns the size of a log.

Parameters
logThe log
Returns
The size of the log, in bytes
GList* purple_log_get_system_logs ( PurpleAccount account)

Returns a list of all available system logs.

Parameters
accountThe account
Returns
A sorted list of PurpleLogs
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
typeThe type of the log
nameThe name of the log
accountThe account
Returns
The size in bytes
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
logThe log
Returns
A boolean indicating if the log is deletable
void purple_log_logger_add ( PurpleLogLogger logger)

Adds a new logger.

Parameters
loggerThe new logger to add
void purple_log_logger_free ( PurpleLogLogger logger)

Frees a logger.

Parameters
loggerThe logger to free
PurpleLogLogger* purple_log_logger_get ( void  )

Returns the current logger.

Returns
logger The current logger
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.
PurpleLogLogger* purple_log_logger_new ( const char *  id,
const char *  name,
int  functions,
  ... 
)

Creates a new logger.

Parameters
idThe logger's id.
nameThe logger's name.
functionsThe 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
void purple_log_logger_remove ( PurpleLogLogger logger)

Removes a logger.

Parameters
loggerThe logger to remove
void purple_log_logger_set ( PurpleLogLogger logger)

Sets the current logger.

Parameters
loggerThe logger to set
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
typeThe type of log this is.
nameThe name of this conversation (buddy name, chat name, etc.)
accountThe account the conversation is occurring on
convThe conversation being logged
timeThe time this conversation started
tmThe time this conversation started, with timezone data, if available and if struct tm has the BSD timezone fields.
Returns
The new log
char* purple_log_read ( PurpleLog log,
PurpleLogReadFlags *  flags 
)

Reads from a log.

Parameters
logThe log to read from
flagsThe returned logging flags.
Returns
The contents of this log in Purple Markup.
gint purple_log_set_compare ( gconstpointer  y,
gconstpointer  z 
)

Implements GCompareFunc for PurpleLogSets.

Parameters
yA PurpleLogSet
zAnother PurpleLogSet
Returns
A value as specified by GCompareFunc
void purple_log_set_free ( PurpleLogSet set)

Frees a log set.

Parameters
setThe log set to destroy
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
logThe log to write to
typeThe type of message being logged
fromWhom this message is coming from, or NULL for system messages
timeA timestamp in UNIX time
messageThe message to log
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!