Класс 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.

Если аргумент не передан, все сообщения записываются в журнал. Только внутренние категории Qt, начинающиеся с qt, обрабатываются по-другому: для них по умолчанию записываются только сообщения типа QtInfoMsg, QtWarningMsg и QtCriticalMsg.

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

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

Правила ведения журнала

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

    <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

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

void myCategoryFilter(QLoggingCategory *);

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

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

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

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

Если category равно nullptr, имя категории "default" используется.

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

QLoggingCategory::~QLoggingCategory()

Уничтожает объект QLoggingCategory.

const char *QLoggingCategory::categoryName() const

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

[static] QLoggingCategory *QLoggingCategory::defaultCategory()

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

[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 в противном случае.

bool QLoggingCategory::isDebugEnabled() const

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

bool QLoggingCategory::isEnabled(QtMsgType msgtype) const

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

[since 5.5] bool QLoggingCategory::isInfoEnabled() const

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

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

bool QLoggingCategory::isWarningEnabled() const

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

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

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

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

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

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

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

Пример:

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

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 logged into category %s", category.categoryName());

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

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

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

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

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

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

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