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