Класс QLoggingCategory

Класс QLoggingCategory представляет категорию, или «область» в инфраструктуре логирования. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются потокобезопасными.

Типы публичного доступа

Функции публичного доступа

Статические члены публичного доступа

Макросы

Подробное описание

Класс QLoggingCategory представляет категорию или «область» в инфраструктуре ведения журнала.

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

Примечание: Имена категорий являются текстом произвольной формы. Однако для удобной конфигурации категорий с использованием Правил ведения журнала имена должны следовать некоторым правилам:

• Используйте только буквы и цифры.
• Дальнейшая структура категорий в общие области путём использования точек.
• Избегайте имён категорий debug, info, warning, и critical.
• Имена категорий, начинающиеся с qt, зарезервированы для модулей Qt.

Объекты QLoggingCategory, неявно определённые макросом Q_LOGGING_CATEGORY(), создаются при первом использовании безопасным для потоков способом.

Проверка конфигурации категории

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.

Если аргумент не передан, все сообщения будут записаны.

Настройка категорий

Значения по умолчанию для категорий могут быть изменены путем установки правил регистрации или установки пользовательского фильтра.

Правила регистрации

Правила регистрации позволяют гибко включать или отключать регистрацию для категорий. Правила задаются в текстовом формате, где каждая строка должна иметь формат

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

<category> — это имя категории, потенциально с * в качестве символа подстановки в начале или конце (или в обоих позициях). Необязательный <type> должен быть либо debug, либо info, либо warning, либо critical. Строки, не соответствующие этому формату, игнорируются.

Правила оцениваются в текстовом порядке, от первой к последней. То есть, если два правила применяются к категории/типу, применяется правило, которое стоит позже.

Правила можно установить с помощью setFilterRules():

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

Начиная с Qt 5.3, правила регистрации также автоматически загружаются из раздела [Rules] файла конфигурации регистрации. Такие файлы конфигурации ищутся в каталоге конфигурации QtProject или явно задаются в переменной среды QT_LOGGING_CONF.

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

Начиная с Qt 5.3, правила регистрации также можно указать в переменной среды QT_LOGGING_RULES. А начиная с Qt 5.6, несколько правил можно разделить точкой с запятой:

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

Правила, установленные с помощью setFilterRules(), имеют приоритет над правилами, указанными в каталоге конфигурации QtProject, и, в свою очередь, могут быть переопределены правилами из файла конфигурации, указанного QT_LOGGING_CONF, и правилами, установленными QT_LOGGING_RULES.

Порядок оценки:

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

Файл QtProject/qtlogging.ini ищется во всех каталогах, возвращаемых QStandardPaths::GenericConfigLocation, например:

• на macOS и iOS: ~/Library/Preferences
• на Unix: ~/.config, /etc/xdg
• на Windows: %LOCALAPPDATA%, %ProgramData%, QCoreApplication::applicationDirPath(), QCoreApplication::applicationDirPath() + "/data"

Установите переменную среды QT_LOGGING_DEBUG для просмотра, откуда загружаются правила регистрации.

Установка пользовательского фильтра

В качестве альтернативы текстовым правилам на более низком уровне вы также можете реализовать пользовательский фильтр с помощью installFilter(). Во всех случаях правила фильтра игнорируются.

Вывод категории

Используйте заполнитель %{category} для вывода категории в обработчике сообщений по умолчанию:

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

Документация по типу членов

typedef QLoggingCategory::CategoryFilter

Это typedef для указателя на функцию со следующим сигнатурой:

void myCategoryFilter(QLoggingCategory *);

Функцию с этим сигнатурой можно установить с помощью installFilter().

Документация по функциям-членам

QLoggingCategory::QLoggingCategory(const char *category)

Создает объект QLoggingCategory с указанным именем категории category. Все типы сообщений для этой категории включены по умолчанию.

Если category — 0, имя категории изменяется на "default".

Обратите внимание, что category должен оставаться действительным в течение всего срока службы этого объекта.

QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel)

Создаёт объект QLoggingCategory с указанным именем категории category и включает все сообщения с типами, более серьёзными или равными enableForLevel.

Если category — 0, имя категории изменяется на "default".

Обратите внимание, что category должен оставаться действительным в течение всего срока службы этого объекта.

Эта функция была добавлена в Qt 5.4.

QLoggingCategory::~QLoggingCategory()

Удаляет объект QLoggingCategory.

const char *QLoggingCategory::categoryName() const

Возвращает имя категории.

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

Возвращает указатель на глобальную категорию "default", которая используется, например, функциями qDebug(), qInfo(), qWarning(), qCritical(), qFatal().

Примечание: Возвращаемый указатель может быть нулевым во время уничтожения статических объектов.

Примечание: Владение категорией не передаётся, не delete возвращаемый указатель.

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

Устанавливает функцию filter, которая используется для определения, какие категории и типы сообщений должны быть включены. Возвращает указатель на ранее установленный фильтр.

Каждый созданный объект QLoggingCategory передаётся в фильтр, и фильтр свободен изменять соответствующую конфигурацию категории с помощью setEnabled().

Фильтр может вызываться из разных потоков, но никогда не одновременно. Фильтр не должен вызывать какие-либо статические функции 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);
}

Альтернативный способ конфигурирования фильтра по умолчанию — с помощью setFilterRules().

bool QLoggingCategory::isCriticalEnabled() const

Возвращает true , если критические сообщения должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макро qCCritical() уже выполняет эту проверку перед выполнением кода. Однако, вызов этого метода может быть полезен для избежания дорогостоящего создания данных, которые используются только для отладки.

bool QLoggingCategory::isDebugEnabled() const

Возвращает true , если сообщения отладки должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макро qCDebug() уже выполняет эту проверку перед выполнением кода. Однако, вызов этого метода может быть полезен для избежания дорогостоящего создания данных, которые используются только для отладки.

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

Возвращает true , если сообщение типа msgtype для категории должно быть отображено. Возвращает false в противном случае.

bool QLoggingCategory::isInfoEnabled() const

Возвращает true , если информационные сообщения должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макро qCInfo() уже выполняет эту проверку перед выполнением кода. Однако, вызов этого метода может быть полезен для избежания дорогостоящего создания данных, которые используются только для отладки.

Функция была добавлена в Qt 5.5.

bool QLoggingCategory::isWarningEnabled() const

Возвращает true , если предупреждающие сообщения должны отображаться для этой категории. Возвращает false в противном случае.

Примечание: Макро qCWarning() уже выполняет эту проверку перед выполнением кода. Однако, вызов этого метода может быть полезен для избежания дорогостоящего создания данных, которые используются только для отладки.

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

Изменяет тип сообщения type для категории на enable.

Этот метод предназначен для использования только внутри фильтра, установленного с помощью installFilter(). См. Настройка категорий для обзора способов глобальной настройки категорий.

Примечание: QtFatalMsg изменить нельзя. Она всегда останется true.

См. также isEnabled().

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

Настраивает, какие категории и типы сообщений должны быть включены с помощью набора правил rules.

Пример:

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

Примечание: Правила могут быть проигнорированы, если установлен пользовательский фильтр категорий с помощью installFilter() или если пользователь определил QT_LOGGING_CONF или QT_LOGGING_RULES переменную окружения.

QLoggingCategory &QLoggingCategory::operator()()

Возвращает сам объект. Это позволяет использовать как переменную QLoggingCategory, так и метод фабрики, возвращающий QLoggingCategory, в макросах qCDebug(), qCWarning(), qCCritical().

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

Возвращает сам объект. Это позволяет использовать как переменную QLoggingCategory, так и фабричный метод, возвращающий QLoggingCategory, в макросах qCDebug(), qCWarning(), qCCritical().

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

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

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

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

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

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

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

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