etwRegister 函式 (wdm.h)

  • 發行項

EtwRegister 函式會註冊事件提供者，而且必須先呼叫，提供者才能開始追蹤。 EtwRegister 函式是與使用者模式 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 函式會從下列清單中傳回狀態代碼：

傳回碼 Description
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 中使用。
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)

另請參閱

EtwUnregister