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 を使用する例については、「イベント トレース セッションの更新」を参照してください。

要件

こちらもご覧ください

ControlTrace