libpurple/debug.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_DEBUG_H_
  23 #define _PURPLE_DEBUG_H_
  24 /**
  25  * SECTION:debug
  26  * @section_id: libpurple-debug
  27  * @short_description: <filename>debug.h</filename>
  28  * @title: Debug API
  29  */
  30
  31 #include <glib.h>
  32 #include <glib-object.h>
  33
  34 #include <stdarg.h>
  35
  36 #define PURPLE_TYPE_DEBUG_UI_OPS (purple_debug_ui_ops_get_type())
  37
  38 typedef struct _PurpleDebugUiOps PurpleDebugUiOps;
  39
  40 /**
  41  * PurpleDebugLevel:
  42  * @PURPLE_DEBUG_ALL:     All debug levels.
  43  * @PURPLE_DEBUG_MISC:    General chatter.
  44  * @PURPLE_DEBUG_INFO:    General operation Information.
  45  * @PURPLE_DEBUG_WARNING: Warnings.
  46  * @PURPLE_DEBUG_ERROR:   Errors.
  47  * @PURPLE_DEBUG_FATAL:   Fatal errors.
  48  *
  49  * Debug levels.
  50  */
  51 typedef enum
  52 {
  53         PURPLE_DEBUG_ALL = 0,
  54         PURPLE_DEBUG_MISC,
  55         PURPLE_DEBUG_INFO,
  56         PURPLE_DEBUG_WARNING,
  57         PURPLE_DEBUG_ERROR,
  58         PURPLE_DEBUG_FATAL
  59
  60 } PurpleDebugLevel;
  61
  62 /**
  63  * PurpleDebugUiOps:
  64  *
  65  * Debug UI operations.
  66  */
  67 struct _PurpleDebugUiOps
  68 {
  69         void (*print)(PurpleDebugLevel level, const char *category,
  70                                   const char *arg_s);
  71         gboolean (*is_enabled)(PurpleDebugLevel level,
  72                         const char *category);
  73
  74         /*< private >*/
  75         void (*_purple_reserved1)(void);
  76         void (*_purple_reserved2)(void);
  77         void (*_purple_reserved3)(void);
  78         void (*_purple_reserved4)(void);
  79 };
  80
  81 G_BEGIN_DECLS
  82
  83 /**************************************************************************/
  84 /* Debug API                                                              */
  85 /**************************************************************************/
  86 /**
  87  * purple_debug:
  88  * @level:    The debug level.
  89  * @category: The category (or %NULL).
  90  * @format:   The format string.
  91  *
  92  * Outputs debug information.
  93  */
  94 void purple_debug(PurpleDebugLevel level, const char *category,
  95                                 const char *format, ...) G_GNUC_PRINTF(3, 4);
  96
  97 /**
  98  * purple_debug_misc:
  99  * @category: The category (or %NULL).
 100  * @format:   The format string.
 101  *
 102  * Outputs misc. level debug information.
 103  *
 104  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_MISC as
 105  * the level.
 106  *
 107  * See purple_debug().
 108  */
 109 void purple_debug_misc(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 110
 111 /**
 112  * purple_debug_info:
 113  * @category: The category (or %NULL).
 114  * @format:   The format string.
 115  *
 116  * Outputs info level debug information.
 117  *
 118  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_INFO as
 119  * the level.
 120  *
 121  * See purple_debug().
 122  */
 123 void purple_debug_info(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 124
 125 /**
 126  * purple_debug_warning:
 127  * @category: The category (or %NULL).
 128  * @format:   The format string.
 129  *
 130  * Outputs warning level debug information.
 131  *
 132  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_WARNING as
 133  * the level.
 134  *
 135  * See purple_debug().
 136  */
 137 void purple_debug_warning(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 138
 139 /**
 140  * purple_debug_error:
 141  * @category: The category (or %NULL).
 142  * @format:   The format string.
 143  *
 144  * Outputs error level debug information.
 145  *
 146  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_ERROR as
 147  * the level.
 148  *
 149  * See purple_debug().
 150  */
 151 void purple_debug_error(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 152
 153 /**
 154  * purple_debug_fatal:
 155  * @category: The category (or %NULL).
 156  * @format:   The format string.
 157  *
 158  * Outputs fatal error level debug information.
 159  *
 160  * This is a wrapper for purple_debug(), and uses PURPLE_DEBUG_ERROR as
 161  * the level.
 162  *
 163  * See purple_debug().
 164  */
 165 void purple_debug_fatal(const char *category, const char *format, ...) G_GNUC_PRINTF(2, 3);
 166
 167 /**
 168  * purple_debug_set_enabled:
 169  * @enabled: TRUE to enable debug output or FALSE to disable it.
 170  *
 171  * Enable or disable printing debug output to the console.
 172  */
 173 void purple_debug_set_enabled(gboolean enabled);
 174
 175 /**
 176  * purple_debug_is_enabled:
 177  *
 178  * Check if console debug output is enabled.
 179  *
 180  * Returns: TRUE if debugging is enabled, FALSE if it is not.
 181  */
 182 gboolean purple_debug_is_enabled(void);
 183
 184 /**
 185  * purple_debug_set_verbose:
 186  * @verbose: TRUE to enable verbose debugging or FALSE to disable it.
 187  *
 188  * Enable or disable verbose debugging.  This ordinarily should only be called
 189  * by #purple_debug_init, but there are cases where this can be useful for
 190  * plugins.
 191  */
 192 void purple_debug_set_verbose(gboolean verbose);
 193
 194 /**
 195  * purple_debug_is_verbose:
 196  *
 197  * Check if verbose logging is enabled.
 198  *
 199  * Returns: TRUE if verbose debugging is enabled, FALSE if it is not.
 200  */
 201 gboolean purple_debug_is_verbose(void);
 202
 203 /**
 204  * purple_debug_set_unsafe:
 205  * @unsafe: TRUE to enable debug logging of messages that could
 206  *        potentially contain passwords and other sensitive information.
 207  *        FALSE to disable it.
 208  *
 209  * Enable or disable unsafe debugging.  This ordinarily should only be called
 210  * by #purple_debug_init, but there are cases where this can be useful for
 211  * plugins.
 212  */
 213 void purple_debug_set_unsafe(gboolean unsafe);
 214
 215 /**
 216  * purple_debug_is_unsafe:
 217  *
 218  * Check if unsafe debugging is enabled.  Defaults to FALSE.
 219  *
 220  * Returns: TRUE if the debug logging of all messages is enabled, FALSE
 221  *         if messages that could potentially contain passwords and other
 222  *         sensitive information are not logged.
 223  */
 224 gboolean purple_debug_is_unsafe(void);
 225
 226 /**
 227  * purple_debug_set_colored:
 228  * @colored: TRUE to enable colored output, FALSE to disable it.
 229  *
 230  * Enable or disable colored output for bash console.
 231  */
 232 void purple_debug_set_colored(gboolean colored);
 233
 234 /**************************************************************************/
 235 /* UI Registration Functions                                              */
 236 /**************************************************************************/
 237
 238 /**
 239  * purple_debug_ui_ops_get_type:
 240  *
 241  * Returns: The #GType for the #PurpleDebugUiOps boxed structure.
 242  */
 243 GType purple_debug_ui_ops_get_type(void);
 244
 245 /**
 246  * purple_debug_set_ui_ops:
 247  * @ops: The UI operations structure.
 248  *
 249  * Sets the UI operations structure to be used when outputting debug
 250  * information.
 251  */
 252 void purple_debug_set_ui_ops(PurpleDebugUiOps *ops);
 253
 254 /**
 255  * purple_debug_get_ui_ops:
 256  *
 257  * Returns the UI operations structure used when outputting debug
 258  * information.
 259  *
 260  * Returns: The UI operations structure in use.
 261  */
 262 PurpleDebugUiOps *purple_debug_get_ui_ops(void);
 263
 264 /**************************************************************************/
 265 /* Debug Subsystem                                                        */
 266 /**************************************************************************/
 267
 268 /**
 269  * purple_debug_init:
 270  *
 271  * Initializes the debug subsystem.
 272  */
 273 void purple_debug_init(void);
 274
 275 G_END_DECLS
 276
 277 #endif /* _PURPLE_DEBUG_H_ */