設定和取得執行緒的記錄權杖

  • 發行項

SetupAPI 記錄 支援建立執行緒記錄內容的機制。 建立此內容的方式是設定執行緒的 記錄權杖 。 SetupAPI 提供這項機制，讓執行緒呼叫的程式碼可以將記錄專案寫入呼叫執行緒的記錄內容。

例如，執行緒可以在呼叫類別安裝程式或共同安裝程式之前，為其記錄內容設定記錄權杖。 安裝程式接著可以擷取呼叫執行緒的記錄權杖，並使用該權杖在與呼叫執行緒記錄內容相關聯的文字記錄檔和區段中寫入記錄專案。

設定執行緒的記錄權杖

SetupSetThreadLogToken函式會設定呼叫此函式之執行緒的記錄權杖。 記錄權杖可以是系統定義的記錄權杖，或呼叫 SetupGetThreadLogToken所擷取的記錄權杖。

以下是如何為執行緒建立記錄內容的範例：

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

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

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

    1. 在父執行緒啟動新執行緒之前，它會呼叫 SetupGetThreadLogToken來取得目前的記錄權杖。
    2. 父執行緒會啟動新的執行緒，並透過實作特定的方法傳遞目前的記錄權杖，例如將權杖儲存在全域變數中。
    3. 新的執行緒會使用目前的記錄權杖呼叫 SetupSetThreadLogToken 。 因此，新的執行緒會「繼承」父執行緒的記錄內容。

    注意 如果類別安裝程式或共同安裝程式的執行緒使用此方法設定記錄內容，後續呼叫從該記錄內容寫入記錄專案的 SetupAPI 記錄函 式，到可能是 文字記錄區段一部分的安裝文字記錄檔。 只有在呼叫安裝程式的 SetupAPI 安裝作業已建立文字記錄區段時，才會發生這種情況。

以下是 呼叫 SetupSetThreadLogToken 的範例，此呼叫會將目前線程的記錄內容設定為裝置安裝文字記錄檔， (SetupAPI.app.log) ，方法是指定系統定義的記錄標記LOGTOKEN_SETUPAPI_APPLOG。 後續呼叫使用這個記錄內容的 SetupAPI 記錄函 式，會將記錄專案寫入裝置安裝文字記錄檔，但不會作為 文字記錄區段的一部分。

SP_LOG_TOKEN LogToken = LOGTOKEN_SETUPAPI_APPLOG;
SetupSetThreadLogToken(LogToken);

取得執行緒的記錄權杖

SetupGetThreadLogToken函式會擷取呼叫此函式之執行緒的記錄權杖。

例如，類別安裝程式可以呼叫 SetupGetThreadLogToken 來擷取適用于呼叫類別安裝程式之 SetupAPI 作業的記錄權杖。 然後，類別安裝程式可以使用這個擷取的記錄標記來記錄適用于對應 SetupAPI 作業的文字記錄檔中的專案。

注意 如果先前未透過 呼叫 SetupSetThreadLogToken來設定執行緒的記錄內容， 則對 SetupGetThreadLogToken 的呼叫會傳回具有值 LOGTOKEN_UNSPECIFIED 的記錄權杖。

以下是 呼叫 SetupGetThreadLogToken 的範例，其會擷取目前線程的記錄權杖。

SP_LOG_TOKEN LogToken = SetupGetThreadLogToken();