UpdateTraceW 関数 (evntrace.h)
UpdateTrace 関数は、指定されたイベント トレース セッションのプロパティ設定を更新します。
この関数は、現在使用されていません。 ControlTrace 関数は、この関数よりも優先されます。
構文
ULONG WMIAPI UpdateTraceW(
CONTROLTRACE_ID TraceId,
LPCWSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
パラメーター
TraceId
InstanceName
更新するイベント トレース セッションの名前( NULL)。 TraceHandle が 0 の場合は、InstanceName を指定する必要があります。
NT カーネル ロガー セッションを指定するには、 InstanceName をKERNEL_LOGGER_NAME に設定します。
Properties
初期化された EVENT_TRACE_PROPERTIES 構造体へのポインター。
入力時に、メンバーは更新するプロパティの新しい値を指定する必要があります。 更新できるプロパティの詳細については、「解説」を参照してください。
出力時に、構造体メンバーには、イベント トレース セッションの更新された設定と統計が含まれます。
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。
関数が失敗した場合、戻り値は システム エラー コードの 1 つです。 次の表に、一般的なエラーとその原因を示します。
ERROR_BAD_LENGTH
Properties の Wnode メンバーの BufferSize メンバーは、正しくないサイズを指定します。
ERROR_INVALID_PARAMETER
次のいずれかが当てはまります。
- プロパティ は 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
管理者特権を持つユーザー、パフォーマンス ログ ユーザー グループ内のユーザー、LocalSystem、LocalService、NetworkService として実行されているサービスのみが、イベント トレース セッションを制御できます。 制限付きユーザーにトレース セッションを制御する機能を付与するには、それらを [パフォーマンス ログ ユーザー] グループに追加します。
Windows XP と Windows 2000: トレース セッションは誰でも制御できます。
注釈
イベント トレース コントローラーは、この関数を呼び出します。
この関数は、現在使用されていません。 代わりに、ControlCode を EVENT_TRACE_CONTROL_UPDATE に設定して ControlTrace を使用します。
入力時に、メンバーは更新するプロパティの新しい値を指定する必要があります。 次のプロパティを更新できます。
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 構造体を使用している場合、更新するメンバー以外に指定する必要があるメンバーは、 Wnode.BufferSize、 Wnode.Guid、 Wnode.Flags のみです。
StartTrace に渡したプロパティ構造を使用する場合は、ログ ファイル名を変更しない限り、LogFileNameOffset メンバーが 0 であることを確認してください。
ControlTrace 関数を呼び出して現在のセッション プロパティに対してクエリを実行し、それらのプロパティを更新してセッションを更新する場合は、LogFileNameOffset を 0 (ログ ファイル名を変更する場合を除く) に設定し、EVENT_TRACE_PROPERTIES設定してください。WNODE_FLAG_TRACED_GUIDする Wnode.Flags。
イベント トレース セッションのプロパティ設定とセッション統計を取得するには、 ControlTrace 関数を呼び出します。
例
UpdateTrace を使用する例については、「イベント トレース セッションの更新」を参照してください。
注意
evntrace.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして UpdateTrace を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
対象プラットフォーム | Windows |
ヘッダー | evntrace.h |
Library | Advapi32.lib |
[DLL] | Advapi32.dll |