共用方式為

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]     TRACEGUID_HANDLE         *RegistrationHandle
);

參數

[in] RequestAddress

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

[in] RequestContext

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

[in] ControlGuid

控制註冊提供者的 GUID （提供者識別符）。

[in] GuidCount

TraceGuidReg 陣列中的元素數目。 如果 TraceGuidRegNULL，請將此參數設定為 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_HEADERRegHandle 成員。

如果提供者只呼叫 TraceEvent 函式來記錄事件，這個參數就可以 NULL。 如果提供者呼叫 TraceEventInstance 函式來記錄事件，則此參數無法 NULL。

[in] MofImagePath

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

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

[in] MofResourceName

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

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

[out] RegistrationHandle

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

重要

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

傳回值

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

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

重要

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

  • ERROR_INVALID_PARAMETER

    下列其中一項成立：

    • RequestAddressNULL。
    • ControlGuidNULL。
    • RegistrationHandleNULL。

    Windows XP 和 Windows 2000：TraceGuidRegNULL 或 GuidCount 小於或等於零。

言論

注意

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

此函式會開啟 傳統（Windows 2000 樣式）事件提供者句柄，可用來 透過 traceEvent、TraceEventInstance、TraceMessage和 TraceMessageVa撰寫 MOF 和 TMF 型 WPP ETW 事件。

注意

若要透過 EventWrite開啟 Windows Vista 樣式 提供者句柄，請使用 EventRegister寫入指令清單式或 TraceLogging 型 ETW 事件。

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

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

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

例子

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

注意

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

要求

要求 價值
最低支援的用戶端 Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式]
支援的最低伺服器 Windows 2000 Server [傳統型應用程式 |UWP 應用程式]
目標平臺 窗戶
標頭 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 Sechost.dll Windows 8.1 和 Windows Server 2012 R2;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.dll

另請參閱

EnableTrace

UnregisterTraceGuids