libpurple/log.h

   1 /**
   2  * @file log.h Logging API
   3  * @ingroup core
   4  * @see @ref log-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27 #ifndef _PURPLE_LOG_H_
  28 #define _PURPLE_LOG_H_
  29
  30 #include <stdio.h>
  31
  32
  33 /********************************************************
  34  * DATA STRUCTURES **************************************
  35  ********************************************************/
  36
  37 typedef struct _PurpleLog PurpleLog;
  38 typedef struct _PurpleLogLogger PurpleLogLogger;
  39 typedef struct _PurpleLogCommonLoggerData PurpleLogCommonLoggerData;
  40 typedef struct _PurpleLogSet PurpleLogSet;
  41
  42 typedef enum {
  43         PURPLE_LOG_IM,
  44         PURPLE_LOG_CHAT,
  45         PURPLE_LOG_SYSTEM
  46 } PurpleLogType;
  47
  48 typedef enum {
  49         PURPLE_LOG_READ_NO_NEWLINE = 1
  50 } PurpleLogReadFlags;
  51
  52 #include "account.h"
  53 #include "conversation.h"
  54
  55 typedef void (*PurpleLogSetCallback) (GHashTable *sets, PurpleLogSet *set);
  56
  57 /**
  58  * A log logger.
  59  *
  60  * This struct gets filled out and is included in the PurpleLog.  It contains everything
  61  * needed to write and read from logs.
  62  */
  63 struct _PurpleLogLogger {
  64         char *name;               /**< The logger's name */
  65         char *id;                 /**< an identifier to refer to this logger */
  66
  67         /** This gets called when the log is first created.
  68             I don't think this is actually needed. */
  69         void (*create)(PurpleLog *log);
  70
  71         /** This is used to write to the log file */
  72         gsize (*write)(PurpleLog *log,
  73                      PurpleMessageFlags type,
  74                      const char *from,
  75                      time_t time,
  76                      const char *message);
  77
  78         /** Called when the log is destroyed */
  79         void (*finalize)(PurpleLog *log);
  80
  81         /** This function returns a sorted GList of available PurpleLogs */
  82         GList *(*list)(PurpleLogType type, const char *name, PurpleAccount *account);
  83
  84         /** Given one of the logs returned by the logger's list function,
  85          *  this returns the contents of the log in GtkIMHtml markup */
  86         char *(*read)(PurpleLog *log, PurpleLogReadFlags *flags);
  87
  88         /** Given one of the logs returned by the logger's list function,
  89          *  this returns the size of the log in bytes */
  90         int (*size)(PurpleLog *log);
  91
  92         /** Returns the total size of all the logs. If this is undefined a default
  93          *  implementation is used */
  94         int (*total_size)(PurpleLogType type, const char *name, PurpleAccount *account);
  95
  96         /** This function returns a sorted GList of available system PurpleLogs */
  97         GList *(*list_syslog)(PurpleAccount *account);
  98
  99         /** Adds PurpleLogSets to a GHashTable. By passing the data in the PurpleLogSets
 100          *  to list, the caller can get every available PurpleLog from the logger.
 101          *  Loggers using purple_log_common_writer() (or otherwise storing their
 102          *  logs in the same directory structure as the stock loggers) do not
 103          *  need to implement this function.
 104          *
 105          *  Loggers which implement this function must create a PurpleLogSet,
 106          *  then call @a cb with @a sets and the newly created PurpleLogSet. */
 107         void (*get_log_sets)(PurpleLogSetCallback cb, GHashTable *sets);
 108
 109         /* Attempts to delete the specified log, indicating success or failure */
 110         gboolean (*remove)(PurpleLog *log);
 111
 112         /* Tests whether a log is deletable */
 113         gboolean (*is_deletable)(PurpleLog *log);
 114
 115         void (*_purple_reserved1)(void);
 116         void (*_purple_reserved2)(void);
 117         void (*_purple_reserved3)(void);
 118         void (*_purple_reserved4)(void);
 119 };
 120
 121 /**
 122  * A log.  Not the wooden type.
 123  */
 124 struct _PurpleLog {
 125         PurpleLogType type;                     /**< The type of log this is */
 126         char *name;                           /**< The name of this log */
 127         PurpleAccount *account;                 /**< The account this log is taking
 128                                                    place on */
 129         PurpleConversation *conv;               /**< The conversation being logged */
 130         time_t time;                          /**< The time this conversation
 131                                                    started, converted to the local timezone */
 132
 133         PurpleLogLogger *logger;                /**< The logging mechanism this log
 134                                                    is to use */
 135         void *logger_data;                    /**< Data used by the log logger */
 136         struct tm *tm;                        /**< The time this conversation
 137                                                    started, saved with original
 138                                                    timezone data, if available and
 139                                                    if struct tm has the BSD
 140                                                    timezone fields, else @c NULL.
 141                                                    Do NOT modify anything in this struct.*/
 142
 143         /* IMPORTANT: Some code in log.c allocates these without zeroing them.
 144          * IMPORTANT: Update that code if you add members here. */
 145 };
 146
 147 /**
 148  * A common logger_data struct containing a file handle and path, as well
 149  * as a pointer to something else for additional data.
 150  */
 151 struct _PurpleLogCommonLoggerData {
 152         char *path;
 153         FILE *file;
 154         void *extra_data;
 155 };
 156
 157 /**
 158  * Describes available logs.
 159  *
 160  * By passing the elements of this struct to purple_log_get_logs(), the caller
 161  * can get all available PurpleLogs.
 162  */
 163 struct _PurpleLogSet {
 164         PurpleLogType type;                     /**< The type of logs available */
 165         char *name;                           /**< The name of the logs available */
 166         PurpleAccount *account;                 /**< The account the available logs
 167                                                    took place on. This will be
 168                                                    @c NULL if the account no longer
 169                                                    exists. (Depending on a
 170                                                    logger's implementation of
 171                                                    list, it may not be possible
 172                                                    to load such logs.) */
 173         gboolean buddy;                       /**< Is this (account, name) a buddy
 174                                                    on the buddy list? */
 175         char *normalized_name;                /**< The normalized version of
 176                                                    @a name. It must be set, and
 177                                                    may be set to the same pointer
 178                                                    value as @a name. */
 179
 180         /* IMPORTANT: Some code in log.c allocates these without zeroing them.
 181          * IMPORTANT: Update that code if you add members here. */
 182 };
 183
 184 #ifdef __cplusplus
 185 extern "C" {
 186 #endif
 187
 188 /***************************************/
 189 /** @name Log Functions                */
 190 /***************************************/
 191 /*@{*/
 192
 193 /**
 194  * Creates a new log
 195  *
 196  * @param type        The type of log this is.
 197  * @param name        The name of this conversation (buddy name, chat name,
 198  *                    etc.)
 199  * @param account     The account the conversation is occurring on
 200  * @param conv        The conversation being logged
 201  * @param time        The time this conversation started
 202  * @param tm          The time this conversation started, with timezone data,
 203  *                    if available and if struct tm has the BSD timezone fields.
 204  * @return            The new log
 205  */
 206 PurpleLog *purple_log_new(PurpleLogType type, const char *name, PurpleAccount *account,
 207                       PurpleConversation *conv, time_t time, const struct tm *tm);
 208
 209 /**
 210  * Frees a log
 211  *
 212  * @param log         The log to destroy
 213  */
 214 void purple_log_free(PurpleLog *log);
 215
 216 /**
 217  * Writes to a log file. Assumes you have checked preferences already.
 218  *
 219  * @param log          The log to write to
 220  * @param type         The type of message being logged
 221  * @param from         Whom this message is coming from, or @c NULL for
 222  *                     system messages
 223  * @param time         A timestamp in UNIX time
 224  * @param message      The message to log
 225  */
 226 void purple_log_write(PurpleLog *log,
 227                     PurpleMessageFlags type,
 228                     const char *from,
 229                     time_t time,
 230                     const char *message);
 231
 232 /**
 233  * Reads from a log
 234  *
 235  * @param log   The log to read from
 236  * @param flags The returned logging flags.
 237  *
 238  * @return The contents of this log in Purple Markup.
 239  */
 240 char *purple_log_read(PurpleLog *log, PurpleLogReadFlags *flags);
 241
 242 /**
 243  * Returns a list of all available logs
 244  *
 245  * @param type                The type of the log
 246  * @param name                The name of the log
 247  * @param account             The account
 248  * @return                    A sorted list of PurpleLogs
 249  */
 250 GList *purple_log_get_logs(PurpleLogType type, const char *name, PurpleAccount *account);
 251
 252 /**
 253  * Returns a GHashTable of PurpleLogSets.
 254  *
 255  * A "log set" here means the information necessary to gather the
 256  * PurpleLogs for a given buddy/chat. This information would be passed
 257  * to purple_log_list to get a list of PurpleLogs.
 258  *
 259  * The primary use of this function is to get a list of everyone the
 260  * user has ever talked to (assuming he or she uses logging).
 261  *
 262  * The GHashTable that's returned will free all log sets in it when
 263  * destroyed. If a PurpleLogSet is removed from the GHashTable, it
 264  * must be freed with purple_log_set_free().
 265  *
 266  * @return A GHashTable of all available unique PurpleLogSets
 267  */
 268 GHashTable *purple_log_get_log_sets(void);
 269
 270 /**
 271  * Returns a list of all available system logs
 272  *
 273  * @param account The account
 274  * @return        A sorted list of PurpleLogs
 275  */
 276 GList *purple_log_get_system_logs(PurpleAccount *account);
 277
 278 /**
 279  * Returns the size of a log
 280  *
 281  * @param log                 The log
 282  * @return                    The size of the log, in bytes
 283  */
 284 int purple_log_get_size(PurpleLog *log);
 285
 286 /**
 287  * Returns the size, in bytes, of all available logs in this conversation
 288  *
 289  * @param type                The type of the log
 290  * @param name                The name of the log
 291  * @param account             The account
 292  * @return                    The size in bytes
 293  */
 294 int purple_log_get_total_size(PurpleLogType type, const char *name, PurpleAccount *account);
 295
 296 /**
 297  * Returns the activity score of a log, based on total size in bytes,
 298  * which is then decayed based on age
 299  *
 300  * @param type                The type of the log
 301  * @param name                The name of the log
 302  * @param account             The account
 303  * @return                    The activity score
 304  *
 305  * @since 2.6.0
 306  */
 307 int purple_log_get_activity_score(PurpleLogType type, const char *name, PurpleAccount *account);
 308
 309 /**
 310  * Tests whether a log is deletable
 311  *
 312  * A return value of @c FALSE indicates that purple_log_delete() will fail on this
 313  * log, unless something changes between the two calls.  A return value of @c TRUE,
 314  * however, does not guarantee the log can be deleted.
 315  *
 316  * @param log                 The log
 317  * @return                    A boolean indicating if the log is deletable
 318  */
 319 gboolean purple_log_is_deletable(PurpleLog *log);
 320
 321 /**
 322  * Deletes a log
 323  *
 324  * @param log                 The log
 325  * @return                    A boolean indicating success or failure
 326  */
 327 gboolean purple_log_delete(PurpleLog *log);
 328
 329 /**
 330  * Returns the default logger directory Purple uses for a given account
 331  * and username.  This would be where Purple stores logs created by
 332  * the built-in text or HTML loggers.
 333  *
 334  * @param type                The type of the log.
 335  * @param name                The name of the log.
 336  * @param account             The account.
 337  * @return                    The default logger directory for Purple.
 338  */
 339 char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account);
 340
 341 /**
 342  * Implements GCompareFunc for PurpleLogs
 343  *
 344  * @param y                   A PurpleLog
 345  * @param z                   Another PurpleLog
 346  * @return                    A value as specified by GCompareFunc
 347  */
 348 gint purple_log_compare(gconstpointer y, gconstpointer z);
 349
 350 /**
 351  * Implements GCompareFunc for PurpleLogSets
 352  *
 353  * @param y                   A PurpleLogSet
 354  * @param z                   Another PurpleLogSet
 355  * @return                    A value as specified by GCompareFunc
 356  */
 357 gint purple_log_set_compare(gconstpointer y, gconstpointer z);
 358
 359 /**
 360  * Frees a log set
 361  *
 362  * @param set         The log set to destroy
 363  */
 364 void purple_log_set_free(PurpleLogSet *set);
 365
 366 /*@}*/
 367
 368 /******************************************/
 369 /** @name Common Logger Functions         */
 370 /******************************************/
 371 /*@{*/
 372
 373 /**
 374  * Opens a new log file in the standard Purple log location
 375  * with the given file extension, named for the current time,
 376  * for writing.  If a log file is already open, the existing
 377  * file handle is retained.  The log's logger_data value is
 378  * set to a PurpleLogCommonLoggerData struct containing the log
 379  * file handle and log path.
 380  *
 381  * This function is intended to be used as a "common"
 382  * implementation of a logger's @c write function.
 383  * It should only be passed to purple_log_logger_new() and never
 384  * called directly.
 385  *
 386  * @param log   The log to write to.
 387  * @param ext   The file extension to give to this log file.
 388  */
 389 void purple_log_common_writer(PurpleLog *log, const char *ext);
 390
 391 /**
 392  * Returns a sorted GList of PurpleLogs of the requested type.
 393  *
 394  * This function should only be used with logs that are written
 395  * with purple_log_common_writer().  It's intended to be used as
 396  * a "common" implementation of a logger's @c list function.
 397  * It should only be passed to purple_log_logger_new() and never
 398  * called directly.
 399  *
 400  * @param type     The type of the logs being listed.
 401  * @param name     The name of the log.
 402  * @param account  The account of the log.
 403  * @param ext      The file extension this log format uses.
 404  * @param logger   A reference to the logger struct for this log.
 405  *
 406  * @return A sorted GList of PurpleLogs matching the parameters.
 407  */
 408 GList *purple_log_common_lister(PurpleLogType type, const char *name,
 409                                                           PurpleAccount *account, const char *ext,
 410                                                           PurpleLogLogger *logger);
 411
 412 /**
 413  * Returns the total size of all the logs for a given user, with
 414  * a given extension.
 415  *
 416  * This function should only be used with logs that are written
 417  * with purple_log_common_writer().  It's intended to be used as
 418  * a "common" implementation of a logger's @c total_size function.
 419  * It should only be passed to purple_log_logger_new() and never
 420  * called directly.
 421  *
 422  * @param type     The type of the logs being sized.
 423  * @param name     The name of the logs to size
 424  *                 (e.g. the username or chat name).
 425  * @param account  The account of the log.
 426  * @param ext      The file extension this log format uses.
 427  *
 428  * @return The size of all the logs with the specified extension
 429  *         for the specified user.
 430  */
 431 int purple_log_common_total_sizer(PurpleLogType type, const char *name,
 432                                                                 PurpleAccount *account, const char *ext);
 433
 434 /**
 435  * Returns the size of a given PurpleLog.
 436  *
 437  * This function should only be used with logs that are written
 438  * with purple_log_common_writer().  It's intended to be used as
 439  * a "common" implementation of a logger's @c size function.
 440  * It should only be passed to purple_log_logger_new() and never
 441  * called directly.
 442  *
 443  * @param log      The PurpleLog to size.
 444  *
 445  * @return An integer indicating the size of the log in bytes.
 446  */
 447 int purple_log_common_sizer(PurpleLog *log);
 448
 449 /**
 450  * Deletes a log
 451  *
 452  * This function should only be used with logs that are written
 453  * with purple_log_common_writer().  It's intended to be used as
 454  * a "common" implementation of a logger's @c delete function.
 455  * It should only be passed to purple_log_logger_new() and never
 456  * called directly.
 457  *
 458  * @param log      The PurpleLog to delete.
 459  *
 460  * @return A boolean indicating success or failure.
 461  */
 462 gboolean purple_log_common_deleter(PurpleLog *log);
 463
 464 /**
 465  * Checks to see if a log is deletable
 466  *
 467  * This function should only be used with logs that are written
 468  * with purple_log_common_writer().  It's intended to be used as
 469  * a "common" implementation of a logger's @c is_deletable function.
 470  * It should only be passed to purple_log_logger_new() and never
 471  * called directly.
 472  *
 473  * @param log      The PurpleLog to check.
 474  *
 475  * @return A boolean indicating if the log is deletable.
 476  */
 477 gboolean purple_log_common_is_deletable(PurpleLog *log);
 478
 479 /*@}*/
 480
 481 /******************************************/
 482 /** @name Logger Functions                */
 483 /******************************************/
 484 /*@{*/
 485
 486 /**
 487  * Creates a new logger
 488  *
 489  * @param id           The logger's id.
 490  * @param name         The logger's name.
 491  * @param functions    The number of functions being passed. The following
 492  *                     functions are currently available (in order): @c create,
 493  *                     @c write, @c finalize, @c list, @c read, @c size,
 494  *                     @c total_size, @c list_syslog, @c get_log_sets,
 495  *                     @c remove, @c is_deletable.
 496  *                     For details on these functions, see PurpleLogLogger.
 497  *                     Functions may not be skipped. For example, passing
 498  *                     @c create and @c write is acceptable (for a total of
 499  *                     two functions). Passing @c create and @c finalize,
 500  *                     however, is not. To accomplish that, the caller must
 501  *                     pass @c create, @c NULL (a placeholder for @c write),
 502  *                     and @c finalize (for a total of 3 functions).
 503  *
 504  * @return The new logger
 505  */
 506 PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...);
 507
 508 /**
 509  * Frees a logger
 510  *
 511  * @param logger       The logger to free
 512  */
 513 void purple_log_logger_free(PurpleLogLogger *logger);
 514
 515 /**
 516  * Adds a new logger
 517  *
 518  * @param logger       The new logger to add
 519  */
 520 void purple_log_logger_add (PurpleLogLogger *logger);
 521
 522 /**
 523  *
 524  * Removes a logger
 525  *
 526  * @param logger       The logger to remove
 527  */
 528 void purple_log_logger_remove (PurpleLogLogger *logger);
 529
 530 /**
 531  *
 532  * Sets the current logger
 533  *
 534  * @param logger       The logger to set
 535  */
 536 void purple_log_logger_set (PurpleLogLogger *logger);
 537
 538 /**
 539  *
 540  * Returns the current logger
 541  *
 542  * @return logger      The current logger
 543  */
 544 PurpleLogLogger *purple_log_logger_get (void);
 545
 546 /**
 547  * Returns a GList containing the IDs and names of the registered
 548  * loggers.
 549  *
 550  * @return The list of IDs and names.
 551  */
 552 GList *purple_log_logger_get_options(void);
 553
 554 /**************************************************************************/
 555 /** @name Log Subsystem                                                   */
 556 /**************************************************************************/
 557 /*@{*/
 558
 559 /**
 560  * Initializes the log subsystem.
 561  */
 562 void purple_log_init(void);
 563
 564 /**
 565  * Returns the log subsystem handle.
 566  *
 567  * @return The log subsystem handle.
 568  */
 569 void *purple_log_get_handle(void);
 570
 571 /**
 572  * Uninitializes the log subsystem.
 573  */
 574 void purple_log_uninit(void);
 575
 576 /*@}*/
 577
 578
 579 #ifdef __cplusplus
 580 }
 581 #endif
 582
 583 #endif /* _PURPLE_LOG_H_ */