UpdateTraceW 関数 (evntrace.h)

  • [アーティクル]

UpdateTrace 関数は、指定されたイベント トレース セッションのプロパティ設定を更新します。

この関数は、現在使用されていません。 ControlTrace 関数は、この関数よりも優先されます。

構文

ULONG WMIAPI UpdateTraceW(
  TRACEHANDLE             TraceHandle,
  LPCWSTR                 InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

パラメーター

TraceHandle

更新するイベント トレース セッション (0) を処理します。 InstanceName が NULL の場合は、0 以外の TraceHandle を指定する必要があります。 このパラメーターは、 InstanceName が NULL の場合にのみ使用されます。 ハンドルは StartTrace によって返されます。

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

こちらもご覧ください

ControlTrace