Data Structures | Typedefs | Enumerations
log.h File Reference
libpurple

Logging API. More...

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

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
PurpleLog * | purple_log_new (PurpleLogType type, const char *name, PurpleAccount *account, PurpleConversation *conv, time_t time, const struct tm *tm)
| Creates a new log. More...
void | purple_log_free (PurpleLog *log)
| Frees a log. More...
void | purple_log_write (PurpleLog *log, PurpleMessageFlags type, const char *from, time_t time, const char *message)
| Writes to a log file. More...
char * | purple_log_read (PurpleLog *log, PurpleLogReadFlags *flags)
| Reads from a log. More...
GList * | purple_log_get_logs (PurpleLogType type, const char *name, PurpleAccount *account)
| Returns a list of all available logs. More...
GHashTable * | purple_log_get_log_sets (void)
| Returns a GHashTable of PurpleLogSets. More...
GList * | purple_log_get_system_logs (PurpleAccount *account)
| Returns a list of all available system logs. More...
int | purple_log_get_size (PurpleLog *log)
| Returns the size of a log. More...
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. More...
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. More...
gboolean | purple_log_is_deletable (PurpleLog *log)
| Tests whether a log is deletable. More...
gboolean | purple_log_delete (PurpleLog *log)
| Deletes a log. More...
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. More...
gint | purple_log_compare (gconstpointer y, gconstpointer z)
| Implements GCompareFunc for PurpleLogs. More...
gint | purple_log_set_compare (gconstpointer y, gconstpointer z)
| Implements GCompareFunc for PurpleLogSets. More...
void | purple_log_set_free (PurpleLogSet *set)
| Frees a log set. More...
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. More...
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. More...
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. More...
int | purple_log_common_sizer (PurpleLog *log)
| Returns the size of a given PurpleLog. More...
gboolean | purple_log_common_deleter (PurpleLog *log)
| Deletes a log. More...
gboolean | purple_log_common_is_deletable (PurpleLog *log)
| Checks to see if a log is deletable. More...
Logger Functions
PurpleLogLogger * | purple_log_logger_new (const char *id, const char *name, int functions,...)
| Creates a new logger. More...
void | purple_log_logger_free (PurpleLogLogger *logger)
| Frees a logger. More...
void | purple_log_logger_add (PurpleLogLogger *logger)
| Adds a new logger. More...
void | purple_log_logger_remove (PurpleLogLogger *logger)
| Removes a logger. More...
void | purple_log_logger_set (PurpleLogLogger *logger)
| Sets the current logger. More...
PurpleLogLogger * | purple_log_logger_get (void)
| Returns the current logger. More...
GList * | purple_log_logger_get_options (void)
| Returns a GList containing the IDs and names of the registered loggers. More...
Log Subsystem
void | purple_log_init (void)
| Initializes the log subsystem.
void * | purple_log_get_handle (void)
| Returns the log subsystem handle. More...
void | purple_log_uninit (void)
| Uninitializes the log subsystem.

## Detailed Description

Logging API.

See also
  Log Signals

Definition in 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