Класс QLoggingCategory

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

Этот класс был представлен в Qt 5.2.

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

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

Открытые типы

Открытые функции

Статические открытые члены

Макросы

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

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

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

typedef QLoggingCategory::CategoryFilter

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

void myCategoryFilter(QLoggingCategory *);

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

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

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

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

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

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

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

QLoggingCategory::QLoggingCategory(const char *category)

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

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

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

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