ProcessTrace 函式 （evntrace.h）

ProcessTrace 函式會將事件從一或多個 ETW 追蹤處理會話傳遞至取用者。

語法

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PROCESSTRACE_HANDLE *HandleArray,
  [in] ULONG               HandleCount,
  [in] LPFILETIME          StartTime,
  [in] LPFILETIME          EndTime
);

參數

[in] HandleArray

從先前呼叫 OpenTrace 函式取得的追蹤處理會話句柄陣列的指標。

陣列最多可以包含 64 個檔案處理會話的控制碼，也可以包含一個即時處理會話的控制碼。 陣列不能同時包含檔案處理會話控制碼和即時處理會話控制碼。

[in] HandleCount

HandleArray 中的元素數目。

[in] StartTime

選擇性 FILETIME 結構的指標，指定您要接收事件的開始時段。 函式不會傳遞時間戳記在 StartTime 之前的事件。

[in] EndTime

選擇性 FILETIME 結構的指標，指定您要接收事件的結束時段。 函式不會傳遞 EndTime 之後具有時間戳記的事件。

Windows Server 2003： 即時事件傳遞會忽略此值。

返回值

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

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

• ERROR_BAD_LENGTH

  HandleCount 無效，或控制碼數目大於 64。

• ERROR_INVALID_HANDLE

  HandleArray 的元素不是有效的事件追蹤會話控制碼。

• ERROR_INVALID_TIME

  EndTime 小於 StartTime。

• ERROR_INVALID_PARAMETER

  HandleArray 為 NULL，同時包含檔案處理工作階段和即時處理工作階段，或包含多個即時處理工作階段。

• ERROR_NOACCESS

  接收事件的其中一個回呼函式中發生例外狀況。

• ERROR_CANCELLED

  指出取用者在其 BufferCallback 函式中傳回 FALSE 來取消處理。

• ERROR_WMI_INSTANCE_NOT_FOUND

  您嘗試從中即時取用事件的追蹤收集階段作業未執行，或未啟用即時追蹤模式。

備註

追蹤取用者會呼叫此函式，以處理來自一或多個追蹤處理會話的事件。 此功能會封鎖，直到處理結束為止。

呼叫 ProcessTrace 之前，請使用 OpenTrace 開啟控制碼以追蹤處理會話。

ProcessTrace 函式會叫用取用者的 BufferCallback、EventCallback 和 EventRecordCallback 回呼函式，從會話傳遞事件。

ProcessTrace 函式會嘗試根據事件的時間戳記依序傳遞事件 （亦即，它會嘗試從最舊到最新的傳遞事件）。 在某些情況下， ProcessTrace 可能會以順序傳遞事件。

• 如果在追蹤收集期間向後調整用於事件時間戳記的時鐘，則事件的遞送順序無法預測。 若要避免此問題，請在收集追蹤時使用 QPC 時鐘 ，而不是系統時鐘。
• 如果在不同 CPU 上收集具有相同時間戳記的多個事件，則事件的傳遞順序是無法預測的。
• 如果事件具有無效的時間戳記 （例如，由於檔案損毀） ，則該事件和追蹤中其他事件的傳遞順序可能無法預測。

ProcessTrace 函式會封鎖執行緒，直到它傳遞所有事件、BufferCallback 函式傳回 FALSE，或您呼叫 CloseTrace。 此外，如果取用者即時取用事件，則 ProcessTrace 函式會在控制器停止追蹤會話之後傳回。 （請注意，在函數返回之前可能會有幾秒鐘的延遲。

Windows Server 2003：只有在 ProcessTrace 傳回之後，您才能呼叫 CloseTrace。

範例

如需使用 ProcessTrace 的範例，請參閱 使用 TdhFormatProperty 取用事件資料。

需求

另請參閱

緩衝區回呼

事件回呼

事件記錄回呼

開放追蹤