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 Professional [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	evntrace.h
Library	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