Класс QLoggingCategory

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

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

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

Типы Public

Функции Public

Статические Public члены

Макросы

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

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

Правила ведения журнала автоматически загружаются из раздела [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".

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

[since 5.5] 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 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";