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_ */ 244