FlushTraceW

FlushTraceW (Unicode) 関数 (evntrace.h) は、指定したセッションに対してイベントトレーシングセッションがバッファリングされたイベントを直ちに配信するようにする。

FlushTraceW TraceHandle, InstanceName, Properties

TraceHandle : [int] フラッシュするイベントトレーシングセッションのハンドル、または 0。_InstanceName_ が **NULL** の場合、ゼロ以外の _TraceHandle_ を指定しなければならない。このパラメータは _InstanceName_ が **NULL** の場合にのみ使用される。ハンドルは [StartTrace](/windows/win32/api/evntrace/nf-evntrace-starttracew) によって返される。
InstanceName : [wstr] フラッシュするイベントトレーシングセッションの名前、または **NULL**。_TraceHandle_ が 0 の場合は _InstanceName_ を指定しなければならない。NT Kernel Logger セッションを指定するには _InstanceName_ を **KERNEL_LOGGER_NAME** に設定する。
Properties : [var] 初期化済みの [EVENT_TRACE_PROPERTIES](/windows/desktop/ETW/event-trace-properties) 構造体へのポインタ。新しく初期化された構造体を使用する場合、構造体の **Wnode.BufferSize**、**Wnode.Guid**、**LoggerNameOffset**、および **LogFileNameOffset** メンバだけを設定すれば十分である。わからない場合は、最大セッション名 (1024 文字) と最大ログ ファイル名 (1024 文字) の長さを使用してバッファ サイズとオフセットを計算できる。出力時、構造体はフラッシュ後のセッション状態を反映するイベントトレーシングセッションのプロパティ設定とセッション統計を受け取る。

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

解説

FlushTraceW (Unicode) 関数 (evntrace.h)
は、指定したセッションに対してイベントトレーシングセッションがバッファリングされたイベントを直ちに配信するようにする。

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS となる。失敗した場合、戻り値は [system error
codes](/windows/win32/debug/system-error-codes)
のいずれかとなる。次の表は一般的なエラーとその原因を示す。- **ERROR_INVALID_PARAMETER**
次のいずれかが真である。- _Properties_ が **NULL** である。- _InstanceName_ と
_TraceHandle_ の両方が **NULL** である。- _InstanceName_ が **NULL**
で、_TraceHandle_ が有効なハンドルではない。- **ERROR_BAD_LENGTH** 次のいずれかが真である。-
_Properties_ の **Wnode.BufferSize** メンバが正しくないサイズを指定している。-
_Properties_ に、セッション名とログ ファイル名 (使用されている場合)
のコピーを保持するのに十分な領域が割り当てられていない。- **ERROR_ACCESS_DENIED**
管理者特権を持つユーザー、Performance Log Users
グループのユーザー、LocalSystem、LocalService、NetworkService
として実行されているサービスのみがイベント トレース
セッションを制御できる。制限付きユーザーにトレースセッションを制御する機能を付与するには、そのユーザーを Performance Log
Users グループに追加する。**Windows XP と Windows 2000:** 誰でもトレースセッションを制御できる。

[備考]
イベント トレース
コントローラはこの関数を呼び出す。この関数は非推奨である。代わりに、[ControlTrace](/windows/win32/api/evntrace/nf-evntrace-controltracew)
を使用し、_ControlCode_ を **EVENT_TRACE_CONTROL_FLUSH** に設定する。この関数はインメモリ
セッション (**EVENT_TRACE_BUFFERING_MODE** フラグで開始されたセッション)
で使用でき、トレースからファイルにデータを書き込む。ファイル ベースまたはリアルタイム セッションでは通常、バッファが一杯になった場合
(すなわち次のイベントを収容する余地がない場合)、トレースセッションの FlushTimer
が満了した場合、またはトレースセッションが閉じられた場合に ETW
が自動的にバッファをフラッシュするため、手動でフラッシュする必要はない。DllMain から **FlushTrace**
を呼び出してはならない (デッドロックを引き起こす可能性がある)。
> [!NOTE] > evntrace.h ヘッダーは FlushTrace をエイリアスとして定義しており、UNICODE
プリプロセッサ定数の定義に応じて、この関数の ANSI 版と Unicode
版を自動的に選択する。エンコーディングに依存しないエイリアスと、エンコーディングに依存しないコードとを混在させると、コンパイルエラーや実行時エラーを引き起こす不整合が生じる可能性がある。詳細は
[関数プロトタイプの規約](/windows/win32/intl/conventions-for-function-prototypes)
を参照。

情報