traceEventInstance 函式 (evntrace.h)

發行項
03/11/2023

RegisterTraceGuids型 (「傳統」) 事件提供者會使用TraceEventInstance函式，將結構化事件傳送至具有實例識別碼的事件追蹤會話。

事件會使用實例識別碼，將事件與交易產生關聯。此函式也可用來追蹤相關事件之間的階層式關聯性。

語法

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

參數

[in] TraceHandle

處理記錄事件實例的事件追蹤會話。提供者在其ControlCallback實作中呼叫GetTraceLoggerHandle函式時，會取得控制碼。

[in] EventTrace

EVENT_INSTANCE_HEADER結構的指標。事件特定資料選擇性地附加至結構。您可以記錄的最大事件是 64K。您必須指定 下列EVENT_INSTANCE_HEADER 結構成員的值。

大小
旗標
RegHandle

根據提供者提供的資訊複雜度，您也應該考慮為下列成員指定值。

Class.Type
Class.Level

若要追蹤相關事件之間的階層式關聯性，也請設定 ParentRegHandle 成員。

[in] InstInfo

EVENT_INSTANCE_INFO結構的指標，其中包含這個事件追蹤類別和實例識別碼的註冊控制碼。使用 CreateTraceInstanceId 函式來初始化結構。

[in] ParentInstInfo

EVENT_INSTANCE_INFO結構的指標，其中包含父事件追蹤類別及其實例識別碼的註冊控制碼。使用 CreateTraceInstanceId 函式來初始化結構。如果您未追蹤階層式關聯性，請將設定為 Null 。

傳回值

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

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

ERROR_INVALID_FLAGS

EVENT_INSTANCE_HEADER的Flags成員不包含WNODE_FLAG_TRACED_GUID。
ERROR_OUTOFMEMORY

記憶體不足，無法完成函式呼叫。下列一節說明此錯誤碼的原因。
ERROR_INVALID_PARAMETER

以下其中一項為正確：
- EventTrace 為 Null。
- pInstInfo 為 Null。
- pInstInfo的成員為Null。
- TraceHandle 為 Null。
- EVENT_INSTANCE_HEADER的大小成員不正確。
ERROR_INVALID_HANDLE

TraceHandle 無效，或指定 NT 核心記錄器會話控制碼。
ERROR_NOT_ENOUGH_MEMORY

工作階段的可用寫入緩衝區不足。當事件發生率偏高時，就會發生這種情形，而原因則是磁碟子系統已超載，或是緩衝區數目太少。 TraceEvent會捨棄事件，而不是封鎖直到有更多緩衝區可用為止。

Windows 2000 和 Windows XP： 不支援。
ERROR_OUTOFMEMORY

事件會被捨棄，因為雖然緩衝集區尚未達到其大小上限，但記憶體不足，無法配置額外的緩衝區，而且沒有緩衝區可供接收事件。
ERROR_MORE_DATA

來自單一事件的資料無法跨越多個緩衝區。追蹤事件受限於事件追蹤會話緩衝區的大小減去 EVENT_INSTANCE_HEADER 結構的大小。

備註

MOF 型 ETW 提供者會呼叫此函式。

注意

大部分的開發人員都不會呼叫此函式。此 API 支援 MOF 型 ETW，但 MOF 型 ETW 已被取代為以資訊清單為基礎的 ETW。此外，大部分的 MOF 型提供者都會使用由 MC.exe 所產生的包裝函式，而不是直接呼叫 ETW API。

提供者必須先呼叫此函式，提供者才能呼叫此函式

必須呼叫 RegisterTraceGuids 函式來註冊本身和事件追蹤類別。
必須呼叫 CreateTraceInstanceId 函式，以建立已註冊事件追蹤類別的實例識別碼。
必須啟用。控制器會呼叫 EnableTrace 函式來啟用提供者。

事件會寫入記錄檔、即時傳送至事件追蹤取用者，或同時傳送至事件追蹤取用者。傳遞至StartTrace之EVENT_TRACE_PROPERTIES結構的LogFileMode成員會定義事件傳送的位置。

追蹤事件會以發生的順序寫入。

若要追蹤不相關的事件，請使用 TraceEvent 函式。

Windowsxp： 無法正常運作。

範例

如需使用 CreateTraceInstanceId 和 TraceEventInstance產生相關事件集的範例，請參閱追蹤事件實例。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	evntrace.h
程式庫	Advapi32.lib
Dll	Advapi32.dll