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 verbose 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 verbose debugging or FALSE to disable it.
 184  *
 185  * @since 2.6.0
 186  */
 187 void purple_debug_set_unsafe(gboolean unsafe);
 188
 189 /**
 190  * Check if unsafe debugging is enabled.
 191  *
 192  * @return TRUE if verbose debugging is enabled, FALSE if it is not.
 193  *
 194  * @since 2.6.0
 195  */
 196 gboolean purple_debug_is_unsafe(void);
 197
 198 /*@}*/
 199
 200 /**************************************************************************/
 201 /** @name UI Registration Functions                                       */
 202 /**************************************************************************/
 203 /*@{*/
 204
 205 /**
 206  * Sets the UI operations structure to be used when outputting debug
 207  * information.
 208  *
 209  * @param ops The UI operations structure.
 210  */
 211 void purple_debug_set_ui_ops(PurpleDebugUiOps *ops);
 212
 213 /**
 214  * Returns the UI operations structure used when outputting debug
 215  * information.
 216  *
 217  * @return The UI operations structure in use.
 218  */
 219 PurpleDebugUiOps *purple_debug_get_ui_ops(void);
 220
 221 /*@}*/
 222
 223 /**************************************************************************/
 224 /** @name Debug Subsystem                                                 */
 225 /**************************************************************************/
 226 /*@{*/
 227
 228 /**
 229  * Initializes the debug subsystem.
 230  */
 231 void purple_debug_init(void);
 232
 233 /*@}*/
 234
 235 #ifdef __cplusplus
 236 }
 237 #endif
 238
 239 #endif /* _PURPLE_DEBUG_H_ */