EVENT_TRACE_LOGFILEA 構造体 (evntrace.h)

EVENT_TRACE_LOGFILE構造体には、トレース データ ソースに関する情報が格納されます。

EVENT_TRACE_LOGFILE構造体は、OpenTrace を呼び出すときに使用されます。 ユーザーは 、 トレース データ ソース (ETL ファイルの名前またはアクティブなリアルタイム ロガー セッションの名前)、トレース処理フラグ、およびトレース データを受信するコールバック関数に関する情報を含むEVENT_TRACE_LOGFILE構造体を提供します。 成功すると、 OpenTrace は構造体の残りのフィールドに入力し、トレース データ ソースに関する詳細を返します。

ProcessTrace は、バッファーを処理するときに、ユーザー定義 BufferCallback をEVENT_TRACE_LOGFILE構造体で呼び出して、イベント処理セッションとバッファーに関する情報を提供します。

構文

typedef struct _EVENT_TRACE_LOGFILEA {
  LPSTR                         LogFileName;
  LPSTR                         LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;

メンバー

LogFileName

処理されるログ ファイルの名前。リアルタイム トレース セッションからデータを処理する場合は NULL 。 OpenTrace を呼び出してログ ファイルのデータを使用する場合は、このメンバーの値を指定します。

OpenTrace を呼び出すときに LoggerName が NULL 以外の場合、LogFileName はNULL である必要があります。

OpenTrace を呼び出す場合、イベントを使用するユーザーには、ファイルを読み取るアクセス許可が必要です。

LoggerName

リアルタイム イベント トレース セッションの名前。ログ ファイルからデータを処理する場合は NULL 。 OpenTrace を呼び出してリアルタイム セッションのデータを使用する場合は、このメンバーの値を指定します。

OpenTrace を呼び出すときに、LogFileName が NULL 以外の場合、LoggerName は NULL である必要があります。

トレース コントローラーが EVENT_TRACE_PROPERTIES の LogFileMode メンバーに EVENT_TRACE_REAL_TIME_MODE フラグを 含める設定 を行っている場合にのみ、イベントをリアルタイム で 使用できます。

管理特権を持つユーザー、パフォーマンス ログ ユーザー グループ内のユーザー、LocalSystem、LocalService、NetworkService として実行されているアプリケーションのみが、リアルタイムでイベントを使用できます。 制限付きユーザーにリアルタイムでイベントを使用する機能を付与するには、イベントをパフォーマンス ログ ユーザー グループに追加するか 、EventAccessControl を呼び出します。

Windows XP と Windows 2000: 誰でもリアルタイム イベントを使用できます。

CurrentTime

出力では、1601 年 1 月 1 日午前 0 時からの 100 ナノ秒間隔の現在の時刻。

BuffersRead

出力時に処理されたバッファーの数。

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

予約済み。 使用しないでください。

DUMMYUNIONNAME.ProcessTraceMode

イベントを処理するためのモード。 モードは、ヘッダー ファイルで evntcons.h 定義されます。 次のモードの 1 つ以上を指定できます。

• PROCESS_TRACE_MODE_EVENT_RECORD

  新しい EVENT_RECORD 形式でイベントを受信する場合は、このモードを指定します (強くお勧めします)。 新しい形式でイベントを受信するには、 EventRecordCallback メンバーでコールバックを指定する必要があります。 このモードを指定しない場合は、 EventCallback メンバーで指定されたコールバックを使用して、古い形式のイベントを受信します。

  Windows Vista より前: サポートされていません。

• PROCESS_TRACE_MODE_RAW_TIMESTAMP

  既定では、 ProcessTrace は、イベントの TimeStamp を元の未加工形式 (システム時刻、QPC 時間、または CPU サイクル カウンター) からシステム時刻 (1601 年 1 月 1 日午前 0 時から 100 ナノ秒間隔) に変換します。

  EVENT_HEADERの TimeStamp メンバーにタイム スタンプ値を指定せず、システム時刻に変換EVENT_TRACE_HEADER場合は、PROCESS_TRACE_MODE_RAW_TIMESTAMP フラグを指定します。 このフラグを指定すると、 ProcessTrace は、コントローラーが EVENT_TRACE_PROPERTIES の Wnode.ClientContext メンバーで指定した 元の形式のタイム スタンプ値を残します。

  Windows Vista より前: サポートされていません。

• PROCESS_TRACE_MODE_REAL_TIME

  リアルタイムでイベントを受信するには、このモードを指定します。 LoggerName が NULL でない場合は、このモードを指定する必要があります。

CurrentEvent

出力 時に、 最後に処理されたイベントを含むEVENT_TRACE構造体。

LogfileHeader

出力時に、 セッション とセッションが実行されたコンピューターに関する一般的な情報を含むTRACE_LOGFILE_HEADER構造体。

BufferCallback

バッファー ETW フラッシュごとにバッファー関連の統計を受け取る BufferCallback 関数へのポインター。 ETW は、バッファー内のすべてのイベントを配信した後、このコールバックを呼び出します。 このコールバックは省略可能です。

BufferSize

出力時には、 には各バッファーのサイズがバイト単位で格納されます。

Filled

出力時には、有効な情報を含むバッファー内のバイト数が格納されます。

EventsLost

使用されていません。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

バッファー内の各イベントに対して ETW が呼び出す EventCallback 関数へのポインター。 このフィールドは、 ProcessTraceMode フィールドに フラグが含 PROCESS_TRACE_MODE_EVENT_RECORD まれていない場合にのみ使用されます。

DUMMYUNIONNAME2.EventRecordCallback

バッファー内の各イベントに対して ETW が呼び出す EventRecordCallback 関数へのポインター。 このフィールドは、 ProcessTraceMode フィールドに フラグが PROCESS_TRACE_MODE_EVENT_RECORD 含まれている場合にのみ使用されます。

Windows Vista より前: サポートされていません。

IsKernelTrace

出力時に、このメンバーが TRUE の場合、イベント トレース セッションは NT カーネル ロガーです。 それ以外の場合は、別のイベント トレース セッションです。

Context

OpenTrace を呼び出すときにコンシューマーが指定できるコンテキスト データ。 コンシューマーが EventRecordCallback を使用してイベントを使用する場合、ETW は、EVENT_RECORD構造体の UserContext メンバーをこの値に設定します。

Windows Vista より前: サポートされていません。

注釈

イベント コンシューマーは次の手順を実行する必要があります。

1. この構造体のメモリを 0 に初期化します。
2. ETL ファイルから読み取る場合は、 LogFileName をファイルのパスに設定します。 それ以外の場合 (つまり、リアルタイム セッションから読み取る場合)、 LoggerName を セッションの名前に設定し、 ProcessTraceMode を に PROCESS_TRACE_MODE_REAL_TIME設定します。
3. EventRecordCallback (推奨) を使用している場合は、EventRecordCallback をイベント レコード コールバック関数のアドレスに設定し、Context をコールバックに指定する値に設定し、ProcessTraceMode に追加PROCESS_TRACE_MODE_EVENT_RECORDします。 それ以外の場合 (つまり 、EventCallback を使用している場合)、 EventCallback をイベント コールバック関数のアドレスに設定します。
4. 各バッファーの処理後にコールバックが必要な場合は、 BufferCallback をバッファー コールバック関数のアドレスに設定します。
5. 処理されたタイムスタンプの代わりに元の生タイムスタンプ データが必要な場合は、ProcessTraceMode に を追加PROCESS_TRACE_MODE_RAW_TIMESTAMPします。
6. OpenTrace を呼び出します。 成功した場合、 OpenTrace 関数はこの構造体のメンバーにトレース データ ソースからの情報を入力します。
7. OpenTrace によって返されるハンドルを使用して ProcessTrace を呼び出します。
   • ProcessTrace は、イベントごとにイベント コールバック関数を呼び出します。
   • ProcessTrace は、各バッファーを終了した後にバッファー コールバック関数 (指定されている場合) を呼び出し、トレース処理の状態情報を 含むEVENT_TRACE_LOGFILE 構造体のインスタンスを含めます。
8. トレース処理が完了したら、 CloseTrace を呼び出して、 OpenTrace によって返されたハンドルを閉じます。

要件

こちらもご覧ください

BufferCallback

EventRecordCallback

OpenTrace