chan_sip: Use video and text crypto attributes to append RTP profiles to SDP
[asterisk/asterisk.git] / include / asterisk / logger.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*!
20   \file logger.h
21   \brief Support for logging to various files, console and syslog
22         Configuration in file logger.conf
23 */
24
25 #ifndef _ASTERISK_LOGGER_H
26 #define _ASTERISK_LOGGER_H
27
28 #include "asterisk/options.h"   /* need option_debug */
29
30 #if defined(__cplusplus) || defined(c_plusplus)
31 extern "C" {
32 #endif
33
34 #define EVENTLOG "event_log"
35 #define QUEUELOG        "queue_log"
36
37 #define DEBUG_M(a) { \
38         a; \
39 }
40
41 #define VERBOSE_PREFIX_1 " "
42 #define VERBOSE_PREFIX_2 "  == "
43 #define VERBOSE_PREFIX_3 "    -- "
44 #define VERBOSE_PREFIX_4 "       > "
45
46 #define AST_CALLID_BUFFER_LENGTH 13
47
48 /*! \brief Used for sending a log message
49         This is the standard logger function.  Probably the only way you will invoke it would be something like this:
50         ast_log(AST_LOG_WHATEVER, "Problem with the %s Captain.  We should get some more.  Will %d be enough?\n", "flux capacitor", 10);
51         where WHATEVER is one of ERROR, DEBUG, EVENT, NOTICE, or WARNING depending
52         on which log you wish to output to. These are implemented as macros, that
53         will provide the function with the needed arguments.
54
55         \param level    Type of log event
56         \param file     Will be provided by the AST_LOG_* macro
57         \param line     Will be provided by the AST_LOG_* macro
58         \param function Will be provided by the AST_LOG_* macro
59         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
60  */
61
62 void ast_log(int level, const char *file, int line, const char *function, const char *fmt, ...)
63         __attribute__((format(printf, 5, 6)));
64
65 /* XXX needs documentation */
66 struct ast_callid;
67
68 /*! \brief Used for sending a log message with a known call_id
69         This is a modified logger function which is functionally identical to the above logger function,
70         it just include a call_id argument as well. If NULL is specified here, no attempt will be made to
71         join the log message with a call_id.
72
73         \param level    Type of log event
74         \param file     Will be provided by the AST_LOG_* macro
75         \param line     Will be provided by the AST_LOG_* macro
76         \param function Will be provided by the AST_LOG_* macro
77         \param callid   This is the ast_callid that is associated with the log message. May be NULL.
78         \param fmt      This is what is important.  The format is the same as your favorite breed of printf.  You know how that works, right? :-)
79 */
80 void ast_log_callid(int level, const char *file, int line, const char *function, struct ast_callid *callid, const char *fmt, ...)
81         __attribute__((format(printf, 6, 7)));
82
83 void ast_backtrace(void);
84
85 /*! \brief Reload logger without rotating log files */
86 int logger_reload(void);
87
88 void __attribute__((format(printf, 5, 6))) ast_queue_log(const char *queuename, const char *callid, const char *agent, const char *event, const char *fmt, ...);
89
90 /*! Send a verbose message (based on verbose level)
91  *      \brief This works like ast_log, but prints verbose messages to the console depending on verbosity level set.
92  *      ast_verbose(VERBOSE_PREFIX_3 "Whatever %s is happening\n", "nothing");
93  *      This will print the message to the console if the verbose level is set to a level >= 3
94  *      Note the absence of a comma after the VERBOSE_PREFIX_3.  This is important.
95  *      VERBOSE_PREFIX_1 through VERBOSE_PREFIX_4 are defined.
96  *  \version 11 added level parameter
97  */
98 void __attribute__((format(printf, 5, 6))) __ast_verbose(const char *file, int line, const char *func, int level, const char *fmt, ...);
99
100 /*! Send a verbose message (based on verbose level) with deliberately specified callid
101  *  \brief just like __ast_verbose, only __ast_verbose_callid allows you to specify which callid is being used
102  *  for the log without needing to bind it to a thread. NULL is a valid argument for this function and will
103  *  allow you to specify that a log will never display a call id even when there is a call id bound to the
104  *  thread.
105  */
106 void __attribute__((format(printf, 6, 7))) __ast_verbose_callid(const char *file, int line, const char *func, int level, struct ast_callid *callid, const char *fmt, ...);
107
108 #define ast_verbose(...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, __VA_ARGS__)
109 #define ast_verbose_callid(callid, ...) __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, -1, callid, __VA_ARGS__)
110
111 void __attribute__((format(printf, 6, 0))) __ast_verbose_ap(const char *file, int line, const char *func, int level, struct ast_callid *callid, const char *fmt, va_list ap);
112
113 void __attribute__((format(printf, 2, 3))) ast_child_verbose(int level, const char *fmt, ...);
114
115 int ast_register_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
116 int ast_unregister_verbose(void (*verboser)(const char *string)) attribute_warn_unused_result;
117
118 void ast_console_puts(const char *string);
119
120 /*!
121  * \brief log the string to the console, and all attached
122  * console clients
123  * \version 1.6.1 added level parameter
124  */
125 void ast_console_puts_mutable(const char *string, int level);
126 void ast_console_toggle_mute(int fd, int silent);
127
128 /*!
129  * \brief enables or disables logging of a specified level to the console
130  * fd specifies the index of the console receiving the level change
131  * level specifies the index of the logging level being toggled
132  * state indicates whether logging will be on or off (0 for off, 1 for on)
133  */
134 void ast_console_toggle_loglevel(int fd, int level, int state);
135
136 /* Note: The AST_LOG_* macros below are the same as
137  * the LOG_* macros and are intended to eventually replace
138  * the LOG_* macros to avoid name collisions with the syslog(3)
139  * log levels. However, please do NOT remove
140  * the LOG_* macros from the source since these may be still
141  * needed for third-party modules
142  */
143
144 #define _A_ __FILE__, __LINE__, __PRETTY_FUNCTION__
145
146 #ifdef LOG_DEBUG
147 #undef LOG_DEBUG
148 #endif
149 #define __LOG_DEBUG    0
150 #define LOG_DEBUG      __LOG_DEBUG, _A_
151
152 #ifdef AST_LOG_DEBUG
153 #undef AST_LOG_DEBUG
154 #endif
155 #define AST_LOG_DEBUG      __LOG_DEBUG, _A_
156
157 #ifdef LOG_NOTICE
158 #undef LOG_NOTICE
159 #endif
160 #define __LOG_NOTICE   2
161 #define LOG_NOTICE     __LOG_NOTICE, _A_
162
163 #ifdef AST_LOG_NOTICE
164 #undef AST_LOG_NOTICE
165 #endif
166 #define AST_LOG_NOTICE     __LOG_NOTICE, _A_
167
168 #ifdef LOG_WARNING
169 #undef LOG_WARNING
170 #endif
171 #define __LOG_WARNING  3
172 #define LOG_WARNING    __LOG_WARNING, _A_
173
174 #ifdef AST_LOG_WARNING
175 #undef AST_LOG_WARNING
176 #endif
177 #define AST_LOG_WARNING    __LOG_WARNING, _A_
178
179 #ifdef LOG_ERROR
180 #undef LOG_ERROR
181 #endif
182 #define __LOG_ERROR    4
183 #define LOG_ERROR      __LOG_ERROR, _A_
184
185 #ifdef AST_LOG_ERROR
186 #undef AST_LOG_ERROR
187 #endif
188 #define AST_LOG_ERROR      __LOG_ERROR, _A_
189
190 #ifdef LOG_VERBOSE
191 #undef LOG_VERBOSE
192 #endif
193 #define __LOG_VERBOSE  5
194 #define LOG_VERBOSE    __LOG_VERBOSE, _A_
195
196 #ifdef AST_LOG_VERBOSE
197 #undef AST_LOG_VERBOSE
198 #endif
199 #define AST_LOG_VERBOSE    __LOG_VERBOSE, _A_
200
201 #ifdef LOG_DTMF
202 #undef LOG_DTMF
203 #endif
204 #define __LOG_DTMF  6
205 #define LOG_DTMF    __LOG_DTMF, _A_
206
207 #ifdef AST_LOG_DTMF
208 #undef AST_LOG_DTMF
209 #endif
210 #define AST_LOG_DTMF    __LOG_DTMF, _A_
211
212 #define NUMLOGLEVELS 32
213
214 /*!
215  * \brief Get the debug level for a module
216  * \param module the name of module
217  * \return the debug level
218  */
219 unsigned int ast_debug_get_by_module(const char *module);
220
221 /*!
222  * \brief Get the verbose level for a module
223  * \param module the name of module
224  * \return the verbose level
225  */
226 unsigned int ast_verbose_get_by_module(const char *module);
227
228 /*!
229  * \brief Register a new logger level
230  * \param name The name of the level to be registered
231  * \retval -1 if an error occurs
232  * \retval non-zero level to be used with ast_log for sending messages to this level
233  * \since 1.8
234  */
235 int ast_logger_register_level(const char *name);
236
237 /*!
238  * \brief Unregister a previously registered logger level
239  * \param name The name of the level to be unregistered
240  * \return nothing
241  * \since 1.8
242  */
243 void ast_logger_unregister_level(const char *name);
244
245 /*!
246  * \brief factory function to create a new uniquely identifying callid.
247  *
248  * \retval ast_callid struct pointer containing the call id
249  *
250  * \note The newly created callid will be referenced upon creation and this function should be
251  * paired with a call to ast_callid_unref()
252  */
253 struct ast_callid *ast_create_callid(void);
254
255 /*!
256  * \brief extracts the callerid from the thread
257  *
258  * \retval ast_callid reference to call_id related to the thread
259  * \retval NULL if no call_id is present in the thread
260  *
261  * This reference must be unreffed before it loses scope to prevent memory leaks.
262  */
263 struct ast_callid *ast_read_threadstorage_callid(void);
264
265 /*!
266  * \brief Increase callid reference count
267  *
268  * \param c the ast_callid
269  *
270  * \retval c always
271  */
272 #define ast_callid_ref(c) ({ ao2_ref(c, +1); (c); })
273
274 /*!
275  * \brief Decrease callid reference count
276  *
277  * \param c the ast_callid
278  *
279  * \retval NULL always
280  */
281 #define ast_callid_unref(c) ({ ao2_ref(c, -1); (NULL); })
282
283 /*!
284  * \brief Adds a known callid to thread storage of the calling thread
285  *
286  * \retval 0 - success
287  * \retval non-zero - failure
288  */
289 int ast_callid_threadassoc_add(struct ast_callid *callid);
290
291 /*!
292  * \brief Removes callid from thread storage of the calling thread
293  *
294  * \retval 0 - success
295  * \retval non-zero - failure
296  */
297 int ast_callid_threadassoc_remove(void);
298
299 /*!
300  * \brief Checks thread storage for a callid and stores a reference if it exists.
301  *        If not, then a new one will be created, bound to the thread, and a reference
302  *        to it will be stored.
303  *
304  * \param callid pointer to struct pointer used to store the referenced callid
305  * \retval 0 - callid was found
306  * \retval 1 - callid was created
307  * \retval -1 - the function failed somehow (presumably memory problems)
308  */
309 int ast_callid_threadstorage_auto(struct ast_callid **callid);
310
311 /*!
312  * \brief Use in conjunction with ast_callid_threadstorage_auto. Cleans up the
313  *        references and if the callid was created by threadstorage_auto, unbinds
314  *        the callid from the threadstorage
315  * \param callid The callid set by ast_callid_threadstorage_auto
316  * \param callid_created The integer returned through ast_callid_threadstorage_auto
317  */
318 void ast_callid_threadstorage_auto_clean(struct ast_callid *callid, int callid_created);
319
320 /*!
321  * \brief copy a string representation of the callid into a target string
322  *
323  * \param buffer destination of callid string (should be able to store 13 characters or more)
324  * \param buffer_size maximum writable length of the string (Less than 13 will result in truncation)
325  * \param callid Callid for which string is being requested
326  */
327 void ast_callid_strnprint(char *buffer, size_t buffer_size, struct ast_callid *callid);
328
329 /*!
330  * \brief Send a log message to a dynamically registered log level
331  * \param level The log level to send the message to
332  *
333  * Like ast_log, the log message may include printf-style formats, and
334  * the data for these must be provided as additional parameters after
335  * the log message.
336  *
337  * \return nothing
338  * \since 1.8
339  */
340
341 #define ast_log_dynamic_level(level, ...) ast_log(level, __FILE__, __LINE__, __PRETTY_FUNCTION__, __VA_ARGS__)
342
343 /*!
344  * \brief Log a DEBUG message
345  * \param level The minimum value of option_debug for this message
346  *        to get logged
347  */
348 #define ast_debug(level, ...) do {       \
349         if (option_debug >= (level) || (ast_opt_dbg_module && ast_debug_get_by_module(AST_MODULE) >= (level)) ) \
350                 ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
351 } while (0)
352
353 #define ast_verb(level, ...) __ast_verbose(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, __VA_ARGS__)
354 #define ast_verb_callid(level, callid, ...) __ast_verbose_callid(__FILE__, __LINE__, __PRETTY_FUNCTION__, level, callid, __VA_ARGS__)
355
356 #ifndef _LOGGER_BACKTRACE_H
357 #define _LOGGER_BACKTRACE_H
358 #ifdef HAVE_BKTR
359 #define AST_MAX_BT_FRAMES 32
360 /* \brief
361  *
362  * A structure to hold backtrace information. This structure provides an easy means to
363  * store backtrace information or pass backtraces to other functions.
364  */
365 struct ast_bt {
366         /*! The addresses of the stack frames. This is filled in by calling the glibc backtrace() function */
367         void *addresses[AST_MAX_BT_FRAMES];
368         /*! The number of stack frames in the backtrace */
369         int num_frames;
370         /*! Tells if the ast_bt structure was dynamically allocated */
371         unsigned int alloced:1;
372 };
373
374 /* \brief
375  * Allocates memory for an ast_bt and stores addresses and symbols.
376  *
377  * \return Returns NULL on failure, or the allocated ast_bt on success
378  * \since 1.6.1
379  */
380 struct ast_bt *ast_bt_create(void);
381
382 /* \brief
383  * Fill an allocated ast_bt with addresses
384  *
385  * \retval 0 Success
386  * \retval -1 Failure
387  * \since 1.6.1
388  */
389 int ast_bt_get_addresses(struct ast_bt *bt);
390
391 /* \brief
392  *
393  * Free dynamically allocated portions of an ast_bt
394  *
395  * \retval NULL.
396  * \since 1.6.1
397  */
398 void *ast_bt_destroy(struct ast_bt *bt);
399
400 /* \brief Retrieve symbols for a set of backtrace addresses
401  *
402  * \param addresses A list of addresses, such as the ->addresses structure element of struct ast_bt.
403  * \param num_frames Number of addresses in the addresses list
404  * \retval NULL Unable to allocate memory
405  * \return List of strings
406  * \since 1.6.2.16
407  */
408 char **ast_bt_get_symbols(void **addresses, size_t num_frames);
409
410 #endif /* HAVE_BKTR */
411 #endif /* _LOGGER_BACKTRACE_H */
412
413 #if defined(__cplusplus) || defined(c_plusplus)
414 }
415 #endif
416
417 #endif /* _ASTERISK_LOGGER_H */