インデントされたログ エントリの記述

「テキスト ログ セクション 本文のフォーマット」 の説明の通り、SetupAPI テキスト ログのセクション本文ログ エントリのフォーマットは、次のフィールドから成ります。

entry_prefix time_stamp event_category indentation formatted_message

ログ エントリでインデント フィールドを使用すれば、formatted_message フィールドにインデントを含むことで、ログ エントリが読みやすく、理解しやすくなります。 インデント フィールドのインデントの量は、セクションに対して設定されているインデントの深さによって異なります。 インデントの深さはインデント単位の数で、インデント単位は 5 つのモノスペース テキストスペースです。 たとえば、インデントの深さが 1 の場合、インデントは 5 スペースになり、インデントの深さが 2 の場合、インデントは 10 スペースになります。 最小インデントの深さは 0 で、最大インデントの深さは 16 です。

既定では、セクションのインデントの深さは 0 です。 インデントの深さが 0 の場合、 formatted_message フィールドにインデントは挿入されません。 アプリケーションが、インデントの深さを増して、インデント入りのセクション エントリのシーケンスを書き込む場合、アプリケーションは、対応するセクション エントリのセットも書き込み、インデントの深さをゼロにリセットする必要があります。そうした上で、アプリケーションは、インデントなしのセクション エントリをさらにに書き込めます。

セクションのインデントの深さを変更するには、SetupAPI ログ関数を呼び出し、以下のシステム定義記号定数のいずれか 1 つと SetupAPI ログ関数に指定された flags パラメーターに対し、ビット単位の OR 演算を使用します。

記号定数	インデントの深さの変更
TXTLOG_DEPTH_INCR	インデントの深さが、現在のログ エントリとその後のすべてのログ エントリに対して 1 増やされる。
TXTLOG_DEPTH_DECR	インデントの深さが、現在のログ エントリとその後のすべてのログ エントリに対して 1 減らされる。
TXTLOG_TAB_1	インデントの深さが、現在のログ エントリに対してのみ 1 増やされる。

たとえば、以下のSetupWriteTextLog3 への一連の呼び出しにより、section_title フィールドが 「インデントの例」 で、instance_identifier フィールドが 「Instance 0」 であるセクション ヘッダーの後に、インデント入りログ エントリのシーケンスが書き込まれます。

// The LogToken value was previously returned by a call to 
// SetupGetThreadLogToken.
// The LogToken value specifies a section in one of the text logs.

DWORD Category = TXTLOG_VENDOR; 
DWORD Flags = TXTLOG_DETAILS;

SetupWriteTextLog(LogToken, Category, Flags, TEXT("Subsection A"));

// Additional SetupWriteTextLog calls that write entries at Subsection A indentation level

SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_INCR, TEXT("Subsection A.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A.1 indentation level

SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_INCR, TEXT("Subsection A.1.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A.1.1 indentation level

SetupWriteTextLog(LogToken, Category, Flags, TEXT("End of Subsection A.1.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A.1 indentation level

SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_DECR, TEXT("End of Subsection A.1"));

// Additional SetupWriteTextLog calls that write entries at Subsection A indentation level
SetupWriteTextLog(LogToken, Category, Flags | TXTLOG_DEPTH_DECR, TEXT("End of Subsection A"));

テキスト ログのイベント レベルが TXTLOG_DETAILS 以上で、テキスト ログに対してイベント カテゴリ TXTLOG_VENDORが有効になっている場合、前のコードはセクション ヘッダーの後に次のログ エントリを書き込みます。

次の例では、省略記号 (...) は、前のログ エントリと同じレベルのインデントで、0 個以上の追加のログ エントリがあることを表します。 タイム スタンプは、実際のタイム スタンプに置き換えられます。

>>>  [Indentation Example - Instance 0]
>>>  2005/02/13 22:06:28.109: Section start
        : Subsection A
...
        :      Subsection A.1
...
        :           Subsection A.1.1
...
        :           End Subsection A.1.1
...
        :      End of Subsection A.1
...
        : End of Subsection A

実際のテキスト ログから取得されたインデント入りセクション エントリの別の例は、「テキスト ログ セクション本文のフォーマット」をご覧ください。