OpenTraceA 函式 (evntrace.h)
OpenTrace 函式會開啟 ETW 追蹤處理句柄，以取用 ETW 實時追蹤會話或 ETW 記錄檔中的事件。
語法
PROCESSTRACE_HANDLE 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 |