TraceLoggingRegister 函式 (traceloggingprovider.h)

發行項
03/03/2024

註冊 TraceLogging 提供者，以便用來記錄事件。註冊有效，直到提供者取消註冊或進程結束為止。

語法

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

參數

hProvider

要註冊之 TraceLogging 提供者的句柄。句柄必須尚未註冊。

傳回值

如果您從使用者模式程式代碼呼叫此函式，函式會傳 HRESULT回。 SUCCEEDED()使用宏來判斷函式是否成功。

如果您從內核模式程式代碼呼叫此函式，函式會 NTSTATUS傳回。 NT_SUCCESS()使用宏來判斷函式是否成功。

注意

TraceLoggingRegister 傳回的錯誤碼主要用於偵錯和診斷案例。即使 ETW 提供者無法註冊，大部分的生產程式代碼都應該繼續執行，因此發行組建通常應該忽略 TraceLoggingRegister 傳回的錯誤碼。

備註

當元件開始執行時，元件中的任何 TraceLogging 提供者句柄都會處於未註冊的狀態，而且任何嘗試使用提供者的句柄來產生事件，都會以無訊息方式忽略。在提供者可以寫入任何事件之前，您必須使用 TraceLoggingRegister 註冊提供者。您通常會在元件啟動期間執行此動作，例如在、wmain、WinMain、 DllMain(DLL_PROCESS_ATTACH)或 DriverEntry中main。在元件關機時，呼叫 TraceLoggingUnregister 來取消註冊提供者。

請勿在已註冊的提供者句柄上呼叫 TraceLoggingRegister 。您可以取消註冊句柄，然後視需要再次註冊，不過重複註冊和取消註冊句柄可能會造成效能問題，而且應該避免 (亦即不要註冊、寫入幾個事件，然後取消註冊;而是在元件啟動時註冊一次，並在元件關機時取消註冊) 。

TraceLoggingRegister 與相同句柄上的 TraceLoggingRegister 或 TraceLoggingUnregister 的其他呼叫無關安全。如果另一個線程可能同時在同一個句柄上呼叫 TraceLoggingRegister 或 TraceLoggingUnregister，請勿呼叫 TraceLoggingRegister。

如果 TraceLoggingRegister 失敗，提供者句柄會維持未註冊狀態，而且提供者句柄的所有用法都將是安全的無作業。特別是，使用未註冊的提供者句柄呼叫 TraceLoggingWrite 或 TraceLoggingUnregister 是安全的 no-op。

重要

如果您的 DLL 或驅動程式在提供者句柄上呼叫 TraceLoggingRegister ，它 必須在 該提供者句柄上呼叫 TraceLoggingUnregister ，才能卸除 DLL 或驅動程式。如果 DLL 卸除而不呼叫 TraceLoggingUnregister，進程後續可能會當機。如果驅動程式在未呼叫 TraceLoggingUnregister 的情況下卸除，系統後續可能會當機。 TraceLoggingRegister 函式會建立 ETW 組態回呼，而 TraceLoggingUnregister 會取消回呼。如果未取消回呼且模組卸除，則下次 ETW 嘗試叫用回呼時，就會發生當機。

警告

如果您的驅動程式呼叫 TraceLoggingRegister ，然後在 DriverEntry 期間遇到錯誤，它必須先呼叫 TraceLoggingUnregister ，再從 DriverEntry 傳回錯誤。如果驅動程式從 DriverEntry 傳回錯誤，而且呼叫 TraceLoggingUnregister 失敗會導致系統當機，則不會呼叫一般驅動程式清除例程。

TraceLoggingRegister 會執行下列動作：

呼叫 EventRegister 以開啟 ETW 的連線。
如果 EventRegister 成功，請使用 InformationClassEventProviderSetTraits 呼叫 TraceLoggingSetInformation 來設定 TraceLogging 支援的提供者。

對 TraceLoggingRegister 的呼叫與回呼和內容參數的 TraceLoggingRegisterEx 呼叫相同。如果您需要在會話啟用或停用提供者時收到 ETW 啟用回呼，請使用 TraceLoggingRegisterEx。

規格需求

需求	值
最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
標頭	traceloggingprovider.h
程式庫	Advapi32.lib