ProcessTrace 函式 (evntrace.h)

  • 發行項

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

語法

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PTRACEHANDLE 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 取用事件資料。

需求

   
最低支援的用戶端 Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows 2000 Server [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntrace.h
程式庫 Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.lib;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.lib
Dll Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.dll;windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 和 Windows XP 上的 Advapi32.dll

另請參閱

BufferCallback

EventCallback

EventRecordCallback

OpenTrace