The QLoggingCategory class represents a category, or 'area' in the logging infrastructure. 更多...
| 头： | #include <QLoggingCategory> |
| qmake: | QT += core |
| Since: | Qt 5.2 |
注意： 此类的所有函数 thread-safe .
| typedef | CategoryFilter |
| QLoggingCategory (const char * category ) | |
| QLoggingCategory (const char * category , QtMsgType enableForLevel ) | |
| ~QLoggingCategory () | |
| const char * | categoryName () const |
| bool | isCriticalEnabled () const |
| bool | isDebugEnabled () const |
| bool | isEnabled (QtMsgType msgtype ) const |
| bool | isInfoEnabled () const |
| bool | isWarningEnabled () const |
| void | setEnabled (QtMsgType type , bool enable ) |
| QLoggingCategory & | operator() () |
| const QLoggingCategory & | operator() () const |
| QLoggingCategory * | defaultCategory () |
| CategoryFilter | installFilter (CategoryFilter filter ) |
| void | setFilterRules (const QString & rules ) |
| Q_DECLARE_LOGGING_CATEGORY ( name ) | |
| Q_LOGGING_CATEGORY ( name , string ) | |
| Q_LOGGING_CATEGORY ( name , string , msgType ) | |
| qCCritical ( category ) | |
| qCCritical ( category , const char * message , ... ) | |
| qCDebug ( category ) | |
| qCDebug ( category , const char * message , ... ) | |
| qCInfo ( category ) | |
| qCInfo ( category , const char * message , ... ) | |
| qCWarning ( category ) | |
| qCWarning ( category , const char * message , ... ) |
The QLoggingCategory class represents a category, or 'area' in the logging infrastructure.
QLoggingCategory represents a certain logging category - identified by a string - at runtime. A category can be configured to enable or disable logging of messages per message type. Whether a message type is enabled or not can be checked with the isDebugEnabled (), isInfoEnabled (), isWarningEnabled ()，和 isCriticalEnabled () 方法。
All objects are meant to be configured by a common registry (see also 配置类别 ). Different objects can also represent the same category. It is therefore not recommended to export objects across module boundaries, nor to manipulate the objects directly, nor to inherit from QLoggingCategory .
The Q_DECLARE_LOGGING_CATEGORY () 和 Q_LOGGING_CATEGORY () macros conveniently declare and create QLoggingCategory 对象：
// in a header Q_DECLARE_LOGGING_CATEGORY(driverUsb) // in one source file Q_LOGGING_CATEGORY(driverUsb, "driver.usb")
注意： Category names are free text. However, to allow easy configuration of the categories using 日志规则 the names should follow some rules:
debug
,
info
,
warning
，和
critical
.
qt
are reserved for Qt modules.
QLoggingCategory objects implicitly defined by Q_LOGGING_CATEGORY () are created on first use in a thread-safe manner.
QLoggingCategory 提供 isDebugEnabled (), isInfoEnabled (), isWarningEnabled (), isCriticalEnabled (), as well as isEnabled () to check whether messages for the given message type should be logged.
注意： The qCDebug (), qCWarning (), qCCritical () macros prevent arguments from being evaluated if the respective message types are not enabled for the category, so explicit checking is not needed:
// usbEntries() will only be called if driverUsb category is enabled
qCDebug(driverUsb) << "devices: " << usbEntries();
两者 QLoggingCategory constructor and the Q_LOGGING_CATEGORY () macro accept an optional QtMsgType argument, which disables all message types with a lower severity. That is, a category declared with
Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)
will log messages of type
QtWarningMsg
,
QtCriticalMsg
,
QtFatalMsg
, but will ignore messages of type
QtDebugMsg
and
QtInfoMsg
.
If no argument is passed, all messages will be logged.
The default configuration of categories can be overridden either by setting logging rules, or by installing a custom filter.
Logging rules allow logging for categories to be enabled or disabled in a flexible way. Rules are specified in text, where every line must have the format
<category>[.<type>] = true|false
<category>
is the name of the category, potentially with
*
as a wildcard symbol as the first or last character (or at both positions). The optional
<type>
must be either
debug
,
info
,
warning
，或
critical
. Lines that do not fit this scheme are ignored.
Rules are evaluated in text order, from first to last. That is, if two rules apply to a category/type, the rule that comes later is applied.
Rules can be set via
setFilterRules
(). Since Qt 5.3, logging rules can also be set in the
QT_LOGGING_RULES
environment variable, and are automatically loaded from the
[Rules]
section of a logging configuration file. Such configuration files are looked up in the QtProject configuration directory, or explicitly set in a
QT_LOGGING_CONF
environment variable:
[Rules] *.debug=false driver.usb.debug=true
Rules set by
setFilterRules
() take precedence over rules specified in the QtProject configuration directory, and can, in turn, be overwritten by rules from the configuration file specified by
QT_LOGGING_CONF
, and rules set by
QT_LOGGING_RULES
.
Since Qt 5.6,
QT_LOGGING_RULES
may contain multiple rules separated by semicolons:
QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"
Order of evaluation:
QT_LOGGING_CONF
QT_LOGGING_RULES
The
QtProject/qtlogging.ini
file is looked up in all directories returned by
QStandardPaths::GenericConfigLocation
，如
~/Library/Preferences
~/.config
,
/etc/xdg
%LOCALAPPDATA%
,
%ProgramData%
,
QCoreApplication::applicationDirPath
(),
QCoreApplication::applicationDirPath
() +
"/data"
设置
QT_LOGGING_DEBUG
environment variable to see from where logging rules are loaded.
As a lower-level alternative to the text rules, you can also implement a custom filter via installFilter (). All filter rules are ignored in this case.
使用
%{category}
placeholder to print the category in the default message handler:
qSetMessagePattern("%{category} %{message}");
这是采用以下签名的函数指针的 typedef：
void myCategoryFilter(QLoggingCategory *);
A function with this signature can be installed with installFilter ().
构造 QLoggingCategory object with the provided category name. All message types for this category are enabled by default.
若
category
is
0
, the category name is changed to
"default"
.
构造 QLoggingCategory object with the provided category name, and enables all messages with types more severe or equal than enableForLevel .
若
category
is
0
, the category name is changed to
"default"
.
该函数在 Qt 5.4 引入。
销毁 QLoggingCategory 对象。
Returns the name of the category.
[static]
QLoggingCategory
*QLoggingCategory::
defaultCategory
()
Returns a pointer to the global category
"default"
that is used e.g. by
qDebug
(),
qInfo
(),
qWarning
(),
qCritical
(),
qFatal
().
注意： The returned pointer may be null during destruction of static objects.
注意：
Ownership of the category is not transferred, do not
delete
the returned pointer.
[static]
CategoryFilter
QLoggingCategory::
installFilter
(
CategoryFilter
filter
)
Installs a function filter that is used to determine which categories and message types should be enabled. Returns a pointer to the previous installed filter.
Every QLoggingCategory object created is passed to the filter, and the filter is free to change the respective category configuration with setEnabled ().
The filter might be called from different threads, but never concurrently. The filter shall not call any static functions of QLoggingCategory .
范例：
QLoggingCategory::CategoryFilter oldCategoryFilter; void myCategoryFilter(QLoggingCategory *category) { // configure driver.usb category here, otherwise forward to to default filter. if (qstrcmp(category->categoryName(), "driver.usb") == 0) category->setEnabled(QtDebugMsg, true); else oldCategoryFilter(category); }
An alternative way of configuring the default filter is via setFilterRules ().
返回
true
if critical messages should be shown for this category. Returns
false
否则。
注意： The qCCritical () macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.
返回
true
if debug messages should be shown for this category. Returns
false
否则。
注意： The qCDebug () macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.
返回
true
if a message of type
msgtype
for the category should be shown. Returns
false
否则。
返回
true
if informational messages should be shown for this category. Returns
false
否则。
注意： The qCInfo () macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.
该函数在 Qt 5.5 引入。
返回
true
if warning messages should be shown for this category. Returns
false
否则。
注意： The qCWarning () macro already does this check before executing any code. However, calling this method may be useful to avoid expensive generation of data that is only used for debug output.
Changes the message type type for the category to enable .
This method is meant to be used only from inside a filter installed by installFilter ()。见 配置类别 for an overview on how to configure categories globally.
注意：
QtFatalMsg
cannot be changed. It will always remain
true
.
另请参阅 isEnabled ().
[static]
void
QLoggingCategory::
setFilterRules
(const
QString
&
rules
)
Configures which categories and message types should be enabled through a a set of rules .
范例：
QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));
注意：
The rules might be ignored if a custom category filter is installed with
installFilter
(), or if the user defined
QT_LOGGING_CONF
or
QT_LOGGING_RULES
环境变量。
Returns the object itself. This allows both a QLoggingCategory variable, and a factory method returning a QLoggingCategory , to be used in qCDebug (), qCWarning (), qCCritical () 宏。
Returns the object itself. This allows both a QLoggingCategory variable, and a factory method returning a QLoggingCategory , to be used in qCDebug (), qCWarning (), qCCritical () 宏。
Declares a logging category name . The macro can be used to declare a common logging category shared in different parts of the program.
This macro must be used outside of a class or method.
该函数在 Qt 5.2 引入。
另请参阅 Q_LOGGING_CATEGORY ().
Defines a logging category name , and makes it configurable under the string identifier. By default, all message types are enabled.
Only one translation unit in a library or executable can define a category with a specific name. The implicitly defined QLoggingCategory object is created on first use, in a thread-safe manner.
This macro must be used outside of a class or method.
该函数在 Qt 5.2 引入。
另请参阅 Q_DECLARE_LOGGING_CATEGORY ().
Defines a logging category name , and makes it configurable under the string identifier. By default, messages of QtMsgType msgType and more severe are enabled, types with a lower severity are disabled.
Only one translation unit in a library or executable can define a category with a specific name. The implicitly defined QLoggingCategory object is created on first use, in a thread-safe manner.
This macro must be used outside of a class or method. It is only defined if variadic macros are supported.
该函数在 Qt 5.4 引入。
另请参阅 Q_DECLARE_LOGGING_CATEGORY ().
Returns an output stream for critical messages in the logging category category .
The macro expands to code that checks whether
QLoggingCategory::isCriticalEnabled
() evaluates to
true
. If so, the stream arguments are processed and sent to the message handler.
范例：
QLoggingCategory category("driver.usb");
qCCritical(category) << "a critical message";
注意： Arguments are not processed if critical output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.2 引入。
另请参阅 qCritical ().
Logs a critical message message in the logging category category . message might contain place holders that are replaced by additional arguments, similar to the C printf() function.
范例：
QLoggingCategory category("driver.usb");
qCCritical(category, "a critical message logged into category %s", category.categoryName());
注意： Arguments might not be processed if critical output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.3 引入。
另请参阅 qCritical ().
Returns an output stream for debug messages in the logging category category .
The macro expands to code that checks whether
QLoggingCategory::isDebugEnabled
() evaluates to
true
. If so, the stream arguments are processed and sent to the message handler.
范例：
QLoggingCategory category("driver.usb");
qCDebug(category) << "a debug message";
注意： Arguments are not processed if debug output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.2 引入。
另请参阅 qDebug ().
Logs a debug message message in the logging category category . message might contain place holders that are replaced by additional arguments, similar to the C printf() function.
范例：
QLoggingCategory category("driver.usb");
qCDebug(category, "a debug message logged into category %s", category.categoryName());
注意： Arguments might not be processed if debug output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.3 引入。
另请参阅 qDebug ().
Returns an output stream for informational messages in the logging category category .
The macro expands to code that checks whether
QLoggingCategory::isInfoEnabled
() evaluates to
true
. If so, the stream arguments are processed and sent to the message handler.
范例：
QLoggingCategory category("driver.usb");
qCInfo(category) << "an informational message";
注意： Arguments are not processed if debug output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.5 引入。
另请参阅 qInfo ().
Logs an informational message message in the logging category category . message might contain place holders that are replaced by additional arguments, similar to the C printf() function.
范例：
QLoggingCategory category("driver.usb");
qCInfo(category, "an informational message logged into category %s", category.categoryName());
注意： Arguments might not be processed if debug output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.5 引入。
另请参阅 qInfo ().
Returns an output stream for warning messages in the logging category category .
The macro expands to code that checks whether
QLoggingCategory::isWarningEnabled
() evaluates to
true
. If so, the stream arguments are processed and sent to the message handler.
范例：
QLoggingCategory category("driver.usb");
qCWarning(category) << "a warning message";
注意： Arguments are not processed if warning output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.2 引入。
另请参阅 qWarning ().
Logs a warning message message in the logging category category . message might contain place holders that are replaced by additional arguments, similar to the C printf() function.
范例：
QLoggingCategory category("driver.usb");
qCWarning(category, "a warning message logged into category %s", category.categoryName());
注意： Arguments might not be processed if warning output for the category is not enabled, so do not rely on any side effects.
注意： Using the macro is thread-safe.
注意： 此函数是 thread-safe .
该函数在 Qt 5.3 引入。
另请参阅 qWarning ().