OpenTraceA 函式 (evntrace.h)

  • 發行項

OpenTrace 函式會開啟 ETW 追蹤處理句柄，以取用 ETW 實時追蹤會話或 ETW 記錄檔中的事件。

語法

TRACEHANDLE WMIAPI OpenTraceA(
  [in, out] PEVENT_TRACE_LOGFILEA Logfile
);

參數

[in, out] Logfile

EVENT_TRACE_LOGFILE 結構的指標。 結構會指定要從 ETW 記錄檔或即時 ETW 工作階段 (取用事件的來源) ，並指定取用者想要用來接收事件的回呼。 成功時， OpenTrace 會使用開啟的檔案或會話中的資訊來更新結構。

傳回值

如果函式成功，它會傳回追蹤處理句柄。 應該使用 CloseTrace 關閉句柄。

如果函式失敗，它會傳回 INVALID_PROCESSTRACE_HANDLE。 (INVALID_PROCESSTRACE_HANDLE 相當於 (UINT64)UINTPTR_MAX.)

注意

在 Windows Vista 之前，OpenTrace 會在失敗時傳 UINT64_MAX 回。 如果您的程式代碼同時支援舊版操作系統 (Windows XP 或 Windows Server 2003) 和更新版本的 Windows (Windows Vista 和更新版本) ，您必須判斷您執行所在的操作系統，並將傳回值與適當的值進行比較。

作業系統 進程類型 指出失敗的值
在 Windows Vista 之前 32 位或64位 0XFFFFFFFFFFFFFFFF = UINT64_MAX
Windows Vista 或更新版本 32 位元 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX
Windows Vista 或更新版本 64 位元 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX

如果函式失敗，您可以使用 GetLastError 函式來取得擴充的錯誤資訊。 以下是一些常見的錯誤及其原因。

  • ERROR_INVALID_PARAMETER

    Logfile 參數為 NULL。

  • ERROR_BAD_PATHNAME

    如果您未指定 EVENT_TRACE_LOGFILE的 LoggerName 成員，則必須指定有效的記錄檔名稱。

  • ERROR_ACCESS_DENIED

    只有具有系統管理許可權、效能記錄使用者群組中的使用者，以及以LocalSystem、LocalService、NetworkService 執行的服務，才能即時取用事件。 若要授與受限制的用戶即時取用事件的能力，請將事件新增至效能記錄使用者群組。

    Windows XP 和 Windows 2000： 任何人都可以取用即時事件。

備註

追蹤取用者會呼叫此函式來開啟追蹤處理會話。

呼叫 OpenTrace 之後，請呼叫 ProcessTrace 函式來處理事件。 當您完成處理事件時，請呼叫 CloseTrace 函式以關閉追蹤處理句柄。

範例

如需使用 OpenTrace 的範例，請參閱 使用 TdhFormatProperty 取用事件數據。

注意

evntrace.h 標頭會將 OpenTrace 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求 值
最低支援的用戶端 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

另請參閱

CloseTrace

EVENT_TRACE_LOGFILE

ProcessTrace