CloseTrace 関数 (evntrace.h)

CloseTrace 関数は、OpenTrace で作成されたトレース処理セッションを閉じます。

構文

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI CloseTrace(
  [in] TRACEHANDLE TraceHandle
);

パラメーター

[in] TraceHandle

閉じるトレース処理セッションを処理します。 OpenTrace 関数は、このハンドルを返します。

戻り値

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

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

• ERROR_INVALID_HANDLE

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

  • TraceHandle は 0 です。
  • TraceHandle が INVALID_PROCESSTRACE_HANDLE。
  • TraceHandle は有効なハンドルではありません。

• ERROR_BUSY

  Windows Vista より前のバージョンでは、 ProcessTrace 関数が完了するまでトレースを閉じることができません。

• ERROR_CTX_CLOSE_PENDING

  呼び出しに成功しました。 ProcessTrace 関数は、バッファー内のすべてのリアルタイム イベントを処理した後に停止します (新しいイベントは受信しません)。

解説

コンシューマーはこの関数を呼び出して、 OpenTrace によって返されるトレース ハンドルを閉じます。

ログ ファイルからイベントを処理する場合は、 ProcessTrace 関数が戻った後にのみこの関数を呼び出します。 ただし、リアルタイム イベントを処理している場合は、 ProcessTrace が返される前にこの関数を呼び出すことができます。 (トレース処理を停止するもう 1 つの方法は、 BufferCallback から FALSE を返す方法です)。

ProcessTrace が返される前にこの関数を呼び出すと、CloseTrace 関数はERROR_CTX_CLOSE_PENDINGを返します。 ERROR_CTX_CLOSE_PENDINGコードは、 CloseTrace 関数の呼び出しが成功したことを示します。 ProcessTrace 関数は、以前にキューに登録されたすべてのイベントを処理した後にイベントの処理を停止します (CloseTrace 関数を呼び出した後、 ProcessTrace は新しいイベントを受信しません)。 CloseTrace 関数は、BufferCallback、EventCallback、または EventClassCallback コールバックから呼び出すことができます。

Windows Vista より前:CloseTrace は、ProcessTrace が返された後にのみ呼び出すことができます。

例

CloseTrace を使用する例については、「TDH を使用したイベント データの取得」を参照してください。

要件

関連項目

OpenTrace

ProcessTrace