設定和取得線程的記錄令牌

SetupAPI 記錄 支援為執行緒建立日誌上下文的機制。 透過為線程設置 記錄令牌 來建立此上下文。 SetupAPI 提供此機制，讓執行緒呼叫的程式代碼可以將日誌項目寫入呼叫執行緒的日誌上下文。

例如，執行緒可以在呼叫類別安裝器或共同安裝器之前，為其記錄內容設定記錄令牌。 安裝程式接著可以擷取呼叫線程的日誌令牌，並使用該令牌在與呼叫線程的日誌上下文相關聯的文字日誌和區段中寫入日誌條目。

在執行緒中設定記錄令牌

SetupSetThreadLogToken 函式會為呼叫此函式的線程設定記錄標記。 記錄令牌可以是系統定義的記錄令牌或藉由呼叫 SetupGetThreadLogToken 所擷取的記錄令牌。

以下是如何為線程建立記錄內容的範例：

• 安裝應用程式可以呼叫 SetupSetThreadLogToken ，為在相同線程內執行的其他安裝程式代碼建立記錄內容。 在建立線程的記錄內容時，應用程式應該在呼叫 SetupSetThreadLogToken 時，使用系統定義的 記錄令牌，例如 LOGTOKEN_SETUPAPI_APPLOG。

  注意 如果使用系統定義的 記錄令牌來設定記錄內容，則後續呼叫從該記錄內容所建立的 SetupAPI 記錄函 式，將記錄專案寫入安裝文字記錄檔，這不屬於 文字記錄區段。

• 如果類別安裝程式或共同安裝程序啟動新的線程，安裝程式可以將該線程的記錄內容設定為與父線程相同。 這會以下列方式完成：

  1. 在父線程啟動新線程之前，它會藉由呼叫 SetupGetThreadLogToken 來取得目前的記錄令牌。
  2. 父線程會啟動新的線程，並透過實作特定的方法傳遞目前的記錄令牌，例如將令牌儲存在全域變數中。
  3. 新的線程會呼叫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();