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 67 extern "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 */ 78 typedef 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 */ 128 typedef 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 */ 154 typedef 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__) 191 int HiLogPrint(LogType type, LogLevel level, unsigned int domain, const char* tag, const char* fmt, ...) 192 __attribute__((format(os_log, 5, 6))); 193 #else 194 int 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