libpurple/log.h

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