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 結構成員的值。

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

如果函式成功，傳回值會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

以下其中一項為正確：
- TraceHandle 為 Null。
- EventTrace 為 Null。
- EVENT_TRACE_HEADER結構的Size成員不正確。
ERROR_MORE_DATA

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

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

注意

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

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

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

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

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

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

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