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 (screenname, 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  * Tests whether a log is deletable
 298  *
 299  * A return value of @c FALSE indicates that purple_log_delete() will fail on this
 300  * log, unless something changes between the two calls.  A return value of @c TRUE,
 301  * however, does not guarantee the log can be deleted.
 302  *
 303  * @param log                 The log
 304  * @return                    A boolean indicating if the log is deletable
 305  */
 306 gboolean purple_log_is_deletable(PurpleLog *log);
 307
 308 /**
 309  * Deletes a log
 310  *
 311  * @param log                 The log
 312  * @return                    A boolean indicating success or failure
 313  */
 314 gboolean purple_log_delete(PurpleLog *log);
 315
 316 /**
 317  * Returns the default logger directory Purple uses for a given account
 318  * and username.  This would be where Purple stores logs created by
 319  * the built-in text or HTML loggers.
 320  *
 321  * @param type                The type of the log.
 322  * @param name                The name of the log.
 323  * @param account             The account.
 324  * @return                    The default logger directory for Purple.
 325  */
 326 char *purple_log_get_log_dir(PurpleLogType type, const char *name, PurpleAccount *account);
 327
 328 /**
 329  * Implements GCompareFunc for PurpleLogs
 330  *
 331  * @param y                   A PurpleLog
 332  * @param z                   Another PurpleLog
 333  * @return                    A value as specified by GCompareFunc
 334  */
 335 gint purple_log_compare(gconstpointer y, gconstpointer z);
 336
 337 /**
 338  * Implements GCompareFunc for PurpleLogSets
 339  *
 340  * @param y                   A PurpleLogSet
 341  * @param z                   Another PurpleLogSet
 342  * @return                    A value as specified by GCompareFunc
 343  */
 344 gint purple_log_set_compare(gconstpointer y, gconstpointer z);
 345
 346 /**
 347  * Frees a log set
 348  *
 349  * @param set         The log set to destroy
 350  */
 351 void purple_log_set_free(PurpleLogSet *set);
 352
 353 /*@}*/
 354
 355 /******************************************/
 356 /** @name Common Logger Functions         */
 357 /******************************************/
 358 /*@{*/
 359
 360 /**
 361  * Opens a new log file in the standard Purple log location
 362  * with the given file extension, named for the current time,
 363  * for writing.  If a log file is already open, the existing
 364  * file handle is retained.  The log's logger_data value is
 365  * set to a PurpleLogCommonLoggerData struct containing the log
 366  * file handle and log path.
 367  *
 368  * This function is intended to be used as a "common"
 369  * implementation of a logger's @c write function.
 370  * It should only be passed to purple_log_logger_new() and never
 371  * called directly.
 372  *
 373  * @param log   The log to write to.
 374  * @param ext   The file extension to give to this log file.
 375  */
 376 void purple_log_common_writer(PurpleLog *log, const char *ext);
 377
 378 /**
 379  * Returns a sorted GList of PurpleLogs of the requested type.
 380  *
 381  * This function should only be used with logs that are written
 382  * with purple_log_common_writer().  It's intended to be used as
 383  * a "common" implementation of a logger's @c list function.
 384  * It should only be passed to purple_log_logger_new() and never
 385  * called directly.
 386  *
 387  * @param type     The type of the logs being listed.
 388  * @param name     The name of the log.
 389  * @param account  The account of the log.
 390  * @param ext      The file extension this log format uses.
 391  * @param logger   A reference to the logger struct for this log.
 392  *
 393  * @return A sorted GList of PurpleLogs matching the parameters.
 394  */
 395 GList *purple_log_common_lister(PurpleLogType type, const char *name,
 396                                                           PurpleAccount *account, const char *ext,
 397                                                           PurpleLogLogger *logger);
 398
 399 /**
 400  * Returns the total size of all the logs for a given user, with
 401  * a given extension.
 402  *
 403  * This function should only be used with logs that are written
 404  * with purple_log_common_writer().  It's intended to be used as
 405  * a "common" implementation of a logger's @c total_size function.
 406  * It should only be passed to purple_log_logger_new() and never
 407  * called directly.
 408  *
 409  * @param type     The type of the logs being sized.
 410  * @param name     The name of the logs to size
 411  *                 (e.g. the username or chat name).
 412  * @param account  The account of the log.
 413  * @param ext      The file extension this log format uses.
 414  *
 415  * @return The size of all the logs with the specified extension
 416  *         for the specified user.
 417  */
 418 int purple_log_common_total_sizer(PurpleLogType type, const char *name,
 419                                                                 PurpleAccount *account, const char *ext);
 420
 421 /**
 422  * Returns the size of a given PurpleLog.
 423  *
 424  * This function should only be used with logs that are written
 425  * with purple_log_common_writer().  It's intended to be used as
 426  * a "common" implementation of a logger's @c size function.
 427  * It should only be passed to purple_log_logger_new() and never
 428  * called directly.
 429  *
 430  * @param log      The PurpleLog to size.
 431  *
 432  * @return An integer indicating the size of the log in bytes.
 433  */
 434 int purple_log_common_sizer(PurpleLog *log);
 435
 436 /**
 437  * Deletes a log
 438  *
 439  * This function should only be used with logs that are written
 440  * with purple_log_common_writer().  It's intended to be used as
 441  * a "common" implementation of a logger's @c delete function.
 442  * It should only be passed to purple_log_logger_new() and never
 443  * called directly.
 444  *
 445  * @param log      The PurpleLog to delete.
 446  *
 447  * @return A boolean indicating success or failure.
 448  */
 449 gboolean purple_log_common_deleter(PurpleLog *log);
 450
 451 /**
 452  * Checks to see if a log is deletable
 453  *
 454  * This function should only be used with logs that are written
 455  * with purple_log_common_writer().  It's intended to be used as
 456  * a "common" implementation of a logger's @c is_deletable function.
 457  * It should only be passed to purple_log_logger_new() and never
 458  * called directly.
 459  *
 460  * @param log      The PurpleLog to check.
 461  *
 462  * @return A boolean indicating if the log is deletable.
 463  */
 464 gboolean purple_log_common_is_deletable(PurpleLog *log);
 465
 466 /*@}*/
 467
 468 /******************************************/
 469 /** @name Logger Functions                */
 470 /******************************************/
 471 /*@{*/
 472
 473 /**
 474  * Creates a new logger
 475  *
 476  * @param id           The logger's id.
 477  * @param name         The logger's name.
 478  * @param functions    The number of functions being passed. The following
 479  *                     functions are currently available (in order): @c create,
 480  *                     @c write, @c finalize, @c list, @c read, @c size,
 481  *                     @c total_size, @c list_syslog, @c get_log_sets,
 482  *                     @c remove, @c is_deletable.
 483  *                     For details on these functions, see PurpleLogLogger.
 484  *                     Functions may not be skipped. For example, passing
 485  *                     @c create and @c write is acceptable (for a total of
 486  *                     two functions). Passing @c create and @c finalize,
 487  *                     however, is not. To accomplish that, the caller must
 488  *                     pass @c create, @c NULL (a placeholder for @c write),
 489  *                     and @c finalize (for a total of 3 functions).
 490  *
 491  * @return The new logger
 492  */
 493 PurpleLogLogger *purple_log_logger_new(const char *id, const char *name, int functions, ...);
 494
 495 /**
 496  * Frees a logger
 497  *
 498  * @param logger       The logger to free
 499  */
 500 void purple_log_logger_free(PurpleLogLogger *logger);
 501
 502 /**
 503  * Adds a new logger
 504  *
 505  * @param logger       The new logger to add
 506  */
 507 void purple_log_logger_add (PurpleLogLogger *logger);
 508
 509 /**
 510  *
 511  * Removes a logger
 512  *
 513  * @param logger       The logger to remove
 514  */
 515 void purple_log_logger_remove (PurpleLogLogger *logger);
 516
 517 /**
 518  *
 519  * Sets the current logger
 520  *
 521  * @param logger       The logger to set
 522  */
 523 void purple_log_logger_set (PurpleLogLogger *logger);
 524
 525 /**
 526  *
 527  * Returns the current logger
 528  *
 529  * @return logger      The current logger
 530  */
 531 PurpleLogLogger *purple_log_logger_get (void);
 532
 533 /**
 534  * Returns a GList containing the IDs and names of the registered
 535  * loggers.
 536  *
 537  * @return The list of IDs and names.
 538  */
 539 GList *purple_log_logger_get_options(void);
 540
 541 /**************************************************************************/
 542 /** @name Log Subsystem                                                   */
 543 /**************************************************************************/
 544 /*@{*/
 545
 546 /**
 547  * Initializes the log subsystem.
 548  */
 549 void purple_log_init(void);
 550
 551 /**
 552  * Returns the log subsystem handle.
 553  *
 554  * @return The log subsystem handle.
 555  */
 556 void *purple_log_get_handle(void);
 557
 558 /**
 559  * Uninitializes the log subsystem.
 560  */
 561 void purple_log_uninit(void);
 562
 563 /*@}*/
 564
 565
 566 #ifdef __cplusplus
 567 }
 568 #endif
 569
 570 #endif /* _PURPLE_LOG_H_ */