UpdateTraceW

UpdateTraceW (Unicode) 関数 (evntrace.h) は、指定したイベントトレースセッションのプロパティ設定を更新する。

UpdateTraceW TraceHandle, InstanceName, Properties

TraceHandle : [int] 更新するイベントトレースセッションへのハンドル、または 0。_InstanceName_ が **NULL** の場合は、0 以外の _TraceHandle_ を指定する必要がある。このパラメータは _InstanceName_ が **NULL** の場合にのみ使用される。ハンドルは [StartTrace](/windows/win32/api/evntrace/nf-evntrace-starttracew) が返す。
InstanceName : [wstr] 更新するイベントトレースセッションの名前、または **NULL**。_TraceHandle_ が 0 の場合は _InstanceName_ を指定する必要がある。NT カーネルロガーセッションを指定するには、_InstanceName_ に **KERNEL_LOGGER_NAME** を設定する。
Properties : [var] 初期化済みの [EVENT_TRACE_PROPERTIES](/windows/desktop/ETW/event-trace-properties) 構造体へのポインタ。入力時、メンバには更新するプロパティの新しい値を指定しなければならない。更新できるプロパティについては、注釈を参照のこと。出力時、構造体メンバはイベントトレースセッションの更新された設定と統計情報を含む。

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

解説

UpdateTraceW (Unicode) 関数 (evntrace.h)
は、指定したイベントトレースセッションのプロパティ設定を更新する。

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS となる。関数が失敗した場合、戻り値は
[システムエラーコード](/windows/win32/debug/system-error-codes)
のいずれかとなる。次の表に代表的なエラーとその原因を示す。- **ERROR_BAD_LENGTH** _Properties_ の
**Wnode** メンバの **BufferSize** メンバが不正なサイズを指定している。-
**ERROR_INVALID_PARAMETER** 次のいずれかが発生している: - _Properties_ が
**NULL**。- _InstanceName_ と _TraceHandle_ の両方が **NULL**。-
_InstanceName_ が **NULL** で _TraceHandle_ が有効なハンドルでない。- _Properties_
の **LogFileNameOffset** メンバが不正。- _Properties_ の **LoggerNameOffset**
メンバが不正。**Windows Server 2003 および Windows XP:** **Wnode** 構造体の
**Guid** メンバが SystemTraceControlGuid だが、_InstanceName_ パラメータが
KERNEL_LOGGER_NAME でない。- **ERROR_ACCESS_DENIED**
管理者特権を持つユーザ、Performance Log Users グループのユーザ、LocalSystem / LocalService
/ NetworkService
として実行中のサービスのみがイベントトレースセッションを制御できる。制限付きユーザにトレースセッション制御権限を付与するには、Performance
Log Users グループに追加すること。**Windows XP および Windows 2000:**
誰でもトレースセッションを制御できる。

[備考]
イベントトレースコントローラがこの関数を呼び出す。この関数は廃止予定である。代わりに、_ControlCode_ を
**EVENT_TRACE_CONTROL_UPDATE** に設定した
[ControlTrace](/windows/win32/api/evntrace/nf-evntrace-controltracew)
を使用する。入力時、メンバには更新するプロパティの新しい値を指定しなければならない。以下のプロパティを更新できる。-
**EnableFlags**: すべてのカーネルプロバイダを無効にするにはこのメンバを 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/desktop/ETW/event-trace-properties)
構造体を使用する場合、更新するメンバ以外に指定する必要があるのは
**Wnode.BufferSize**、**Wnode.Guid**、および **Wnode.Flags**
のみである。[StartTrace](/windows/desktop/ETW/starttrace)
に渡したプロパティ構造体を使用する場合、ログファイル名を変更する場合を除き **LogFileNameOffset** メンバが 0
であることを確認する。[ControlTrace](/windows/desktop/ETW/controltrace)
関数を呼び出して現在のセッションプロパティを問い合わせてからそれらのプロパティを更新してセッションを更新する場合、**LogFileNameOffset**
を 0
に（ログファイル名を変更する場合を除き）、[EVENT_TRACE_PROPERTIES.Wnode.Flags](/windows/desktop/ETW/event-trace-properties)
を **WNODE_FLAG_TRACED_GUID**
に設定することを確認する。イベントトレースセッションのプロパティ設定とセッション統計情報を取得するには、[ControlTrace](/windows/desktop/ETW/controltrace)
関数を呼び出す。

情報