QLoggingCategory 类

QLoggingCategory 类表示日志基础设施类别或区域。更多...

头：	#include <QLoggingCategory>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core

所有成员列表，包括继承成员

注意： 此类的所有函数 thread-safe .

公共类型

CategoryFilter

公共函数

	QLoggingCategory (const char * category , QtMsgType enableForLevel = QtDebugMsg)
	~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 ()
QLoggingCategory::CategoryFilter	installFilter (QLoggingCategory::CategoryFilter filter )
void	setFilterRules (const QString & rules )

宏

`(从 6.5 起)`	Q_DECLARE_EXPORTED_LOGGING_CATEGORY ( name , EXPORT_MACRO )
	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 , ...)
`(从 6.5 起)`	qCFatal ( category )
`(从 6.5 起)`	qCFatal ( category , const char * message , ...)
	qCInfo ( category )
	qCInfo ( category , const char * message , ...)
	qCWarning ( category )
	qCWarning ( category , const char * message , ...)

详细描述

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. An exception are fatal messages, which are always enabled.

To check whether a message type is enabled or not, use one of these methods: isDebugEnabled (), isInfoEnabled (), isWarningEnabled ()，和 isCriticalEnabled ().

All objects are meant to be configured by a common registry, as described in 配置类别 . Different objects can also represent the same category. Therefore, it's not recommended to export objects across module boundaries, to manipulate the objects directly, or to inherit from QLoggingCategory.

创建类别对象

The Q_DECLARE_LOGGING_CATEGORY () 和 Q_LOGGING_CATEGORY () macros conveniently declare and create QLoggingCategory objects:

// in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)
// in one source file
Q_LOGGING_CATEGORY(driverUsb, "driver.usb")

There is also the Q_DECLARE_EXPORTED_LOGGING_CATEGORY () macro in order to use a logging category across library boundaries.

Category names are free text; to configure categories using 日志规则 , their names should follow this convention:

Use letters and numbers only.
Use dots to further structure categories into common areas.
Avoid the category names: debug , info , warning ，和 critical .
Category names with the qt prefix are solely reserved for Qt modules.

QLoggingCategory objects that are implicitly defined by Q_LOGGING_CATEGORY () are created on first use, in a thread-safe manner.

校验类别配置

QLoggingCategory provides 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();

默认类别配置

Both the 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)

logs messages of type QtWarningMsg , QtCriticalMsg , QtFatalMsg , but ignores messages of type QtDebugMsg and QtInfoMsg .

If no argument is passed, all messages are logged. Only Qt internal categories which start with qt are handled differently: For these, only messages of type QtInfoMsg , QtWarningMsg , QtCriticalMsg ，和 QFatalMsg are logged by default.

注意： Logging categories are not affected by your C++ build configuration. That is, whether messages are printed does not change depending on whether the code is compiled with debug symbols ('Debug Build'), optimizations ('Release Build'), or some other combination.

配置类别

You can override the default configuration for categories either by setting logging rules, or by installing a custom filter.

日志规则

Logging rules let you enable or disable logging for categories 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 for the first or last character; or at both positions. The optional <type> 必须为 debug , info , warning ，或 critical . Lines that don't 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 ():

    QLoggingCategory::setFilterRules("*.debug=false\n"
                                     "driver.usb.debug=true");

Logging rules are automatically loaded from the [Rules] section in a logging configuration file. These 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

Logging rules can also be specified in a QT_LOGGING_RULES environment variable; multiple rules can also be separated by semicolons:

    QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"

Rules set by setFilterRules () take precedence over rules specified in the QtProject configuration directory. In turn, these rules can be overwritten by those from the configuration file specified by QT_LOGGING_CONF , and those set by QT_LOGGING_RULES .

The order of evaluation is as follows:

[ QLibraryInfo::DataPath ]/qtlogging.ini
QtProject/qtlogging.ini
setFilterRules ()
QT_LOGGING_CONF
QT_LOGGING_RULES

The QtProject/qtlogging.ini file is looked up in all directories returned by QStandardPaths::GenericConfigLocation .

设置 QT_LOGGING_DEBUG environment variable to find out where your logging rules are loaded from.

Installing a Custom Filter

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 ().

成员函数文档编制

`[explicit]` QLoggingCategory:: QLoggingCategory (const char * category , QtMsgType enableForLevel = QtDebugMsg)

Constructs a QLoggingCategory object with the provided category name, and enables all messages with types at least as verbose as enableForLevel ，其默认为 QtDebugMsg (which enables all categories).

若 category is nullptr , the category name "default" 被使用。

注意： category must be kept valid during the lifetime of this object. Using a string literal for it is the usual way to achieve this.

`[noexcept]` QLoggingCategory:: ~QLoggingCategory ()

销毁 QLoggingCategory 对象。

const char *QLoggingCategory:: categoryName () const

Returns the name of the category.

`[static]` QLoggingCategory *QLoggingCategory:: defaultCategory ()

Returns a pointer to the global category "default" that is used, for example, by qDebug (), qInfo (), qWarning (), qCritical ()，或 qFatal ().

注意： The pointer returned may be null during destruction of static objects. Also, don't delete this pointer, as ownership of the category isn't transferred.

`[static]` QLoggingCategory::CategoryFilter QLoggingCategory:: installFilter ( QLoggingCategory::CategoryFilter filter )

Take control of how logging categories are configured.

Installs a function filter that is used to determine which categories and message types should be enabled. If filter is nullptr , the default message filter is reinstated. Returns a pointer to the previously-installed filter.

Every QLoggingCategory object that already exists is passed to the filter before installFilter() returns, and the filter is free to change each category's configuration with setEnabled (). Any category it doesn't change will retain the configuration it was given by the prior filter, so the new filter does not need to delegate to the prior filter during this initial pass over existing categories.

Any new categories added later will be passed to the new filter; a filter that only aims to tweak the configuration of a select few categories, rather than completely overriding the logging policy, can first pass the new category to the prior filter, to give it its standard configuration, and then tweak that as desired, if it is one of the categories of specific interest to the filter. The code that installs the new filter can record the return from installFilter() for the filter to use in such later calls.

When you define your filter, note that it can be called from different threads; but never concurrently. This filter cannot call any static functions from QLoggingCategory .

范例：

static QLoggingCategory::CategoryFilter oldCategoryFilter = nullptr;
void myCategoryFilter(QLoggingCategory *category)
{
    // For a category set up after this filter is installed, we first set it up
    // with the old filter. This ensures that any driver.usb logging configured
    // by the user is kept, aside from the one level we override; and any new
    // categories we're not interested in get configured by the old filter.
    if (oldCategoryFilter)
        oldCategoryFilter(category);
    // Tweak driver.usb's logging, over-riding the default filter:
    if (qstrcmp(category->categoryName(), "driver.usb") == 0)
        category->setEnabled(QtDebugMsg, true);
}

installed (in main() , for example) by

oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);

Alternatively, you can configure the default filter via setFilterRules ().

bool QLoggingCategory:: isCriticalEnabled () const

返回 true if critical messages should be shown for this category; false 否则。

注意： The qCCritical () macro already does this check before executing any code. However, calling this method may be useful to avoid the expensive generation of data for debug output only.

bool QLoggingCategory:: isDebugEnabled () const

返回 true if debug messages should be shown for this category; false 否则。

注意： The qCDebug () macro already does this check before running any code. However, calling this method may be useful to avoid the expensive generation of data for debug output only.

bool QLoggingCategory:: isEnabled ( QtMsgType msgtype ) const

返回 true if a message of type msgtype for the category should be shown; false 否则。

bool QLoggingCategory:: isInfoEnabled () const

返回 true if informational messages should be shown for this category; false 否则。

注意： The qCInfo () macro already does this check before executing any code. However, calling this method may be useful to avoid the expensive generation of data for debug output only.

bool QLoggingCategory:: isWarningEnabled () const

返回 true if warning messages should be shown for this category; false 否则。

注意： The qCWarning () macro already does this check before executing any code. However, calling this method may be useful to avoid the expensive generation of data for debug output only.

void QLoggingCategory:: setEnabled ( QtMsgType type , bool enable )

Changes the message type type for the category to enable .

This method is meant for use only from inside a filter installed with installFilter (). For an overview on how to configure categories globally, see 配置类别 .

注意： 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 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 has defined the QT_LOGGING_CONF 或 QT_LOGGING_RULES 环境变量。

QLoggingCategory &QLoggingCategory:: operator() ()

Returns the object itself. This allows for both: a QLoggingCategory variable, and a factory method that returns a QLoggingCategory , to be used in qCDebug (), qCWarning (), qCCritical ()，或 qCFatal () 宏。

const QLoggingCategory &QLoggingCategory:: operator() () const

宏文档编制

`[since 6.5]` Q_DECLARE_EXPORTED_LOGGING_CATEGORY ( name , EXPORT_MACRO )

Declares a logging category name . The macro can be used to declare a common logging category shared in different parts of the program.

This works exactly like Q_DECLARE_LOGGING_CATEGORY (). However, the logging category declared by this macro is additionally qualified with EXPORT_MACRO . This is useful if the logging category needs to be exported from a dynamic library.

例如：

Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcCore, LIB_EXPORT_MACRO)

This macro must be used outside of a class or function.

该宏在 Qt 6.5 引入。

另请参阅 Q_LOGGING_CATEGORY () 和 Q_DECLARE_LOGGING_CATEGORY ().

Q_DECLARE_LOGGING_CATEGORY ( name )

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.

另请参阅 Q_LOGGING_CATEGORY () 和 Q_DECLARE_EXPORTED_LOGGING_CATEGORY ().

Q_LOGGING_CATEGORY ( name , string )

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.

另请参阅 Q_DECLARE_LOGGING_CATEGORY () 和 Q_DECLARE_EXPORTED_LOGGING_CATEGORY ().

Q_LOGGING_CATEGORY ( name , string , msgType )

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.

另请参阅 Q_DECLARE_LOGGING_CATEGORY ().

qCCritical ( 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";

注意： If the critical output for a particular category isn't enabled, arguments won't be processed, so don't rely on any side effects.

另请参阅 qCritical ().

qCCritical ( category , const char * message , ...)

Logs a critical message, message , in the logging category, category . message may contain place holders to be 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());

注意： If the critical output for a particular category isn't enabled, arguments won't be processed, so don't rely on any side effects.

另请参阅 qCritical ().

qCDebug ( category )

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 aren't processed if the debug output for that category is not enabled, so don't rely on any side effects.

另请参阅 qDebug ().

qCDebug ( category , const char * message , ...)

Logs a debug message, message , in the logging category, category . message may contain place holders to be 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 aren't processed if the debug output for that category is not enabled, so don't rely on any side effects.

另请参阅 qDebug ().

`[since 6.5]` qCFatal ( category )

Returns an output stream for fatal messages in the logging category, category .

若正使用 默认消息处理程序 , the returned stream will abort to create a core dump. On Windows, for debug builds, this function will report a _CRT_ERROR enabling you to connect a debugger to the application.

范例：

    QLoggingCategory category("driver.usb");
    qCFatal(category) << "a fatal message. Program will be terminated!";

该宏在 Qt 6.5 引入。

另请参阅 qFatal ().

`[since 6.5]` qCFatal ( category , const char * message , ...)

Logs a fatal message, message , in the logging category, category . message may contain place holders to be replaced by additional arguments, similar to the C printf() function.

范例：

    QLoggingCategory category("driver.usb");
    qCFatal(category, "a fatal message. Program will be terminated!");

若正使用 默认消息处理程序 , this function will abort to create a core dump. On Windows, for debug builds, this function will report a _CRT_ERROR enabling you to connect a debugger to the application.

该宏在 Qt 6.5 引入。

另请参阅 qFatal ().

qCInfo ( category )

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";

注意： If the debug output for a particular category isn't enabled, arguments won't be processed, so don't rely on any side effects.

另请参阅 qInfo ().

qCInfo ( category , const char * message , ...)

Logs an informational message, message , in the logging category, category . message may contain place holders to be 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());

注意： If the debug output for a particular category isn't enabled, arguments won't be processed, so don't rely on any side effects.

另请参阅 qInfo ().

qCWarning ( category )

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";

注意： If the warning output for a particular category isn't enabled, arguments won't be processed, so don't rely on any side effects.

另请参阅 qWarning ().

qCWarning ( category , const char * message , ...)

Logs a warning message, message , in the logging category, category . message may contain place holders to be 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());

注意： If the warning output for a particular category isn't enabled, arguments won't be processed, so don't rely on any side effects.

另请参阅 qWarning ().

QLoggingCategory 类

公共类型

公共函数

静态公共成员

宏

详细描述

创建类别对象

校验类别配置

默认类别配置

配置类别

日志规则

Installing a Custom Filter

打印类别

成员类型文档编制

QLoggingCategory:: CategoryFilter

成员函数文档编制

[explicit] QLoggingCategory:: QLoggingCategory (const char * category , QtMsgType enableForLevel = QtDebugMsg)

[noexcept] QLoggingCategory:: ~QLoggingCategory ()

const char *QLoggingCategory:: categoryName () const

[static] QLoggingCategory *QLoggingCategory:: defaultCategory ()

[static] QLoggingCategory::CategoryFilter QLoggingCategory:: installFilter ( QLoggingCategory::CategoryFilter filter )

bool QLoggingCategory:: isCriticalEnabled () const

bool QLoggingCategory:: isDebugEnabled () const

bool QLoggingCategory:: isEnabled ( QtMsgType msgtype ) const

bool QLoggingCategory:: isInfoEnabled () const

bool QLoggingCategory:: isWarningEnabled () const

void QLoggingCategory:: setEnabled ( QtMsgType type , bool enable )

[static] void QLoggingCategory:: setFilterRules (const QString & rules )

QLoggingCategory &QLoggingCategory:: operator() ()

const QLoggingCategory &QLoggingCategory:: operator() () const

宏文档编制

[since 6.5] Q_DECLARE_EXPORTED_LOGGING_CATEGORY ( name , EXPORT_MACRO )

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 , ...)

[since 6.5] qCFatal ( category )

[since 6.5] qCFatal ( category , const char * message , ...)

qCInfo ( category )

qCInfo ( category , const char * message , ...)

qCWarning ( category )

qCWarning ( category , const char * message , ...)

内容

`[explicit]` QLoggingCategory:: QLoggingCategory (const char * category , QtMsgType enableForLevel = QtDebugMsg)

`[noexcept]` QLoggingCategory:: ~QLoggingCategory ()

`[static]` QLoggingCategory *QLoggingCategory:: defaultCategory ()

`[static]` QLoggingCategory::CategoryFilter QLoggingCategory:: installFilter ( QLoggingCategory::CategoryFilter filter )

`[static]` void QLoggingCategory:: setFilterRules (const QString & rules )

`[since 6.5]` Q_DECLARE_EXPORTED_LOGGING_CATEGORY ( name , EXPORT_MACRO )

`[since 6.5]` qCFatal ( category )

`[since 6.5]` qCFatal ( category , const char * message , ...)