traceEventInstance 函式 (evntrace.h)
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 |