QLoggingCategory 类

QLoggingCategory 类表示一个类别，或日志基础设施中的一个“区域”。更多信息...

头文件 #include <QLoggingCategory>
CMakefind_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmakeQT += core

注意：该类中所有函数都是线程安全的。

公共类型

CategoryFilter

公共函数

QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg)
~QLoggingCategory()
const char *categoryName() const
boolisCriticalEnabled() const
boolisDebugEnabled() const
boolisEnabled(QtMsgType msgtype) const
boolisInfoEnabled() const
boolisWarningEnabled() const
voidsetEnabled(QtMsgType type, bool enable)
QLoggingCategory &operator()()
const QLoggingCategory &operator()() const

静态公共成员

QLoggingCategory *defaultCategory()
QLoggingCategory::CategoryFilterinstallFilter(QLoggingCategory::CategoryFilter filter)
voidsetFilterRules(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表示运行时某个以字符串标识的日志类别。类别可以被配置为启用或禁用按消息类型记录消息。但致命消息始终开启。

要检查消息类型是否开启，可以使用以下方法之一：isDebugEnabled()，isInfoEnabled()，isWarningEnabled()，以及 isCriticalEnabled()。

所有对象都应通过公共注册表进行配置，详见配置类别。不同的对象可以代表相同的类别。因此，不建议在城市边界之外导出对象，直接操作对象或从QLoggingCategory继承。

创建类别对象

Q_DECLARE_LOGGING_CATEGORY() 和 Q_LOGGING_CATEGORY() 宏可以方便地声明和创建QLoggingCategory对象。

// in a header
Q_DECLARE_LOGGING_CATEGORY(driverUsb)

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

还有Q_DECLARE_EXPORTED_LOGGING_CATEGORY() 宏，可以在库边界之外使用日志类别。

类别名称是自由文本；使用日志规则配置类别时，其名称应遵循以下约定。

  • 只使用字母和数字。
  • 使用点号进一步将类别结构化到公共区域。
  • 避免使用类别名称：debug、info、warning和critical。
  • 具有qt前缀的类别名称仅保留给Qt模块。

由Q_LOGGING_CATEGORY()隐式定义的QLoggingCategory对象在首次使用时以线程安全的方式创建。

检查类别配置

QLoggingCategory提供isDebugEnabled()，isInfoEnabled()，isWarningEnabled()，isCriticalEnabled()以及isEnabled()来检查是否应将给定类型的消息记录下来。

qCDebug()，qCWarning()和qCCritical()宏在相应的消息类型未在类别中开启时，阻止参数的评估，因此不需要显式检查。

    // usbEntries() will only be called if driverUsb category is enabled
    qCDebug(driverUsb) << "devices: " << usbEntries();

默认类别配置

QLoggingCategory构造函数和Q_LOGGING_CATEGORY()宏均接受一个可选的QtMsgType参数，这将禁用所有更低严重性的消息类型。也就是说，使用以下声明

Q_LOGGING_CATEGORY(driverUsbEvents, "driver.usb.events", QtWarningMsg)

记录类型为QtWarningMsg，QtCriticalMsg，QtFatalMsg的消息，但忽略类型为QtDebugMsg和QtInfoMsg的消息。

如果没有传入任何参数，则记录所有消息。只有以qt开头的Qt内部类别处理方式不同：对于这些类别，默认情况下记录类型为QtInfoMsg，QtWarningMsg，QtCriticalMsg和QtFatalMsg的消息。

注意：记录类别不受您的C++构建配置的影响。也就是说，消息是否打印并不取决于代码是否编译为包含调试符号（'Debug Build'）、优化（'Release Build'）或者某些其他组合。

配置类别

您可以通过设置记录规则或安装自定义过滤器来覆盖类别的默认配置。

记录规则

记录规则提供了一种灵活的方式，让您启用或禁用类别的记录。规则以文本形式指定，每行必须符合以下格式：

    <category>[.<type>] = true|false

<category> 是类别的名称，可能包含 * 作为通配符符号，用于第一个或最后一个字符；或者两个位置都可以。可选的 <type> 必须是 debug、info、warning 或 critical。不符合此格式的行将被忽略。

规则按文本顺序评估，从第一个到最后一个。也就是说，如果有两个规则适用于一个类别/类型，则后来应用的规则会被执行。

规则可以通过 setFilterRules() 设置

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

记录规则会自动从记录配置文件的 [Rules] 部分加载。这些配置文件在 QtProject 配置目录中搜索，或者通过环境变量 QT_LOGGING_CONF 显式设置

    [Rules]
    *.debug=false
    driver.usb.debug=true

记录规则也可以通过 QT_LOGGING_RULES 环境变量指定；多个规则也可以用分号分开

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

setFilterRules() 设置的规则优先于 QtProject 配置目录中指定的规则。转而，这些规则可以被 QT_LOGGING_CONF 指定的配置文件中的规则覆盖，以及那些通过 QT_LOGGING_RULES 设置的规则。

评估顺序如下

  1. [QLibraryInfo::DataPath]/qtlogging.ini
  2. QtProject/qtlogging.ini
  3. setFilterRules()
  4. QT_LOGGING_CONF
  5. QT_LOGGING_RULES

QtProject/qtlogging.ini 文件在 QStandardPaths::GenericConfigLocation 返回的所有目录中搜索。

将 QT_LOGGING_DEBUG 环境变量设置为找出您的记录规则是从哪里加载的。

安装自定义过滤器

作为文本规则的底层替代方案，您也可以通过 installFilter() 实现。在这种情况下，所有过滤器规则都将被忽略。

打印类别

使用 %{category} 占位符在默认消息处理器中打印类别

    qSetMessagePattern("%{category} %{message}");

成员类型文档

QLoggingCategory::CategoryFilter

这是具有以下签名的函数指针的typedef：

void myCategoryFilter(QLoggingCategory *);

可以具有此签名的函数通过 installFilter() 安装。

成员函数文档

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

使用提供的category名称构建一个QLoggingCategory对象，并启用所有至少 verbose 如 enableForLevel 类型的消息，默认为 QtDebugMsg（这会启用所有类别）。

如果category是nullptr，则使用类别名称"default"。

注意：category必须在对象生命期内保持有效。使用字符串字面量为它赋值是通常实现这一点的途径。

[noexcept] QLoggingCategory::~QLoggingCategory()

销毁一个QLoggingCategory对象。

const char *QLoggingCategory::categoryName() const

返回类别的名称。

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

返回全局类别"default"的指针，该类别由例如qDebug()，qInfo()，qWarning()，qCritical()或qFatal()使用。

注意：在静态对象的销毁过程中，返回的指针可能为 null。此外，不要delete此指针，因为类别所有权未转让。

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

控制日志类别的配置方式。

安装一个函数filter，它用于确定应启用哪些类别和消息类型。如果filter是nullptr，则重新启用默认消息过滤器。返回之前安装的过滤器的指针。

在installFilter()返回之前，将每个现有的QLoggingCategory对象传递给过滤器，过滤器可以使用setEnabled()来更改每个类别的配置。任何未更改的类别将保留先前过滤器提供的配置，因此新过滤器在此对现有类别进行初始遍历时不需要委托给先前过滤器。

稍后添加的任何新类别都将传递给新过滤器；如果过滤器仅旨在调整少量类别的配置而不是完全覆盖日志策略，则可以将新类别首先传递给先前过滤器，以给它标准配置，然后根据需要调整，如果它是过滤器特定感兴趣类别之一。安装新过滤器的代码可以记录installFilter()的返回值以供过滤器在以后调用中使用。

在定义您的过滤器时，请注意它可以从不同的线程调用；但永远不要并发调用。该过滤器不能从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);
}

通过main()（例如）安装的已安装

oldCategoryFilter = QLoggingCategory::installFilter(myCategoryFilter);

或者，您可以通过setFilterRules()配置默认过滤器。

bool QLoggingCategory::isCriticalEnabled() const

如果应为此类别显示关键消息，则返回true；否则返回false。

注意：qCCritical() 宏在执行任何代码之前已经进行了此检查。然而，调用此方法可能有助于避免仅用于调试输出的昂贵的数据生成。

bool QLoggingCategory::isDebugEnabled() const

如果应该为该类别显示调试消息，则返回true；否则返回false。

注意： qCDebug() 宏已经在运行任何代码之前进行此检查。然而，调用此方法可能有助于避免仅用于调试输出而生成数据的昂贵操作。

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

如果应该为该类别显示类型为 msgtype 的消息，则返回true；否则返回false。

bool QLoggingCategory::isInfoEnabled() const

如果应该为该类别显示信息性消息，则返回true；否则返回false。

注意： qCInfo() 宏已经在执行任何代码之前进行此检查。然而，调用此方法可能有助于避免仅用于调试输出而生成数据的昂贵操作。

bool QLoggingCategory::isWarningEnabled() const

如果应该为该类别显示警告消息，则返回true；否则返回false。

注意： qCWarning() 宏已经在执行任何代码之前进行此检查。然而，调用此方法可能有助于避免仅用于调试输出而生成数据的昂贵操作。

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

将类别的消息类型 type 改为 enable。

此方法仅供在通过 installFilter() 安装的过滤器中使用。有关如何全局配置类别的概述，请参阅 配置类别。

注意： QtFatalMsg 不能更改；它将始终保持 true。

另请参阅：isEnabled()。

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

通过一系列规则配置应启用哪些类别和消息类型。

示例

    QLoggingCategory::setFilterRules(QStringLiteral("driver.usb.debug=true"));

注意： 如果通过 installFilter() 安装了自定义类别过滤器，或者用户已定义了 QT_LOGGING_CONF 或 QT_LOGGING_RULES 环境变量，则可能会忽略这些规则。

QLoggingCategory &QLoggingCategory::operator()()

返回对象本身。这允许在 qCDebug()、 qCWarning()、 qCCritical() 或 qCFatal() 宏中使用 QLoggingCategory 变量和返回 QLoggingCategory 的工厂方法。

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

返回对象本身。这允许在 qCDebug()、 qCWarning()、 qCCritical() 或 qCFatal() 宏中使用 QLoggingCategory 变量和返回 QLoggingCategory 的工厂方法。

宏文档

[自 6.5] Q_DECLARE_EXPORTED_LOGGING_CATEGORY(name, EXPORT_MACRO)

声明日志类别名称 name。该宏可用于在程序的不同部分中声明共享的通用日志类别。

这与 Q_DECLARE_LOGGING_CATEGORY 完全相同。然而，该宏声明的日志类别还额外携带了 EXPORT_MACRO 标识。如果需要将从动态库中导出日志类别，这很有用。

例如

Q_DECLARE_EXPORTED_LOGGING_CATEGORY(lcCore, LIB_EXPORT_MACRO)

此宏必须在类或函数外部使用。

此宏是在Qt 6.5中引入的。

另请参阅Q_LOGGING_CATEGORY() 和 Q_DECLARE_LOGGING_CATEGORY。

Q_DECLARE_LOGGING_CATEGORY(name)

声明日志类别名称 name。该宏可用于在程序的不同部分中声明共享的通用日志类别。

此宏必须在类或方法外部使用。

另请参阅Q_LOGGING_CATEGORY() 和 Q_DECLARE_EXPORTED_LOGGING_CATEGORY。

Q_LOGGING_CATEGORY(name, string)

定义一个日志类别 name，并使其可以在 string 标识符下进行配置。默认情况下，所有消息类型都被启用。

库或可执行文件中只能有一个翻译单元定义具有特定名称的类别。隐式定义的 QLoggingCategory 对象是在第一次使用时以线程安全的方式创建的。

此宏必须在类或方法外部使用。

另请参阅Q_DECLARE_LOGGING_CATEGORY() 和 Q_DECLARE_EXPORTED_LOGGING_CATEGORY。

Q_LOGGING_CATEGORY(name, string, msgType)

定义一个日志类别 name，并使其可以在 string 标识符下进行配置。默认情况下，启用 QtMsgType msgType 和严重程度更高的消息，级别较低的消息类型被禁用。

库或可执行文件中只能有一个翻译单元定义具有特定名称的类别。隐式定义的 QLoggingCategory 对象是在第一次使用时以线程安全的方式创建的。

此宏必须在类或方法外部使用。

另请参阅Q_DECLARE_LOGGING_CATEGORY。

qCCritical(category)

返回用于 category 中临界消息的输出流。

该宏展开为检查 QLoggingCategory::isCriticalEnabled() 是否评估为 true。如果是这样，则处理流参数并发送到消息处理程序。

示例

    QLoggingCategory category("driver.usb");
    qCCritical(category) << "a critical message";

注意：如果特定类别的临界输出没有被启用，则不会处理参数，因此不要依赖于任何副作用。

另请参阅qCritical。

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

在日志类别 category 中记录一个临界消息，message 可以包含用于替换额外参数的占位符，类似于 C printf() 函数。

示例

    QLoggingCategory category("driver.usb");
    qCCritical(category, "a critical message logged into category %s", category.categoryName());

注意：如果特定类别的临界输出没有被启用，则不会处理参数，因此不要依赖于任何副作用。

另请参阅qCritical。

qCDebug(category)

返回用于 category 中调试消息的输出流。

该宏展开为检查 QLoggingCategory::isDebugEnabled() 是否评估为 true。如果是这样，则处理流参数并发送到消息处理程序。

示例

    QLoggingCategory category("driver.usb");
    qCDebug(category) << "a debug message";

注意：如果该 category 的调试输出未启用，则不会处理参数，因此不要依赖任何副作用。

另请参阅qDebug。

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

在日志分类中，记录调试消息message。 message可以包含占位符，这些占位符可以用更多参数替换，类似于C语言的printf()函数。

示例

    QLoggingCategory category("driver.usb");
    qCDebug(category, "a debug message logged into category %s", category.categoryName());

注意：如果该 category 的调试输出未启用，则不会处理参数，因此不要依赖任何副作用。

另请参阅qDebug。

[since 6.5] qCFatal(category)

返回用于记录日志分类中的严重错误消息的输出流，category。

如果你使用的是默认的消息处理器，返回的流将导致程序终止以创建核心转储。在Windows上的调试版本中，这个函数将报告一个_CRT_ERROR，你可以通过它连接调试器到应用程序。

示例

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

在日志分类中记录严重错误消息message。 message可以包含占位符，这些占位符可以用更多参数替换，类似于C语言的printf()函数。

示例

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

如果你使用的是默认的消息处理器，此函数将导致程序终止以创建核心转储。在Windows的调试版本中，此函数将报告一个_CRT_ERROR，你可通过它将调试器连接到应用程序。

此宏是在Qt 6.5中引入的。

另请参阅 qFatal。

qCInfo(category)

返回用于记录日志分类中的信息消息的输出流，category。

宏展开为检查QLoggingCategory::isInfoEnabled()是否评估为true的代码。如果是，流参数将被处理并发送到消息处理器。

示例

    QLoggingCategory category("driver.usb");
    qCInfo(category) << "an informational message";

注意： 如果特定分类的调试输出未被启用，则不会处理参数，因此不要依赖于任何副作用。

另请参阅 qInfo。

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

在日志分类中记录信息消息message。 message可以包含占位符，这些占位符可以用更多参数替换，类似于C语言的printf()函数。

示例

    QLoggingCategory category("driver.usb");
    qCInfo(category, "an informational message logged into category %s", category.categoryName());

注意： 如果特定分类的调试输出未被启用，则不会处理参数，因此不要依赖于任何副作用。

另请参阅 qInfo。

qCWarning(category)

返回用于记录日志分类中的警告消息的输出流，category。

宏展开为检查QLoggingCategory::isWarningEnabled()是否评估为true的代码。如果是，流参数将被处理并发送到消息处理器。

示例

    QLoggingCategory category("driver.usb");
    qCWarning(category) << "a warning message";

注意： 如果特定分类的警告输出未被启用，则不会处理参数，因此不要依赖于任何副作用。

另请参阅 qWarning。

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

在日志分类中记录警告消息message。 message可以包含占位符，这些占位符可以用更多参数替换，类似于C语言的printf()函数。

示例

    QLoggingCategory category("driver.usb");
    qCWarning(category, "a warning message logged into category %s", category.categoryName());

注意： 如果特定分类的警告输出未被启用，则不会处理参数，因此不要依赖于任何副作用。

另请参阅 qWarning。

© 2024 The Qt Company Ltd。本文件中包含的文档贡献者的版权所有。本文件提供的文档受GNU自由文档许可证版本1.3的条款约束，由自由软件基金会发布。Qt及其标志是The Qt Company Ltd.在芬兰以及其他国家的商标。所有其他商标均为其各自所有者的财产。