libpurple/debug.h

   1 /**
   2  * @file debug.h Debug API
   3  * @ingroup core
   4  */
   5
   6 /* purple
   7  *
   8  * Purple is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26 #ifndef _PURPLE_DEBUG_H_
  27 #define _PURPLE_DEBUG_H_
  28
  29 #include <glib.h>
  30 #include <stdarg.h>
  31
  32 /**
  33  * Debug levels.
  34  */
  35 typedef enum
  36 {
  37         PURPLE_DEBUG_ALL = 0,  /**< All debug levels.              */
  38         PURPLE_DEBUG_MISC,     /**< General chatter.               */
  39         PURPLE_DEBUG_INFO,     /**< General operation Information. */
  40         PURPLE_DEBUG_WARNING,  /**< Warnings.                      */
  41         PURPLE_DEBUG_ERROR,    /**< Errors.                        */
  42         PURPLE_DEBUG_FATAL     /**< Fatal errors.                  */
  43
  44 } PurpleDebugLevel;
  45
  46 /**
  47  * Debug UI operations.
  48  */
  49 typedef struct
  50 {
  51         void (*print)(PurpleDebugLevel level, const char *category,
  52                                   const char *arg_s);
  53         gboolean (*is_enabled)(PurpleDebugLevel level,
  54                         const char *category);
  55
  56         void (*_purple_reserved1)(void);
  57         void (*_purple_reserved2)(void);
  58         void (*_purple_reserved3)(void);
  59         void (*_purple_reserved4)(void);
  60 } PurpleDebugUiOps;
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66 /**************************************************************************/
  67 /** @name Debug API                                                       */
  68 /**************************************************************************/
  69 /**
  70  * Outputs debug information.
  71  *
  72  * @param level    The debug level.
  73  * @param category The category (or @c NULL).
  74  * @param format   The format string.
  75  */
  76 void purple_debug(PurpleDebugLevel level, const char *category,
  77                                 const char *format, ...) G_GNUC_PRINTF(3, 4);
  78
  79 /**
  80  * Outputs misc. level debug information.
  81  *
  82  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_MISC as
  83  * the level.
  84  *
  85  * @param category The category (or @c NULL).
  86  * @param format   The format string.
  87  *
  88  * @see purple_debug()
  89  */
  90 void purple_debug_misc(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
  91
  92 /**
  93  * Outputs info level debug information.
  94  *
  95  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_INFO as
  96  * the level.
  97  *
  98  * @param category The category (or @c NULL).
  99  * @param format   The format string.
 100  *
 101  * @see purple_debug()
 102  */
 103 void purple_debug_info(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 104
 105 /**
 106  * Outputs warning level debug information.
 107  *
 108  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_WARNING as
 109  * the level.
 110  *
 111  * @param category The category (or @c NULL).
 112  * @param format   The format string.
 113  *
 114  * @see purple_debug()
 115  */
 116 void purple_debug_warning(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 117
 118 /**
 119  * Outputs error level debug information.
 120  *
 121  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_ERROR as
 122  * the level.
 123  *
 124  * @param category The category (or @c NULL).
 125  * @param format   The format string.
 126  *
 127  * @see purple_debug()
 128  */
 129 void purple_debug_error(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 130
 131 /**
 132  * Outputs fatal error level debug information.
 133  *
 134  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_ERROR as
 135  * the level.
 136  *
 137  * @param category The category (or @c NULL).
 138  * @param format   The format string.
 139  *
 140  * @see purple_debug()
 141  */
 142 void purple_debug_fatal(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 143
 144 /**
 145  * Enable or disable printing debug output to the console.
 146  *
 147  * @param enabled TRUE to enable debug output or FALSE to disable it.
 148  */
 149 void purple_debug_set_enabled(gboolean enabled);
 150
 151 /**
 152  * Check if console debug output is enabled.
 153  *
 154  * @return TRUE if debugging is enabled, FALSE if it is not.
 155  */
 156 gboolean purple_debug_is_enabled(void);
 157
 158 /**
 159  * Enable or disable verbose debugging.  This ordinarily should only be called
 160  * by #purple_debug_init, but there are cases where this can be useful for
 161  * plugins.
 162  *
 163  * @param verbose TRUE to enable verbose debugging or FALSE to disable it.
 164  *
 165  * @since 2.6.0
 166  */
 167 void purple_debug_set_verbose(gboolean verbose);
 168
 169 /**
 170  * Check if verbose logging is enabled.
 171  *
 172  * @return TRUE if verbose debugging is enabled, FALSE if it is not.
 173  *
 174  * @since 2.6.0
 175  */
 176 gboolean purple_debug_is_verbose(void);
 177
 178 /**
 179  * Enable or disable unsafe debugging.  This ordinarily should only be called
 180  * by #purple_debug_init, but there are cases where this can be useful for
 181  * plugins.
 182  *
 183  * @param unsafe TRUE to enable debug logging of messages that could
 184  *        potentially contain passwords and other sensitive information.
 185  *        FALSE to disable it.
 186  *
 187  * @since 2.6.0
 188  */
 189 void purple_debug_set_unsafe(gboolean unsafe);
 190
 191 /**
 192  * Check if unsafe debugging is enabled.  Defaults to FALSE.
 193  *
 194  * @return TRUE if the debug logging of all messages is enabled, FALSE
 195  *         if messages that could potentially contain passwords and other
 196  *         sensitive information are not logged.
 197  *
 198  * @since 2.6.0
 199  */
 200 gboolean purple_debug_is_unsafe(void);
 201
 202 /*@}*/
 203
 204 /**************************************************************************/
 205 /** @name UI Registration Functions                                       */
 206 /**************************************************************************/
 207 /*@{*/
 208
 209 /**
 210  * Sets the UI operations structure to be used when outputting debug
 211  * information.
 212  *
 213  * @param ops The UI operations structure.
 214  */
 215 void purple_debug_set_ui_ops(PurpleDebugUiOps *ops);
 216
 217 /**
 218  * Returns the UI operations structure used when outputting debug
 219  * information.
 220  *
 221  * @return The UI operations structure in use.
 222  */
 223 PurpleDebugUiOps *purple_debug_get_ui_ops(void);
 224
 225 /*@}*/
 226
 227 /**************************************************************************/
 228 /** @name Debug Subsystem                                                 */
 229 /**************************************************************************/
 230 /*@{*/
 231
 232 /**
 233  * Initializes the debug subsystem.
 234  */
 235 void purple_debug_init(void);
 236
 237 /*@}*/
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243 #endif /* _PURPLE_DEBUG_H_ */