ProcessTrace 関数 (evntrace.h)

  • [アーティクル]

ProcessTrace 関数は、1 つ以上の ETW トレース処理セッションからコンシューマーにイベントを配信します。

構文

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PTRACEHANDLE HandleArray,
  [in] ULONG        HandleCount,
  [in] LPFILETIME   StartTime,
  [in] LPFILETIME   EndTime
);

パラメーター

[in] HandleArray

OpenTrace 関数の以前の呼び出しから取得したトレース処理セッション ハンドルの配列へのポインター。

配列には、ファイル処理セッションへの最大 64 個のハンドルを含めることができます。または、リアルタイム処理セッションへの 1 つのハンドルを含めることができます。 配列には、ファイル処理セッション ハンドルとリアルタイム処理セッション ハンドルの両方を含めることはできません。

[in] HandleCount

HandleArray 内の要素の数。

[in] StartTime

イベントを受信する開始時刻を指定するオプションの FILETIME 構造体へのポインター。 関数は、 StartTime より前のタイムスタンプを持つイベントを配信しません。

[in] EndTime

イベントを受信する終了期間を指定するオプションの FILETIME 構造体へのポインター。 関数は 、EndTime の後にタイムスタンプを持つイベントを配信しません。

Windows Server 2003: この値は、リアルタイムのイベント配信では無視されます。

戻り値

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

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

  • ERROR_BAD_LENGTH

    HandleCount が無効であるか、ハンドルの数が 64 を超えています。

  • ERROR_INVALID_HANDLE

    HandleArray の要素は、有効なイベント トレース セッション ハンドルではありません。

  • ERROR_INVALID_TIME

    EndTime が StartTime より小さい。

  • ERROR_INVALID_PARAMETER

    HandleArray は NULL、ファイル処理セッションとリアルタイム処理セッションの両方を含むか、複数のリアルタイム処理セッションを含みます。

  • ERROR_NOACCESS

    イベントを受信するコールバック関数のいずれかで例外が発生しました。

  • ERROR_CANCELLED

    コンシューマーが BufferCallback 関数で FALSE を返すことによって処理を取り消したことを示します。

  • ERROR_WMI_INSTANCE_NOT_FOUND

    リアルタイムでイベントを使用しようとしているトレース収集セッションが実行されていないか、リアルタイム トレース モードが有効になっていません。

解説

トレース コンシューマーは、この関数を呼び出して、1 つ以上のトレース処理セッションからのイベントを処理します。 この関数は、処理が終了するまでブロックします。

ProcessTrace を呼び出す前に、OpenTrace を使用してハンドルを開き、処理セッションをトレースします。

ProcessTrace 関数は、コンシューマーの BufferCallback、EventCallback、および EventRecordCallback コールバック関数を呼び出すことによって、セッションからイベントを配信します。

ProcessTrace 関数は、イベントのタイムスタンプに基づいてイベントを順番に配信しようとします (つまり、最も古いイベントを最新のイベントに配信しようとします)。 場合によっては、 ProcessTrace がイベントを順番に配信することがあります。

  • イベント タイムスタンプに使用されるクロックがトレース収集中に後方に調整された場合、イベントの配信順序は予測できません。 この問題を回避するには、トレースを収集するときにシステム タイム クロックではなく QPC クロックを使用します。
  • 異なる CPU で同じタイムスタンプを持つ複数のイベントが収集された場合、イベントの配信順序は予測できません。
  • イベントに無効なタイムスタンプ (ファイルの破損など) がある場合、そのイベントとそのトレース内の他のイベントの配信順序は予測できない可能性があります。

ProcessTrace 関数は、すべてのイベントを配信するか、BufferCallback 関数が FALSE を返すか、CloseTrace を呼び出すまでスレッドをブロックします。 さらに、コンシューマーがリアルタイムでイベントを使用している場合、コントローラーがトレース セッションを停止した後に ProcessTrace 関数が返されます。 (関数が戻るまでに数秒の遅延が発生する場合があることに注意してください)。

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

例

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

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー evntrace.h
Library Windows 8.1および Windows Server 2012 R2 の Sechost.lib。Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows XP 上の Advapi32.lib
[DLL] Windows 8.1および Windows Server 2012 R2 の Sechost.dll。Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows XP での Advapi32.dll

関連項目

BufferCallback

EventCallback

EventRecordCallback

OpenTrace