ControlTraceW

ControlTraceW (Unicode) 関数 (evntrace.h) は、指定したイベントトレースセッションをフラッシュ、問い合わせ、更新、または停止する。

ControlTraceW TraceHandle, InstanceName, Properties, ControlCode

TraceHandle : [int] イベントトレースセッションへのハンドル、または 0。_InstanceName_ が **NULL** の場合は 0 以外の _TraceHandle_ を指定する必要がある。_InstanceName_ が **NULL** でない場合、ETW はハンドルを無視する。[StartTrace](/windows/win32/api/evntrace/nf-evntrace-starttracew) 関数は新しいトレースが開始されるとこのハンドルを返す。既存のトレースのハンドルを取得するには、**ControlTrace** を使ってトレース名に基づきトレースプロパティを問い合わせ、返された `EVENT_TRACE_PROPERTIES` データの **Wnode.HistoricalContext** フィールドからハンドルを取得する。
InstanceName : [wstr] イベントトレースセッションの名前、または **NULL**。_TraceHandle_ が 0 の場合は _InstanceName_ を指定する必要がある。NT カーネルロガーセッションを指定するには、_InstanceName_ を **KERNEL_LOGGER_NAME** に設定する。
Properties : [var] 初期化済みの [EVENT_TRACE_PROPERTIES](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties) 構造体へのポインタ。この構造体はフィールドを設定する前にゼロクリアしておく必要がある。_ControlCode_ が **EVENT_TRACE_CONTROL_STOP**、**EVENT_TRACE_CONTROL_QUERY**、または **EVENT_TRACE_CONTROL_FLUSH** を指定する場合、[EVENT_TRACE_PROPERTIES](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties) 構造体の **Wnode.BufferSize**、**Wnode.Guid**、**LoggerNameOffset**、**LogFileNameOffset** メンバのみ設定すればよい。セッションがプライベートセッションの場合は **LogFileMode** も設定する必要がある。バッファサイズとオフセットを算出する際に不明な場合は、最大セッション名長 (1024 文字) と最大ログファイル名長 (1024 文字) を使用できる。_ControlCode_ が **EVENT_TRACE_CONTROL_UPDATE** を指定する場合、入力時のメンバには更新するプロパティの新しい値を指定する必要がある。出力時、_Properties_ にはイベントトレースセッションのプロパティと統計情報が格納される。以下のプロパティを更新できる。- **EnableFlags**: すべてのシステムプロバイダを無効化するには 0 を設定する。有効化または有効な状態を維持したいシステムプロバイダを指定するには 0 以外の値を設定する。これは [システムロガー](/windows/win32/api/evntrace/nf-evntrace-starttracew#system-loggers) に対してのみ 0 以外でありえる。- **FlushTimer**: バッファのフラッシュを待つ時間を変更する場合に設定する。このメンバが 0 の場合、メンバは更新されない。- **LogFileNameOffset**: 別のログファイルに切り替えたい場合、またはバッファリングモードのトレースを新しいログファイルにフラッシュしたい場合に設定する。このメンバが 0 の場合、ファイル名は更新されない。オフセットが 0 でなくログファイル名を変更しない場合、関数はエラーを返す。- **LogFileMode**: **EVENT_TRACE_REAL_TIME_MODE** のオン/オフを切り替えたい場合に設定する。リアルタイム消費をオフにするにはこのメンバを 0 に設定する。リアルタイム消費をオンにする（ディスクへの記録とリアルタイムイベント配信を同時に行うセッションを作成する）にはこのメンバを **EVENT_TRACE_REAL_TIME_MODE** に設定する。これは現在のモードと OR される。- **MaximumBuffers**: ETW が使用する最大バッファ数を変更する場合に設定する。このメンバが 0 の場合、メンバは更新されない。プライベートロガーセッションでは、**LogFileNameOffset** と **FlushTimer** メンバのみ更新できる。新しく初期化した [EVENT_TRACE_PROPERTIES](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties) 構造体を使用する場合は、構造体をゼロクリアしてから **Wnode.BufferSize**、**Wnode.Guid**、**Wnode.Flags** と、更新する値を設定する。**EVENT_TRACE_PROPERTIES** 構造体を再利用する場合（以前 [StartTrace](/windows/win32/api/evntrace/nf-evntrace-starttracew) または **ControlTrace** に渡した構造体を使用する場合）、ログファイル名を変更しない限り **LogFileNameOffset** メンバを 0 に設定し、[EVENT_TRACE_PROPERTIES.Wnode.Flags](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties) を **WNODE_FLAG_TRACED_GUID** に設定することを忘れないこと。> **Windows 10 バージョン 1703 以降:** クロスプロセスシナリオでのパフォーマンス向上のため、システム全体のプライベートロガーに対して **ControlTrace** にフィルタリング情報を渡せるようになった。フィルタリング情報を含めるには > [EVENT_TRACE_PROPERTIES_V2](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties_v2) > 構造体を使用する必要がある。詳細は > [Configuring and Starting a Private Logger Session](/windows/win32/etw/configuring-and-starting-a-private-logger-session) > を参照のこと。
ControlCode : [int] 

(プラグイン / モジュール : advapi32.dll)

解説

ControlTraceW (Unicode) 関数 (evntrace.h)
は、指定したイベントトレースセッションをフラッシュ、問い合わせ、更新、または停止する。

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS となる。関数が失敗した場合、戻り値は
[システムエラーコード](/windows/win32/debug/system-error-codes)
のいずれかとなる。以下に一般的なエラーとその原因を示す。- **ERROR_BAD_LENGTH** 以下のいずれかが真である: -
_Properties_ の **Wnode.BufferSize** メンバに不正なサイズが指定されている。- _Properties_
がセッション名とログファイル名（使用する場合）のコピーを保持するのに十分な領域を割り当てていない。-
**ERROR_INVALID_PARAMETER** 以下のいずれかが真である: - _Properties_ が **NULL**
である。- _InstanceName_ と _TraceHandle_ の両方が **NULL** である。-
_InstanceName_ が **NULL** で _TraceHandle_ が有効なハンドルではない。- _Properties_
の **LogFileNameOffset** メンバが有効でない。- _Properties_ の
**LoggerNameOffset** メンバが有効でない。- _Properties_ の **LogFileMode**
メンバに無効なフラグの組み合わせが指定されている。- _Properties_ の **Wnode.Guid** メンバが
**SystemTraceControlGuid** だが、_InstanceName_ パラメータが
`KERNEL_LOGGER_NAME` ではない。- **ERROR_BAD_PATHNAME** _Properties_ 構造体の
**LogFileNameOffset** メンバで指定したファイル名が既に別のセッションで使用されている。-
**ERROR_MORE_DATA**
[EVENT_TRACE_PROPERTIES](/windows/win32/api/evntrace/ns-evntrace-event_trace_properties)
のバッファが、セッションのすべての情報を保持するには小さすぎる。セッションのプロパティ情報が不要であれば、このエラーは無視してよい。セッションの停止時にこのエラーを受け取った場合、ETW
はこのエラーを生成する前に既にセッションを停止している。- **ERROR_ACCESS_DENIED**
管理者特権を持って実行されているユーザー、Performance Log Users
グループに属するユーザー、LocalSystem、LocalService、NetworkService
として動作しているサービスのみがイベントトレースセッションを制御できる。制限付きユーザーにトレースセッションを制御する権限を付与するには、Performance
Log Users グループに追加する。NT カーネルロガーセッションを制御できるのは、管理者特権を持つユーザーおよび
LocalSystem として動作するサービスのみである。**Windows XP および Windows 2000:**
誰でもトレースセッションを制御できる。- **ERROR_WMI_INSTANCE_NOT_FOUND**
指定したセッションが実行されていない。- **ERROR_ACTIVE_CONNECTIONS**
EVENT_TRACE_CONTROL_STOP 呼び出しから返された場合、セッションが既に停止処理中であることを示す。

[備考]
イベントトレースコントローラが本関数を呼び出す。本関数は
[FlushTrace](/windows/win32/api/evntrace/nf-evntrace-flushtracew)、[QueryTrace](/windows/win32/api/evntrace/nf-evntrace-querytracew)、[StopTrace](/windows/win32/api/evntrace/nf-evntrace-stoptracew)、[UpdateTrace](/windows/win32/api/evntrace/nf-evntrace-updatetracew)
関数に取って代わる。> [!NOTE] > evntrace.h ヘッダは、ControlTrace を UNICODE
プリプロセッサ定数の定義に基づいて ANSI 版または Unicode
版を自動選択するエイリアスとして定義している。エンコーディング中立のエイリアスとエンコーディング中立でないコードを混在させると、コンパイルエラーや実行時エラーを引き起こす不一致が生じる可能性がある。詳細は
[Conventions for Function
Prototypes](/windows/win32/intl/conventions-for-function-prototypes)
を参照のこと。

情報