RegisterTraceGuidsA 函式 (evntrace.h)

  • 發行項

RegisterTraceGuids函式會註冊傳統 (Windows 2000 樣式) ETW 事件追蹤提供者，以及用來產生事件的事件追蹤類別。 此函式也會指定系統用來啟用和停用提供者追蹤的回呼函式。

此函式已過時。 新的程式碼應該使用 EventRegister 來註冊 Windows Vista 樣式 (Crimson) ETW 事件追蹤提供者。

語法

ULONG WMIAPI RegisterTraceGuidsA(
  [in]      WMIDPREQUEST             RequestAddress,
  [in]      PVOID                    RequestContext,
  [in]      LPCGUID                  ControlGuid,
  [in]      ULONG                    GuidCount,
  [in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
  [in]      LPCSTR                   MofImagePath,
  [in]      LPCSTR                   MofResourceName,
  [out]     PTRACEHANDLE             RegistrationHandle
);

參數

[in] RequestAddress

當事件追蹤會話啟用或停用提供者時，可接收通知的 ControlCallback 函式指標。 EnableTrace函式會觸發此回呼。

[in] RequestContext

ETW 傳遞至 RequestAddress所指定函式的選擇性提供者定義內容指標。

[in] ControlGuid

控制註冊提供者的 GUID (提供者識別碼) 。

[in] GuidCount

TraceGuidReg陣列中的元素數目。 如果 TraceGuidReg 為 Null，請將此參數設定為 0。

[in, out] TraceGuidReg

陣列的指標
TRACE_GUID_REGISTRATION 結構。

每個元素都會識別提供者所提供的事件類別。

在輸入時，每個結構的 Guid 成員都包含註冊提供者指派的事件追蹤類別 GUID。 類別 GUID 會識別提供者所提供的事件類別。 提供者會在呼叫TraceEvent函式來記錄事件時，使用相同的類別 GUID 來設定EVENT_TRACE_HEADER的 Guid 成員。

輸出時， RegHandle 成員會收到事件的類別 GUID 註冊控制碼。 如果提供者呼叫TraceEventInstance函式，請使用TRACE_GUID_REGISTRATION的RegHandle成員來設定EVENT_INSTANCE_HEADER的RegHandle成員。

如果提供者只呼叫TraceEvent函式來記錄事件，這個參數可以是Null。 如果提供者呼叫 TraceEventInstance 函式來記錄事件，此參數不能是 Null。

[in] MofImagePath

不支援此參數。 設定為 Null。 您應該使用 Mofcomp.exe 在應用程式設定期間註冊 MOF 資源。 如需詳細資訊，請參閱 發佈事件架構。

具有 SP1、Windows XP 和 Windows 2000 的 Windows XP： 選擇性字串的指標，指定包含 MofResourceName所指定資源的 DLL 或可執行程式路徑。 如果事件提供者和取用者使用另一種機制來共用提供者所使用之事件追蹤類別的相關資訊，此參數可以是 Null 。

[in] MofResourceName

不支援此參數。 設定為 Null。 您應該使用 Mofcomp.exe 在應用程式設定期間註冊 MOF 資源。 如需詳細資訊，請參閱 發佈事件架構。

具有 SP1、Windows XP 和 Windows 2000 的 Windows XP： 指定 MofImagePath字串資源的選擇性字串指標。 字串資源包含二進位 MOF 檔案名，描述提供者所支援的事件追蹤類別。

[out] RegistrationHandle

接收提供者的註冊控制碼。 當您呼叫 UnregisterTraceGuids 函式時，請使用傳回的控制碼。

重要

DLL 或驅動程式所建立的所有註冊控制碼都必須在 DLL 或驅動程式卸載之前取消註冊。 如果未取消註冊提供者，ETW 嘗試叫用提供者的回呼時，就會發生當機。

傳回值

如果函式成功，傳回值會ERROR_SUCCESS。

如果函式失敗，傳回值就是其中一個 系統錯誤碼。 以下是一些常見的錯誤及其原因。

重要

 如果控制器呼叫EnableTrace以啟用提供者，而且提供者尚未呼叫RegisterTraceGuids，此函式也可以傳回ControlCallback所傳回的值。 發生這種情況時，如果註冊成功， RegisterTraceGuids 會傳回回呼的傳回值。

  • ERROR_INVALID_PARAMETER

    以下其中一項為正確：

    • RequestAddress 為 Null。
    • ControlGuid 為 Null。
    • RegistrationHandle 為 Null。

    Windows XP 和 Windows 2000：TraceGuidReg 為 Null 或 GuidCount 小於或等於零。

備註

注意

大部分開發人員都不會直接呼叫此函式。 相反地，開發人員通常會使用 ETW 架構。 例如，TMF 型 WPP 會代表您管理 RegisterTraceGuids、 TraceMessage和 UnregisterTraceGuids 的呼叫。

此函式會開啟傳統 (Windows 2000 樣式) 事件提供者控制碼，可用來透過TraceEvent、TraceEventInstance、TraceMessage 和 TraceMessageVa寫入 MOF 和 TMF 型 WPP ETW 事件。

注意

若要開啟 Windows Vista 樣式 提供者控制碼，以透過 EventWrite寫入以資訊清單為基礎的或 TraceLogging 型 ETW 事件，請使用 EventRegister。

如果提供者的 ControlGuid 先前已註冊並啟用，則會自動啟用參考相同 ControlGuid 的後續註冊。

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

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

範例

如需使用 RegisterTraceGuids 的範例，請參閱 撰寫傳統事件。

注意

evntrace.h 標頭會將 RegisterTraceGuids 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

需求

   
最低支援的用戶端 Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows 2000 Server [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntrace.h
程式庫 Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.lib;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.lib
Dll Windows 8.1和 Windows Server 2012 R2 上的 Sechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.dll

另請參閱

EnableTrace

UnregisterTraceGuids