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