共用方式為


TraceEvent 函式 (evntrace.h)

RegisterTraceGuids型 (「傳統」) 事件提供者會使用TraceEvent函式,將結構化事件傳送至事件追蹤會話。

語法

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

參數

[in] TraceHandle

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

[in] EventTrace

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

  • 大小
  • GuidGuidPtr
  • 旗標

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

  • Class.Type
  • Class.Level

傳回值

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

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

  • ERROR_INVALID_FLAG_NUMBER

    EVENT_TRACE_HEADER結構的Flags成員不正確。

  • ERROR_INVALID_HANDLE

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

  • ERROR_NOT_ENOUGH_MEMORY

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

    請考慮增加工作階段的緩衝區大小和數目,或是減少寫入的事件數目或事件的大小。

    Windows 2000: 不支援。

  • ERROR_OUTOFMEMORY

    事件會捨棄,因為雖然緩衝集區未達到其大小上限,但沒有足夠的可用記憶體來配置額外的緩衝區,而且沒有緩衝區可供接收事件。

  • ERROR_INVALID_PARAMETER

    以下其中一項為正確:

    • TraceHandleNull
    • EventTraceNull
    • EVENT_TRACE_HEADER結構的Size成員不正確。
  • ERROR_MORE_DATA

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

備註

以 MOF 為基礎的 ETW 提供者會呼叫此函式。

注意

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

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

  • 必須呼叫 RegisterTraceGuids 函式來註冊本身和事件追蹤類別。
  • 必須啟用。 控制器會呼叫 EnableTrace 函式來啟用提供者。

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

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

若要追蹤一組相關的事件,請使用 TraceEventInstance 函式。

在 Windows Vista 上,您應該使用 EventWrite 函式來記錄事件。

範例

如需使用 TraceEvent的範例,請參閱 追蹤事件

需求

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

另請參閱

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance