Asterisk - The Open Source Telephony Project  21.4.1
logger_category.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2020, Sangoma Technologies Corporation
5  *
6  * Kevin Harwell <kharwell@sangoma.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 #ifndef ASTERISK_LOGGER_CATEGORY_H
19 #define ASTERISK_LOGGER_CATEGORY_H
20 
21 #include "asterisk/logger.h"
22 
23 /*!
24  * Logger category is enabled
25  */
26 #define AST_LOG_CATEGORY_ENABLED -1
27 
28 /*!
29  * Logger category is disabled
30  */
31 #define AST_LOG_CATEGORY_DISABLED 0
32 
33 /*!
34  * \brief Load/Initialize system wide logger category functionality
35  *
36  * \retval 0 Success
37  * \retval -1 Failure
38  *
39  * \since 16.14
40  * \since 17.8
41  * \since 18.0
42  */
43 int ast_logger_category_load(void);
44 
45 /*!
46  * \brief Unload system wide logger category functionality
47  *
48  * \retval 0 Success
49  * \retval -1 Failure
50  *
51  * \since 16.14
52  * \since 17.8
53  * \since 18.0
54  */
55 int ast_logger_category_unload(void);
56 
57 /*!
58  * \brief Register a debug level logger category
59  *
60  * \param name The name of the category
61  *
62  * \retval 0 if failed to register/retrieve an id
63  * \return id for the registered category
64  *
65  * \since 16.14
66  * \since 17.8
67  * \since 18.0
68  */
69 uintmax_t ast_debug_category_register(const char *name);
70 
71 /*!
72  * \brief Un-register a debug level logger category
73  *
74  * \retval 0 Success
75  * \retval -1 Failure
76  *
77  * \since 16.14
78  * \since 17.8
79  * \since 18.0
80  */
81 int ast_debug_category_unregister(const char *name);
82 
83 /*!
84  * \brief Set the debug category's sublevel
85  *
86  * Statements are output at a specified sublevel. Typically any number greater
87  * than or equal to 0. Other acceptable values include AST_LOG_CATEGORY_ENABLED
88  * and AST_LOG_CATEGORY_DISABLED.
89  *
90  * \param name The name of the category
91  * \param sublevel The debug sublevel output number
92  *
93  * \retval 0 Success
94  * \retval -1 Failure
95  *
96  * \since 16.14
97  * \since 17.8
98  * \since 18.0
99  */
100 int ast_debug_category_set_sublevel(const char *name, int sublevel);
101 
102 /*!
103  * \brief Set one or more debug category's sublevel.
104  *
105  * Accepts an array of category names, and optional associated sublevels. Sublevels can
106  * be associated with a name by using a ':' as a separator. For example:
107  * \verbatim <category name>:<category sublevel> \endverbatim
108  *
109  * The given default sublevel is used if no sublevel is associated with a name.
110  *
111  * \param names An array of category names
112  * \param size The size of the array (number of elements)
113  * \param default_sublevel The sublevel value to use if one is not associated with a name
114  *
115  * \retval 0 Success
116  * \retval -1 Failure
117  *
118  * \since 16.14
119  * \since 17.8
120  * \since 18.0
121  */
122 int ast_debug_category_set_sublevels(const char * const *names, size_t size, int default_sublevel);
123 
124 /*!
125  * \brief Add a unique (no duplicates) result to a request for completion for debug categories.
126  *
127  * \param argv A list of already completed options
128  * \param argc The number of already completed options
129  * \param word The word to complete
130  * \param state The state
131  *
132  * \retval 0 Success
133  * \retval -1 Failure
134  *
135  * \since 16.14
136  * \since 17.8
137  * \since 18.0
138  */
139 char *ast_debug_category_complete(const char * const *argv, int argc, const char *word, int state);
140 
141 /*!
142  * \brief Check if a debug category is enabled, and allowed to output
143  *
144  * \note If more than one id is specified then if even one is allowed "true"
145  * is returned.
146  *
147  * \param sublevel Current set sublevel must be this sublevel or less
148  * \param ids One or more unique category ids to check
149  *
150  * \retval 1 if allowed
151  * \retval 0 if not allowed
152  *
153  * \since 16.14
154  * \since 17.8
155  * \since 18.0
156 */
157 int ast_debug_category_is_allowed(int sublevel, uintmax_t ids);
158 
159 /*!
160  * \brief Log for a debug category.
161  *
162  * This will output log data for debug under the following conditions:
163  *
164  * 1. The specified sublevel is at, or below the current system debug level
165  * 2. At least one of the given category ids is enabled AND
166  * a. The category sublevel is enabled OR the given sublevel is at, or
167  * below a category's specified sublevel.
168  *
169  * \param sublevel The minimum level to output at
170  * \param ids One or more unique category ids to output for
171  *
172  * \since 16.14
173  * \since 17.8
174  * \since 18.0
175  */
176 #define ast_debug_category(sublevel, ids, ...) \
177  do { \
178  if (DEBUG_ATLEAST(sublevel) || ast_debug_category_is_allowed(sublevel, ids)) { \
179  ast_log(AST_LOG_DEBUG, __VA_ARGS__); \
180  } \
181  } while (0)
182 
183 #endif /* ASTERISK_LOGGER_CATEGORY_H */
Support for logging to various files, console and syslog Configuration in file logger.conf.