共用方式為

EtwRegister 函式 （wdm.h）

  • 發行項

EtwRegister 函式會註冊事件提供者，而且必須先呼叫提供者，提供者才能開始追蹤。 EtwRegister 函式是與 user-mode EventRegister 函式的核心模式對應專案。 函式也可以提供選擇性回呼函式的指標，可用來提供額外的事件篩選功能。

語法

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

參數

[in] ProviderId

事件提供者 GUID 的指標。

[in, optional] EnableCallback

選擇性回呼函式的指標。 回呼函式提供額外的事件篩選功能。 回呼函式是用戶定義的。

[in, optional] CallbackContext

函式會在進行回呼時傳回選擇性回呼內容。 您可以在註冊提供者時指定選擇性內容。 CallbackContext 參數支援多個提供者共用一個回呼的案例，就像在 C++ 類別中一樣。 CallbackContext 提供一種方式來區分啟用回呼的目標提供者實例。

[out] RegHandle

如果函式呼叫成功，接收提供者註冊句柄的變數指標。

傳回值

EtwRegister 函式會從下列清單中傳回狀態代碼：

傳回碼 描述
STATUS_SUCCESS
指出事件提供者已成功向 ETW 註冊。
STATUS_INVALID_PARAMETER
表示參數無效。
STATUS_Xxx
表示要求因為 NTSTATUS 值所指定的原因而失敗。 如需實際狀態傳回碼的詳細資訊，請參閱 Ntstatus.h。

言論

在內核模式驅動程式可以追蹤事件之前，驅動程式必須使用 EtwRegister 函式註冊為事件提供者。 當核心模式驅動程式呼叫 EtwRegister時，函式會傳回註冊句柄。 此註冊句柄可用來測試是否為特定提供者啟用關鍵詞或層級，以及呼叫事件追蹤和記錄函式。 追蹤完成之後，驅動程式必須呼叫 EtwUnregister 函式來取消註冊提供者。 對於每個呼叫 EtwRegister 必須有對應的呼叫，才能 EtwUnregister。 當卸除進程時，無法取消註冊事件提供者可能會導致錯誤，因為與進程相關聯的回呼函式不再有效。 不應該呼叫落在由 EtwRegister 系結的程式代碼之外，EtwUnregister 函式。 為了獲得最佳效能，您可以在 DriverEntry 例程中呼叫 EtwRegister 函式，並在 DriverUnload 例程中呼叫 EtwUnregister 函式。

EtwRegister 的呼叫端必須在系統線程的內容中於 IRQL = PASSIVE_LEVEL執行。

要求

要求 價值
最低支援的用戶端 適用於 Windows Vista 和更新版本的 Windows。
目標平臺 普遍
標頭 wdm.h （包括 Wdm.h、 Ntddk.h）
連結庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIs（storport），PowerIrpDDis（wdm）

另請參閱

EtwUnregister