共用方式為


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_HEADERFlags成員不包含WNODE_FLAG_TRACED_GUID

  • ERROR_OUTOFMEMORY

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

  • ERROR_INVALID_PARAMETER

    以下其中一項為正確:

    • EventTraceNull
    • pInstInfoNull
    • pInstInfo的成員為Null
    • TraceHandleNull
    • 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。

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

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

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

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

Windowsxp: 無法正常運作。

範例

如需使用 CreateTraceInstanceIdTraceEventInstance產生相關事件集的範例,請參閱 追蹤事件實例

需求

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

另請參閱

CreateTraceInstanceId

EVENT_INSTANCE_HEADER

EVENT_INSTANCE_INFO

RegisterTraceGuids

TraceEvent