FlushTraceA 関数 (evntrace.h)

  • [アーティクル]

FlushTrace 関数を使用すると、イベント トレース セッションは、指定したセッションのバッファーされたイベントを直ちに配信します。 既定では、イベント トレース セッションは、バッファーがいっぱいになった場合、セッションの FlushTimer が期限切れになった場合、またはセッションが閉じられた場合にイベントを配信します。

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

構文

ULONG WMIAPI FlushTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

パラメーター

[in] TraceHandle

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

[in] InstanceName

フラッシュするイベント トレース セッションの名前( NULL)。 TraceHandle が 0 の場合は、InstanceName を指定する必要があります。

NT カーネル ロガー セッションを指定するには、 InstanceName をKERNEL_LOGGER_NAME に設定します。

[in, out] Properties

初期化された EVENT_TRACE_PROPERTIES 構造体へのポインター。

新しく初期化された構造体を使用している場合は、構造体の Wnode.BufferSize、 Wnode.Guid、 LoggerNameOffset、 LogFileNameOffset メンバーのみを設定する必要があります。 最大セッション名 (1024 文字) と最大ログ ファイル名 (1024 文字) を使用して、バッファー サイズとオフセット (不明な場合) を計算できます。

出力時に、構造体はイベント トレース セッションのプロパティ設定とセッション統計を受け取ります。これは、フラッシュ後のセッションの状態を反映します。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値は システム エラー コードの 1 つです。 次の表に、一般的なエラーとその原因を示します。

  • ERROR_INVALID_PARAMETER

    次のいずれかが当てはまります。

    • プロパティ は NULL です。
    • InstanceName と TraceHandle はどちらも NULL です。
    • InstanceName は NULL で、 TraceHandle は有効なハンドルではありません。

  • ERROR_BAD_LENGTH

    次のいずれかが当てはまります。

    • Properties の Wnode.BufferSize メンバーは、正しくないサイズを指定します。
    • セッション 名とログ ファイル名のコピーを保持するための十分な領域がプロパティに割り当てられません (使用されている場合)。

  • ERROR_ACCESS_DENIED

    管理特権を持つユーザー、パフォーマンス ログ ユーザー グループ内のユーザー、LocalSystem、LocalService、NetworkService として実行されているサービスのみがイベント トレース セッションを制御できます。 制限付きユーザーにトレース セッションを制御する機能を付与するには、それらを [パフォーマンス ログ ユーザー] グループに追加します。

    Windows XP と Windows 2000: トレース セッションは誰でも制御できます。

注釈

イベント トレース コントローラーは、この関数を呼び出します。

この関数は、現在使用されていません。 代わりに、ControlCode を EVENT_TRACE_CONTROL_FLUSH に設定して ControlTrace を使用します。

この関数は、メモリ内セッション ( EVENT_TRACE_BUFFERING_MODE フラグで開始されたセッション) と共に使用して、トレースからファイルにデータを書き込むことができます。

通常は、ファイル ベースまたはリアルタイム セッションをフラッシュする必要はありません。ETW は、バッファーがいっぱいになったとき (つまり、次のイベント用のスペースがない場合)、トレース セッションの FlushTimer の有効期限が切れた場合、またはトレース セッションが閉じられたときに自動的にフラッシュされるためです。

DllMain から FlushTrace を呼び出さないでください (デッドロックが発生する可能性があります)。

注意

evntrace.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして FlushTrace を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー evntrace.h
Library Advapi32.lib
[DLL] Advapi32.dll

こちらもご覧ください

ControlTrace