1 /*
2     Copyright (C) 2003, 2004, 2008, 2012 Rocky Bernstein <rocky@gnu.org>
3     Copyright (C) 2000 Herbert Valerio Riedel <hvr@gnu.org>
4 
5     This program is free software: you can redistribute it and/or modify
6     it under the terms of the GNU General Public License as published by
7     the Free Software Foundation, either version 3 of the License, or
8     (at your option) any later version.
9 
10     This program is distributed in the hope that it will be useful,
11     but WITHOUT ANY WARRANTY; without even the implied warranty of
12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13     GNU General Public License for more details.
14 
15     You should have received a copy of the GNU General Public License
16     along with this program.  If not, see <http://www.gnu.org/licenses/>.
17 */
18 
19 /** \file logging.h
20  *  \brief Header to control logging and level of detail of output.
21  *
22  */
23 
24 #ifndef CDIO_LOGGING_H_
25 #define CDIO_LOGGING_H_
26 
27 #include <cdio/types.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /**
34  * The different log levels supported.
35  */
36 typedef enum {
37   CDIO_LOG_DEBUG = 1, /**< Debug-level messages - helps debug what's up. */
38   CDIO_LOG_INFO,      /**< Informational - indicates perhaps something of
39                            interest. */
40   CDIO_LOG_WARN,      /**< Warning conditions - something that looks funny. */
41   CDIO_LOG_ERROR,     /**< Error conditions - may terminate program.  */
42   CDIO_LOG_ASSERT     /**< Critical conditions - may abort program. */
43 } cdio_log_level_t;
44 
45 /**
46  * The place to save the preference concerning how much verbosity
47  * is desired. This is used by the internal default log handler, but
48  * it could be use by applications which provide their own log handler.
49  */
50 extern cdio_log_level_t cdio_loglevel_default;
51 
52 /**
53  * This type defines the signature of a log handler.  For every
54  * message being logged, the handler will receive the log level and
55  * the message string.
56  *
57  * @see cdio_log_set_handler
58  * @see cdio_log_level_t
59  *
60  * @param level   The log level.
61  * @param message The log message.
62  */
63 typedef void (*cdio_log_handler_t) (cdio_log_level_t level,
64                                     const char message[]);
65 
66 /**
67  * The initial or default log handler in effect.
68  *
69  * @param level   The log level.
70  * @param message The log message.
71  */
72 extern void cdio_default_log_handler(cdio_log_level_t level, const char message[]);
73 
74 /**
75  * Set a custom log handler for libcdio.  The return value is the log
76  * handler being replaced.  If the provided parameter is NULL, then
77  * the handler will be reset to the default handler.
78  *
79  * @see cdio_log_handler_t
80  *
81  * @param new_handler The new log handler.
82  * @return The previous log handler.
83  */
84 cdio_log_handler_t cdio_log_set_handler (cdio_log_handler_t new_handler);
85 
86 /**
87  * Handle an message with the given log level.
88  *
89  * @see cdio_debug
90  * @see cdio_info
91  * @see cdio_warn
92  * @see cdio_error
93 
94  * @param level   The log level.
95  * @param format  printf-style format string
96  * @param ...     remaining arguments needed by format string
97  */
98 void cdio_log (cdio_log_level_t level,
99                const char format[], ...) GNUC_PRINTF(2, 3);
100 
101 /**
102  * Handle a debugging message.
103  *
104  * @see cdio_log for a more generic routine
105  */
106 void cdio_debug (const char format[], ...) GNUC_PRINTF(1,2);
107 
108 /**
109  * Handle an informative message.
110  *
111  * @see cdio_log for a more generic routine
112  */
113 void cdio_info (const char format[], ...) GNUC_PRINTF(1,2);
114 
115 /**
116  * Handle a warning message.
117  *
118  * @see cdio_log for a more generic routine
119  */
120 void cdio_warn (const char format[], ...) GNUC_PRINTF(1,2);
121 
122 /**
123  * Handle an error message. Execution is terminated.
124  *
125  * @see cdio_log for a more generic routine.
126  */
127 void cdio_error (const char format[], ...) GNUC_PRINTF(1,2);
128 
129 #ifdef __cplusplus
130 }
131 #endif
132 
133 #endif /* CDIO_LOGGING_H_ */
134 
135 
136 /*
137  * Local variables:
138  *  c-file-style: "gnu"
139  *  tab-width: 8
140  *  indent-tabs-mode: nil
141  * End:
142  */
143