SetupAPI のログ記録は、スレッドのログ コンテキストを確立するメカニズムをサポートします。 このコンテキストは、スレッドの ログ トークン を設定することによって確立されます。 SetupAPI は、スレッドによって呼び出されたコードが、呼び出し元スレッドのログ コンテキストにログ エントリを書き込むことができるように、このメカニズムを提供します。
たとえば、スレッドは、クラス インストーラーまたは共同インストーラーを呼び出す前に、ログ コンテキストのログ トークンを設定できます。 インストーラーは、呼び出し元スレッドのログ トークンを取得し、そのトークンを使用して、呼び出し元スレッドのログ コンテキストに関連付けられているテキスト ログとセクションにログ エントリを書き込むことができます。
スレッドのログ トークンの設定
SetupSetThreadLogToken 関数は、この関数が呼び出されたスレッドのログ トークンを設定します。 ログ トークンには、システム定義のログ トークン、または SetupGetThreadLogToken を呼び出して取得したログ トークンを指定できます。
スレッドのログ コンテキストを確立する方法の例を次に示します。
インストール アプリケーションは SetupSetThreadLogToken を呼び出して、同じスレッド内で実行される他のインストール コードのログ コンテキストを確立できます。 スレッドのログ コンテキストを確立するときに、アプリケーションは SetupSetThreadLogToken の呼び出しで、LOGTOKEN_SETUPAPI_APPLOG などのシステム定義 ログ トークン を使用する必要があります。
注: ログ コンテキストがシステム定義のログ トークンを使用して設定されている場合、そのログ コンテキストから行われる SetupAPI ログ関数の後続の呼び出しでは、テキスト ログ セクションの一部ではないインストール テキスト ログにログ エントリを書き込みます。
クラス インストーラーまたは共同インストーラーが新しいスレッドを開始した場合、インストーラーはそのスレッドのログ コンテキストを親スレッドと同じに設定できます。 これは、次の方法で行われます。
- 親スレッドが新しいスレッドを開始する前に、 SetupGetThreadLogToken を呼び出して現在のログ トークンを取得します。
- 親スレッドは新しいスレッドを開始し、グローバル変数にトークンを保存するなど、実装固有のメソッドを介して現在のログ トークンを渡します。
- 新しいスレッドは、現在のログ トークンを使用して SetupSetThreadLogToken を呼び出します。 その結果、新しいスレッドは親スレッドのログ コンテキストを "継承" します。
注: クラス インストーラーまたは共同インストーラーのスレッドがこのメソッドを使用してログ コンテキストを設定する場合、そのログ コンテキストから作成された SetupAPI ログ関数の後続の呼び出しは、テキスト ログ セクションの一部である可能性があるインストール テキスト ログにログ エントリを書き込みます。 これは、インストーラーを呼び出した SetupAPI インストール操作によってテキスト ログ セクションが確立された場合にのみ発生します。
次に示す SetupSetThreadLogToken の呼び出しの例を示します。この呼び出しでは、LOGTOKEN_SETUPAPI_APPLOGのシステム定義ログ トークンを指定して、現在のスレッドのログ コンテキストをデバイス インストール テキスト ログ (SetupAPI.app.log) に設定します。 このログ コンテキストを使用する SetupAPI ログ関数 の後続の呼び出しでは、ログ エントリがデバイス インストール テキスト ログに書き込まれますが、 テキスト ログ セクションの一部として書き込まれません。
SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);
スレッドのログ トークンの取得
SetupGetThreadLogToken 関数は、この関数が呼び出されたスレッドのログ トークンを取得します。
たとえば、クラス インストーラーは SetupGetThreadLogToken を呼び出して、クラス インストーラーを呼び出した SetupAPI 操作に適用されるログ トークンを取得できます。 クラス インストーラーは、この取得したログ トークンを使用して、対応する SetupAPI 操作に適用されるテキスト ログ内のエントリをログに記録できます。
注 スレッドのログ コンテキストが SetupSetThreadLogToken の呼び出しによって以前に設定されていない場合、 SetupGetThreadLogToken の呼び出しは、LOGTOKEN_UNSPECIFIEDの値を持つログ トークンを返します。
現在のスレッドのログ トークンを取得する SetupGetThreadLogToken の呼び出しの例を次に示します。
SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();