スレッド用のログ トークンの設定と取得

  • [アーティクル]

SetupAPI ログは 、スレッドのログ コンテキストを確立するメカニズムをサポートします。 このコンテキストは、スレッドのログ トークンを設定することによって確立されます。 SetupAPI は、スレッドによって呼び出されたコードが、呼び出し元スレッドのログ コンテキストにログ エントリを書き込むことができるように、このメカニズムを提供します。

たとえば、スレッドは、クラス インストーラーまたは共同インストーラーを呼び出す前に、ログ コンテキストのログ トークンを設定できます。 インストーラーは、呼び出し元スレッドのログ トークンを取得し、そのトークンを使用して、呼び出し元スレッドのログ コンテキストに関連付けられているテキスト ログとセクションにログ エントリを書き込むことができます。

スレッドのログ トークンの設定

SetupSetThreadLogToken 関数は、この関数の呼び出し元のスレッドのログ トークンを設定します。 ログ トークンには、システム定義のログ トークン、または SetupGetThreadLogToken を呼び出して取得したログ トークンを指定できます。

スレッドのログ コンテキストを確立する方法の例を次に示します。

  • インストール アプリケーションは、SetupSetThreadLogToken を呼び出して、同じスレッド内で実行される他のインストール コードのログ コンテキストを確立できます。 アプリケーションは、スレッドのログ コンテキストを確立するときに、SetupSetThreadLogToken の呼び出しで、LOGTOKEN_SETUPAPI_APPLOG のようなシステム定義のログ トークンを使用する必要があります。

    注: ログ コンテキストがシステム定義のログ トークンを使用して設定されている場合、そのログ コンテキストから行われる SetupAPI ログ関数の後続の呼び出しでは、テキスト ログ セクションの一部ではないインストール テキスト ログにログ エントリを書き込みます。

  • クラス インストーラーまたは共同インストーラーが新しいスレッドを開始した場合、インストーラーはそのスレッドのログ コンテキストを親スレッドと同じに設定できます。 これは、次の方法で行われます。

    1. 親スレッドが新しいスレッドを開始する前に、SetupGetThreadLogToken を呼び出して現在のログ トークンを取得します。
    2. 親スレッドは新しいスレッドを開始し、グローバル変数にトークンを保存するなど、実装固有のメソッドを介して現在のログ トークンを渡します。
    3. 新しいスレッドは、現在のログ トークンを使用して SetupSetThreadLogToken を呼び出します。 その結果、新しいスレッドは親スレッドのログ コンテキストを 「継承」 します。

    注: クラス インストーラーまたは共同インストーラーのスレッドがこのメソッドを使用してログ コンテキストを設定する場合、そのログ コンテキストから作成された SetupAPI ログ関数の後続の呼び出しは、テキスト ログ セクションの一部である可能性があるインストール テキスト ログにログ エントリを書き込みます。 これは、インストーラーを呼び出した SetupAPI インストール操作によってテキスト ログ セクションが確立された場合にのみ発生します。

次に示す SetupSetThreadLogToken の呼び出しの例では、LOGTOKEN_Standard Edition TUPAPI_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();