diff -r 7d964cdccbb5 -r 91119588bc3a libpurple/log.h --- a/libpurple/log.h Fri Jan 31 19:42:12 2014 +0530 +++ b/libpurple/log.h Fri Jan 31 20:07:33 2014 +0530 @@ -56,6 +56,8 @@ typedef void (*PurpleLogSetCallback) (GHashTable *sets, PurpleLogSet *set); /** + * PurpleLogLogger: + * * A log logger. * * This struct gets filled out and is included in the PurpleLog. It contains everything @@ -104,7 +106,7 @@ * need to implement this function. * * Loggers which implement this function must create a PurpleLogSet, - * then call @a cb with @a sets and the newly created PurpleLogSet. */ + * then call @cb with @sets and the newly created PurpleLogSet. */ void (*get_log_sets)(PurpleLogSetCallback cb, GHashTable *sets); /* Attempts to delete the specified log, indicating success or failure */ @@ -121,32 +123,40 @@ }; /** + * PurpleLog: + * @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 + * timezone + * @logger: The logging mechanism this log is to use + * @logger_data: Data used by the log logger + * @tm: The time this conversation started, saved with original + * timezone data, if available and if struct tm has the BSD + * timezone fields, else %NULL. Do NOT modify anything in this + * struct. + * * A log. Not the wooden type. */ struct _PurpleLog { - PurpleLogType type; /**< The type of log this is */ - char *name; /**< The name of this log */ - PurpleAccount *account; /**< The account this log is taking - place on */ - PurpleConversation *conv; /**< The conversation being logged */ - time_t time; /**< The time this conversation - started, converted to the local timezone */ + PurpleLogType type; + char *name; + PurpleAccount *account; + PurpleConversation *conv; + time_t time; - PurpleLogLogger *logger; /**< The logging mechanism this log - is to use */ - void *logger_data; /**< Data used by the log logger */ - struct tm *tm; /**< The time this conversation - started, saved with original - timezone data, if available and - if struct tm has the BSD - timezone fields, else %NULL. - Do NOT modify anything in this struct.*/ + PurpleLogLogger *logger; + void *logger_data; + struct tm *tm; /* 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. */ @@ -157,27 +167,28 @@ }; /** + * PurpleLogSet: + * @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 + * load such logs.) + * @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. */ struct _PurpleLogSet { - PurpleLogType type; /**< The type of logs available */ - char *name; /**< The name of the logs available */ - PurpleAccount *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 load such logs.) */ - gboolean buddy; /**< Is this (account, name) a buddy - on the buddy list? */ - char *normalized_name; /**< The normalized version of - @a name. It must be set, and - may be set to the same pointer - value as @a name. */ + PurpleLogType type; + char *name; + PurpleAccount *account; + gboolean buddy; + char *normalized_name; /* IMPORTANT: Some code in log.c allocates these without zeroing them. * IMPORTANT: Update that code if you add members here. */ @@ -191,6 +202,8 @@ /*@{*/ /** + * purple_log_get_type: + * * 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. @@ -198,8 +211,7 @@ GType purple_log_get_type(void); /** - * Creates a new log - * + * purple_log_new: * @type: The type of log this is. * @name: The name of this conversation (buddy name, chat name, * etc.) @@ -208,27 +220,32 @@ * @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. + * + * Creates a new log + * * Returns: The new log */ PurpleLog *purple_log_new(PurpleLogType type, const char *name, PurpleAccount *account, PurpleConversation *conv, time_t time, const struct tm *tm); /** - * Frees a log + * purple_log_free: + * @log: The log to destroy * - * @log: The log to destroy + * Frees a log */ void purple_log_free(PurpleLog *log); /** - * Writes to a log file. Assumes you have checked preferences already. - * + * purple_log_write: * @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 + * + * Writes to a log file. Assumes you have checked preferences already. */ void purple_log_write(PurpleLog *log, PurpleMessageFlags type, @@ -237,26 +254,31 @@ const char *message); /** - * Reads from a log - * + * purple_log_read: * @log: The log to read from * @flags: The returned logging flags. * + * Reads from a log + * * Returns: The contents of this log in Purple Markup. */ char *purple_log_read(PurpleLog *log, PurpleLogReadFlags *flags); /** - * Returns a list of all available logs - * + * purple_log_get_logs: * @type: The type of the log * @name: The name of the log * @account: The account + * + * Returns a list of all available logs + * * Returns: A sorted list of PurpleLogs */ 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 @@ -275,96 +297,115 @@ GHashTable *purple_log_get_log_sets(void); /** + * purple_log_get_system_logs: + * @account: The account + * * Returns a list of all available system logs * - * @account: The account * Returns: A sorted list of PurpleLogs */ GList *purple_log_get_system_logs(PurpleAccount *account); /** + * purple_log_get_size: + * @log: The log + * * Returns the size of a log * - * @log: The log * Returns: The size of the log, in bytes */ int purple_log_get_size(PurpleLog *log); /** - * Returns the size, in bytes, of all available logs in this conversation - * + * purple_log_get_total_size: * @type: The type of the log * @name: The name of the log * @account: The account + * + * 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 + * @account: The account + * * Returns the activity score of a log, based on total size in bytes, * which is then decayed based on age * - * @type: The type of the log - * @name: The name of the log - * @account: The account * Returns: The activity score */ int purple_log_get_activity_score(PurpleLogType type, const char *name, PurpleAccount *account); /** + * purple_log_is_deletable: + * @log: The 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. * - * @log: The log * Returns: A boolean indicating if the log is deletable */ gboolean purple_log_is_deletable(PurpleLog *log); /** + * purple_log_delete: + * @log: The log + * * Deletes a log * - * @log: The 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. + * @account: The 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. * - * @type: The type of the log. - * @name: The name of the log. - * @account: The account. * Returns: The default logger directory for Purple. */ char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account); /** + * purple_log_compare: + * @y: A PurpleLog + * @z: Another PurpleLog + * * Implements GCompareFunc for PurpleLogs * - * @y: A PurpleLog - * @z: Another PurpleLog * Returns: A value as specified by GCompareFunc */ gint purple_log_compare(gconstpointer y, gconstpointer z); /** + * purple_log_set_compare: + * @y: A PurpleLogSet + * @z: Another PurpleLogSet + * * Implements GCompareFunc for PurpleLogSets * - * @y: A PurpleLogSet - * @z: Another PurpleLogSet * Returns: A value as specified by GCompareFunc */ gint purple_log_set_compare(gconstpointer y, gconstpointer z); /** - * Frees a log set + * purple_log_set_free: + * @set: The log set to destroy * - * @set: The log set to destroy + * Frees a log set */ void purple_log_set_free(PurpleLogSet *set); @@ -376,6 +417,10 @@ /*@{*/ /** + * 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 @@ -384,30 +429,28 @@ * file handle and log path. * * This function is intended to be used as a "common" - * implementation of a logger's @c write function. + * implementation of a logger's write function. * It should only be passed to purple_log_logger_new() and never * called directly. - * - * @log: The log to write to. - * @ext: The file extension to give to this log file. */ void purple_log_common_writer(PurpleLog *log, const char *ext); /** - * 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 @c list function. - * It should only be passed to purple_log_logger_new() and never - * called directly. - * + * 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 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. + * * Returns: A sorted GList of PurpleLogs matching the parameters. */ GList *purple_log_common_lister(PurpleLogType type, const char *name, @@ -415,21 +458,22 @@ 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 * 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 @c total_size function. + * a "common" implementation of a logger's total_size function. * It should only be passed to purple_log_logger_new() and never * called directly. * - * @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. */ @@ -437,46 +481,49 @@ 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 @c size function. + * a "common" implementation of a logger's size function. * It should only be passed to purple_log_logger_new() and never * called directly. * - * @log: The PurpleLog to size. - * * 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. + * * 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 @c delete function. + * a "common" implementation of a logger's delete function. * It should only be passed to purple_log_logger_new() and never * called directly. * - * @log: The PurpleLog to delete. - * * 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 @c is_deletable function. + * a "common" implementation of a logger's is_deletable function. * It should only be passed to purple_log_logger_new() and never * called directly. * - * @log: The PurpleLog to check. - * * Returns: A boolean indicating if the log is deletable. */ gboolean purple_log_common_is_deletable(PurpleLog *log); @@ -489,58 +536,64 @@ /*@{*/ /** - * Creates a new logger - * + * purple_log_logger_new: * @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): @c create, - * @c write, @c finalize, @c list, @c read, @c size, - * @c total_size, @c list_syslog, @c get_log_sets, - * @c remove, @c is_deletable. - * For details on these functions, see PurpleLogLogger. - * Functions may not be skipped. For example, passing - * @c create and @c write is acceptable (for a total of - * two functions). Passing @c create and @c finalize, - * however, is not. To accomplish that, the caller must - * pass @c create, %NULL (a placeholder for @c write), - * and @c finalize (for a total of 3 functions). + * 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). + * + * Creates a new logger * * Returns: The new logger */ PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...); /** - * Frees a logger + * purple_log_logger_free: + * @logger: The logger to free * - * @logger: The logger to free + * Frees a logger */ void purple_log_logger_free(PurpleLogLogger *logger); /** - * Adds a new logger + * purple_log_logger_add: + * @logger: The new logger to add * - * @logger: The new logger to add + * Adds a new logger */ void purple_log_logger_add (PurpleLogLogger *logger); /** + * purple_log_logger_remove: + * @logger: The logger to remove * * Removes a logger - * - * @logger: The logger to remove */ void purple_log_logger_remove (PurpleLogLogger *logger); /** + * purple_log_logger_set: + * @logger: The logger to set * * Sets the current logger - * - * @logger: The logger to set */ void purple_log_logger_set (PurpleLogLogger *logger); /** + * purple_log_logger_get: * * Returns the current logger * @@ -549,6 +602,8 @@ PurpleLogLogger *purple_log_logger_get (void); /** + * purple_log_logger_get_options: + * * Returns a GList containing the IDs and names of the registered * loggers. * @@ -562,11 +617,15 @@ /*@{*/ /** + * purple_log_init: + * * Initializes the log subsystem. */ void purple_log_init(void); /** + * purple_log_get_handle: + * * Returns the log subsystem handle. * * Returns: The log subsystem handle. @@ -574,6 +633,8 @@ void *purple_log_get_handle(void); /** + * purple_log_uninit: + * * Uninitializes the log subsystem. */ void purple_log_uninit(void);