1/*
2 * Copyright (c) 2020 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef HOS_LITE_HIVIEW_LOG_H
17#define HOS_LITE_HIVIEW_LOG_H
18/**
19 * @addtogroup HiLog
20 * @{
21 *
22 * @brief Provides logging functions.
23 *
24 * For example, you can use these functions to output logs of the specified log type, service domain, log tag,
25 * and log level.
26 *
27 * @since 1.1
28 * @version 1.0
29 */
30
31/**
32 * @file hilog/log.h
33 *
34 * @brief Defines the logging functions of the HiLog module.
35 *
36 * Before outputting logs, you must define the service domain, and log tag, use the function with
37 * the specified log type and level, and specify the privacy identifier.\n
38 * <ul><li>Service domain: used to identify the subsystem and module of a service. Its value is a hexadecimal
39 * integer ranging from 0x0 to 0xFFFFF. The recommended format is 0xAAABB, where AAA indicates the subsystem
40 * and BB indicates the module.</li> \n
41 * <li>Log tag: a string used to identify the class, file, or service behavior.</li> \n
42 * <li>Log level: <b>DEBUG</b>, <b>INFO</b>, <b>WARN</b>, <b>ERROR</b>, and <b>FATAL</b></li> \n
43 * <li>Parameter format: a printf format string that starts with a % character, including format specifiers
44 * and variable parameters.</li> \n
45 * <li>Privacy identifier: {public} or {private} added between the % character and the format specifier in
46 * each parameter. Note that each parameter has a privacy identifier. If no privacy identifier is added,
47 * the parameter is considered to be <b>private</b>.</li></ul> \n
48 *
49 * Sample code:\n
50 * Defining the service domain and log tag:\n
51 * #define LOG_DOMAIN MY_SUBSYSTEM_MODULE // MY_SUBSYSTEM_MODULE=0x00201, where 002 indicates the subsystem and
52 * 01 indicates the module.\n
53 *     #define LOG_TAG "MY_TAG"\n
54 * Outputting logs:\n
55 *     HILOG_WARN({@link LOG_APP}, "Failed to visit %{private}s, reason:%{public}d.", url, errno);\n
56 * Output result:\n
57 *     05-06 15:01:06.870 1051 1051 W 00201/MY_TAG: Failed to visit <private>, reason:503.\n
58 *
59 * @since 1.1
60 * @version 1.0
61 */
62
63#include <stdarg.h>
64#include <stdio.h>
65
66#ifdef __cplusplus
67extern "C" {
68#endif
69
70/**
71 * @brief Enumerates logging module types.
72 *
73 * The module type must be globally unique. A maximum of 64 module types can be defined.
74 *
75 * @since 1.0
76 * @version 1.0
77 */
78typedef enum {
79    /** DFX */
80    HILOG_MODULE_HIVIEW = 0,
81    /** System Ability Manager */
82    HILOG_MODULE_SAMGR,
83    /** Update */
84    HILOG_MODULE_ACE,
85    /** GRAPHIC*/
86    HILOG_MODULE_GRAPHIC,
87    /** Third-party applications */
88    HILOG_MODULE_APP,
89    /** Maximum number of modules */
90    HILOG_MODULE_MAX
91} HiLogModuleType;
92
93/**
94 * @brief Defines the service domain for a log file.
95 *
96 * The service domain is used to identify the subsystem and module of a service. Its value is a hexadecimal integer
97 * ranging from 0x0 to 0xFFFFF. If the value is beyond the range, its significant bits are automatically truncated. \n
98 * The recommended format is 0xAAABB, where AAA indicates the subsystem and BB indicates the module. \n
99 *
100 * @since 1.1
101 * @version 1.0
102 */
103#ifndef LOG_DOMAIN
104#define LOG_DOMAIN 0
105#endif
106
107/**
108 * @brief Defines a string constant used to identify the class, file, or service behavior.
109 *
110 * @since 1.1
111 * @version 1.0
112 */
113#ifndef LOG_TAG
114#define LOG_TAG NULL
115#endif
116
117#define DOMAIN_LENGTH 5
118#define DOMAIN_FILTER 0x000FFFFF
119
120/**
121 * @brief Enumerates log types.
122 *
123 * Currently, <b>LOG_APP</b> is available. \n
124 *
125 * @since 1.1
126 * @version 1.0
127 */
128typedef enum {
129    LOG_TYPE_MIN = 0,
130    // Log to kmsg, only used by init phase.
131    LOG_INIT = 1,
132    // Used by core service, framework.
133    LOG_CORE = 3,
134    LOG_TYPE_MAX
135} LogType;
136
137/**
138 * @brief Enumerates log levels.
139 *
140 * You are advised to select log levels based on their respective usage scenarios:\n
141 * <ul><li><b>DEBUG</b>: used for debugging and disabled from commercial releases</li> \n
142 * <li><b>INFO</b>: used for logging important system running status and steps in key processes</li> \n
143 * <li><b>WARN</b>: used for logging unexpected exceptions that have little impact on user experience and can
144 * automatically recover. Logs at this level are generally output when such exceptions are detected and
145 * captured.</li> \n
146 * <li><b>ERROR</b>: used for logging malfunction that affects user experience and cannot automatically
147 * recover</li>\n
148 * <li><b>FATAL</b>: used for logging major exceptions that have severely affected user experience and should
149 * not occur.</li></ul> \n
150 *
151 * @since 1.1
152 * @version 1.0
153 */
154typedef enum {
155    /** Debug level to be used by {@link HILOG_DEBUG} */
156    LOG_DEBUG = 3,
157    /** Informational level to be used by {@link HILOG_INFO} */
158    LOG_INFO = 4,
159    /** Warning level to be used by {@link HILOG_WARN} */
160    LOG_WARN = 5,
161    /** Error level to be used by {@link HILOG_ERROR} */
162    LOG_ERROR = 6,
163    /** Fatal level to be used by {@link HILOG_FATAL} */
164    LOG_FATAL = 7,
165} LogLevel;
166
167#define HILOG_LEVEL_MAX (LOG_FATAL + 1)
168/**
169 * @brief Outputs logs.
170 *
171 * You can use this function to output logs based on the specified log type, log level, service domain, log tag,
172 * and variable parameters determined by the format specifier and privacy identifier in the printf format.
173 *
174 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}.
175 * @param level Indicates the log level, which can be <b>LOG_DEBUG</b>, <b>LOG_INFO</b>, <b>LOG_WARN</b>,
176 * <b>LOG_ERROR</b>, and <b>LOG_FATAL</b>.
177 * @param domain Indicates the service domain of logs. Its value is a hexadecimal integer ranging from 0x0 to 0xFFFFF.
178 * The recommended format is 0xAAABB, where AAA indicates the subsystem and BB indicates the module.
179 * @param tag Indicates the log tag, which is a string used to identify the class, file, or service behavior.
180 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy
181 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier
182 * in each parameter. \n
183 * @param... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers
184 * in the format string.
185 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller
186 * than <b>0</b> otherwise.
187 * @since 1.1
188 * @version 1.0
189 */
190#if defined(__clang__)
191int HiLogPrint(LogType type, LogLevel level, unsigned int domain, const char* tag, const char* fmt, ...)
192    __attribute__((format(os_log, 5, 6)));
193#else
194int HiLogPrint(LogType type, LogLevel level, unsigned int domain, const char* tag, const char* fmt, ...)
195    __attribute__((format(printf, 5, 6)));
196#endif
197
198/**
199 * @brief Outputs debug logs. This is a function-like macro.
200 *
201 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at
202 * the beginning of the source file. \n
203 *
204 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}.
205 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the
206 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier
207 * in each parameter. \n
208 * @param... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers
209 * in the format string.
210 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller than <b>0</b>
211 * otherwise.
212 * @see HiLogPrint
213 * @since 1.1
214 * @version 1.0
215 */
216#define HILOG_DEBUG(type, ...) ((void)HiLogPrint(LOG_CORE, LOG_DEBUG, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
217
218/**
219 * @brief Outputs informational logs. This is a function-like macro.
220 *
221 * Before calling this function, define the log service domain and log tag. Generally, you need to define them
222 * at the beginning of the source file. \n
223 *
224 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}.
225 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy
226 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in
227 * each parameter. \n
228 * @param... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers
229 * in the format string.
230 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller than
231 * <b>0</b> otherwise.
232 * @see HiLogPrint
233 * @since 1.1
234 * @version 1.0
235 */
236#define HILOG_INFO(type, ...) ((void)HiLogPrint(LOG_CORE, LOG_INFO, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
237
238/**
239 * @brief Outputs warning logs. This is a function-like macro.
240 *
241 * Before calling this function, define the log service domain and log tag. Generally, you need to define them
242 * at the beginning of the source file. \n
243 *
244 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}.
245 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the
246 * privacy identifier. Specifically, {public} or {private} is added between the % character and the format specifier
247 * in each parameter. \n
248 * @param... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers
249 * in the format string.
250 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller than
251 * <b>0</b> otherwise.
252 * @see HiLogPrint
253 * @since 1.1
254 * @version 1.0
255 */
256#define HILOG_WARN(type, ...) ((void)HiLogPrint(LOG_CORE, LOG_WARN, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
257
258/**
259 * @brief Outputs error logs. This is a function-like macro.
260 *
261 * Before calling this function, define the log service domain and log tag. Generally, you need to define
262 * them at the beginning of the source file. \n
263 *
264 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}.
265 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy
266 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in each
267 * parameter. \n
268 * @param... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers
269 * in the format string.
270 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller than
271 * <b>0</b> otherwise.
272 * @see HiLogPrint
273 * @since 1.1
274 * @version 1.0
275 */
276#define HILOG_ERROR(type, ...) ((void)HiLogPrint(LOG_CORE, LOG_ERROR, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
277
278/**
279 * @brief Outputs fatal logs. This is a function-like macro.
280 *
281 * Before calling this function, define the log service domain and log tag. Generally, you need to define them at
282 * the beginning of the source file. \n
283 *
284 * @param type Indicates the log type. The type for third-party applications is defined by {@link LOG_APP}.
285 * @param fmt Indicates the format string, which is an enhancement of a printf format string and supports the privacy
286 * identifier. Specifically, {public} or {private} is added between the % character and the format specifier in
287 * each parameter. \n
288 * @param... Indicates a list of parameters. The number and type of parameters must map onto the format specifiers
289 * in the format string.
290 * @return Returns <b>0</b> or a larger value if the operation is successful; returns a value smaller than
291 * <b>0</b> otherwise.
292 * @see HiLogPrint
293 * @since 1.1
294 * @version 1.0
295 */
296#define HILOG_FATAL(type, ...) ((void)HiLogPrint(LOG_CORE, LOG_FATAL, LOG_DOMAIN, LOG_TAG, __VA_ARGS__))
297
298#ifdef __cplusplus
299}
300#endif
301/** @} */
302#endif  // HOS_LITE_HIVIEW_LOG_H
303