EventRegister 函式 (evntprov.h)

  • 發行項

註冊 ETW 事件提供者，建立可用來寫入 ETW 事件的控制碼。

語法

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

參數

[in] ProviderId

可唯一識別提供者的 GUID，有時稱為控制項 GUID。 這必須是穩定的識別碼，讓追蹤控制器可以使用 GUID 來訂閱來自此提供者的事件。

[in, optional] EnableCallback

當追蹤會話啟用或停用此提供者時，ETW 將叫用的選擇性 EnableCallback 。 若不需要回呼，請使用 NULL 。

[in, optional] CallbackContext

在叫用 EnableCallback時，ETW 會提供的選擇性內容資料。 如果需要回呼內容，請使用 NULL 。

[out] RegHandle

接收事件提供者註冊控制碼。 控制碼用於後續呼叫提供者 API，例如 EventWrite、 EventProviderEnabled和 EventRegister。

在提供者卸載或結束之前，請呼叫 EventUnregister釋放提供者註冊控制碼。 卸載而不釋放所有已註冊提供者控制碼的 DLL，可能會導致進程當機。

傳回值

如果成功 ， 則傳回ERROR_SUCCESS。

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

備註

EventRegister會建立控制碼，讓您可用來透過EventWrite、EventWriteTransfer 或 EventWriteEx寫入ETW 事件。

注意

大部分的事件提供者都不會直接呼叫 EventRegister 。 相反地，大部分的事件提供者都是使用 ETW 架構來實作，以包裝 對 EventRegister、 EventWrite和 EventUnregister的呼叫。 例如，您可以 撰寫事件資訊清單 ，然後使用 訊息編譯 程式為事件產生 C/C++ 程式碼，或者您可以使用 TraceLogging 來避免資訊清單的需求。

事件提供者的註冊不應與事件提供者資訊清單的安裝混淆。

  • EventRegister API 會執行事件提供者的註冊，以建立提供者控制碼。 這是進程範圍作業， (控制碼只在進程) 內有效。 控制碼可用來寫入 ETW 事件。 使用控制碼撰寫的所有事件都會以提供者註冊期間指定的 ProviderId 標記。 不需要安裝資訊清單來寫入事件或擷取追蹤 (但安裝資訊清單可能需要解碼提供者的事件，或提供者才能使用事件記錄檔) 。
  • wevtutil.exe工具可用來安裝或卸載事件提供者的資訊清單。 事件提供者資訊清單的安裝表示會記錄來自資訊清單的資訊。 記錄的資訊是系統全域的，而且會持續存在，直到卸載資訊清單為止。 記錄的資訊包括資訊清單中定義之提供者的名稱、GUID、通道和資源 DLL 路徑。 來自資訊清單的資訊是由追蹤解碼工具和事件記錄檔使用。

大部分元件會在元件初始化時註冊其事件提供者，並在元件關機時取消註冊其事件提供者。 例如，應用程式 (EXE) 可能會在應用程式啟動期間註冊，並在應用程式結束期間取消註冊。 動態連結程式庫 (DLL) 可能會在進程附加期間註冊， DllMain 而且可能會在進程中斷連結期間取消 DllMain 註冊。

由於事件追蹤是偵錯/診斷考慮，而且通常不是應用程式關鍵功能，因此大部分零售應用程式應該以無訊息方式忽略 EventRegister傳回的失敗。 如果失敗， EventRegister 會將 RegHandle 參數設定為零，以便後續使用 RegHandle (，也就是在 呼叫 EventWrite 和 EventUnregister) 時，將不會有任何作用。

每個進程最多可以註冊 1，024 個提供者。 不過，您應該將元件註冊的提供者數目限制為一或兩個。 此限制包括使用此函式註冊的提供者，以及使用 RegisterTraceGuids 註冊的提供者。

在 Windows Vista 之前： 進程可以註冊的提供者數目沒有特定限制。

需求

   
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntprov.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

EnableCallback

EventWrite

EventUnregister