QLoggingCategory Class
QLoggingCategory クラスは、ロギング・インフラストラクチャのカテゴリ、または「エリア」を表します。詳細...
Header: | #include <QLoggingCategory> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
注意:このクラスのすべての関数はスレッドセーフです。
パブリック型
パブリック関数
QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg) | |
~QLoggingCategory() | |
const char * | categoryName() const |
bool | isCriticalEnabled() const |
bool | isDebugEnabled() const |
bool | isEnabled(QtMsgType msgtype) const |
bool | isInfoEnabled() const |
bool | isWarningEnabled() const |
void | setEnabled(QtMsgType type, bool enable) |
QLoggingCategory & | operator()() |
const QLoggingCategory & | operator()() const |
静的パブリックメンバ
QLoggingCategory * | defaultCategory() |
QLoggingCategory::CategoryFilter | installFilter(QLoggingCategory::CategoryFilter filter) |
void | setFilterRules(const QString &rules) |
マクロ
(since 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, ...) | |
(since 6.5) | qCFatal(category) |
(since 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()。
Configuring Categories で説明されているように、すべてのオブジェクトは共通のレジストリで 構成されるようになっています。異なるオブジェクトが同じカテゴリーを表すこともあります。したがって、モジュールの境界を越えてオブジェクトをエクスポートしたり、オブジェクトを直接操作したり、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() マクロもあります。
カテゴリー名はフリーテキストです。Logging Rules を使用してカテゴリーを構成するには、その名前はこの規約に従わなければなりません:
- カテゴリ名はフリーテキストです。
- ドットを使用して、カテゴリーをさらに共通の領域に構造化する。
- カテゴリ名は避けてください:
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
、QFatalMsg
のタイプのメッセージだけがログに記録されます。
注意: ロギング・カテゴリーは C++ ビルドの設定に影響されません。つまり、コードがデバッグ・シンボル('Debug Build')、最適化('Release Build')、またはその他の組み合わせでコンパイルされているかどうかによって、メッセージが出力されるかどうかが変わることはありません。
カテゴリの設定
カテゴリのデフォルト設定を上書きするには、ロギングルールを設定するか、カスタムフィルタをインストールします。
ロギングルール
ロギングルールによって、柔軟な方法でカテゴリのロギングを有効または無効にできます。ルールはテキストで指定します:
<category>[.<type>] = true|false
<category>
はカテゴリー名で、最初か最後の文字にワイルドカードシンボルとして を指定することもできます。オプションの は、 、 、 、 のいずれかでなければならない。このスキームに合わない行は無視される。*
<type>
debug
info
warning
critical
ルールは、テキストの先頭から末尾の順に評価される。つまり、1つのカテゴリー/タイプに2つのルールが適用される場合、後に来るルールが適用される。
ルールは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
で設定された設定ファイルによって上書きされます。
評価の順序は以下の通りです:
- [QLibraryInfo::DataPath]/qtlogging.ini
- QtProject/qtlogging.ini
- setFilterRules()
QT_LOGGING_CONF
QT_LOGGING_RULES
QtProject/qtlogging.ini
ファイルは、QStandardPaths::GenericConfigLocation によって返されたすべてのディレクトリで検索されます。
QT_LOGGING_DEBUG
環境変数を設定して、ロギングルールがどこからロードされるかを調べてください。
カスタムフィルターのインストール
テキスト・ルールの低レベルの代替として、installFilter() を使ってカスタム・フィルターを実装することもできます。この場合、すべてのフィルター・ルールは無視されます。
カテゴリの印刷
デフォルトのメッセージ・ハンドラでカテゴリを表示するには、%{category}
プレースホルダを使用します:
qSetMessagePattern("%{category} %{message}");
メンバ型ドキュメント
QLoggingCategory::CategoryFilter
これは、以下のシグネチャを持つ関数へのポインタの typedef です:
void myCategoryFilter(QLoggingCategory *);
このシグネチャを持つ関数は、installFilter() でインストールできます。
メンバ関数ドキュメント
[explicit]
QLoggingCategory::QLoggingCategory(const char *category, QtMsgType enableForLevel = QtDebugMsg)
提供されたcategory 名で QLoggingCategory オブジェクトを構築し、少なくともenableForLevel と同じくらい冗長なタイプを持つすべてのメッセージを有効にします。デフォルトはQtDebugMsg (すべてのカテゴリを有効にする) です。
category がnullptr
の場合、カテゴリ名"default"
が使用されます。
注意: category は、このオブジェクトの有効期間中、有効にしておく必要があります。これを実現するには、文字列リテラルを使用するのが一般的です。
[noexcept]
QLoggingCategory::~QLoggingCategory()
QLoggingCategory オブジェクトを破棄します。
const char *QLoggingCategory::categoryName() const
カテゴリ名を返します。
[static]
QLoggingCategory *QLoggingCategory::defaultCategory()
qDebug()、qInfo()、qWarning()、qCritical()、またはqFatal() などで使用されるグローバル・カテゴリ"default"
へのポインタを返します。
注意: 静的オブジェクトの破棄時に、返されるポインタがNULLになることがあります。また、カテゴリの所有権は移譲されないので、このポインタをdelete
。
[static]
QLoggingCategory::CategoryFilter QLoggingCategory::installFilter(QLoggingCategory::CategoryFilter filter)
ロギング・カテゴリの設定方法を制御します。
どのカテゴリーとメッセージ・タイプを有効にするかを決定するために使用される関数filter をインストールします。filter がnullptr
の場合、デフォルトのメッセージ・フィルタが復活します。以前にインストールされたフィルタへのポインタを返します。
installFilter()
が返される前に、すでに存在するすべてのQLoggingCategory オブジェクトがフィルタに渡され、フィルタはsetEnabled() で各カテゴリの設定を自由に変更できます。フィルターが変更しなかったカテゴリーは、前のフィルターによって与えられた設定を保持するので、新しいフィルターは、既存のカテゴリーに対するこの最初のパスの間、前のフィルターに委譲する必要はありません。
ロギングポリシーを完全に上書きするのではなく、選択されたいくつかのカテゴリの設定を調整することだけを目的とするフィルタは、最初に新しいカテゴリを先行フィルタに渡して標準の設定を与え、それがフィルタにとって特定の関心のあるカテゴリの1つであれば、必要に応じてそれを調整することができます。新しいフィルタをインストールするコードは、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() でインストールされたフィルター内部からのみ使用できる。カテゴリーをグローバルに設定する方法の概要については、Configuring Categories を参照してください。
注: 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()、またはqCFatal() マクロで使用できます。
const QLoggingCategory &QLoggingCategory::operator()() const
オブジェクト自身を返します。これにより、QLoggingCategory 変数と、QLoggingCategory を返すファクトリーメソッドの両方を、qCDebug()、qCWarning()、qCCritical()、またはqCFatal() マクロで使用できます。
マクロ・ドキュメント
[since 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 識別子の下で設定可能にします。デフォルトでは、すべてのメッセージ・タイプが有効になります。
ライブラリまたは実行可能ファイル内の1つの翻訳ユニットだけが、特定の名前のカテゴリを定義できます。暗黙的に定義されたQLoggingCategory オブジェクトは、最初の使用時にスレッドセーフな方法で生成されます。
このマクロは、クラスまたはメソッドの外部で使用する必要があります。
Q_DECLARE_LOGGING_CATEGORY() およびQ_DECLARE_EXPORTED_LOGGING_CATEGORY()も参照して ください。
Q_LOGGING_CATEGORY(name, string, msgType)
ロギング・カテゴリname を定義し、string 識別子の下で設定可能にします。デフォルトでは、QtMsgType msgType 以上のメッセージは有効になり、それ以下のメッセージは無効になります。
ライブラリまたは実行可能ファイル内の1つの翻訳ユニットだけが、特定の名前のカテゴリを定義できます。暗黙的に定義された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 をログに記録する。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 をロギング・カテゴリーcategory に記録する。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 を、ロギング・カテゴリーcategory に記録します。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 category 。 には、Cのprintf()関数と同様に、追加の引数で置き換えられるプレースホルダを含めることができる。message
例
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, ...)
ロギング・カテゴリーcategory に警告メッセージ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. 本文書に含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。