EnableTrace 関数 (evntrace.h)

  • [アーティクル]

トレース セッション コントローラーは EnableTrace を 呼び出して、ETW イベント プロバイダーがトレース セッションにイベントを記録する方法を構成します。

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

構文

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

パラメーター

[in] Enable

プロバイダーからのイベントの受信を有効にする場合、またはプロバイダーからイベントを受信するときに使用する設定を調整するには、1 に設定します (レベルやキーワードを変更する場合など)。 プロバイダーからのイベントの受信を無効にするには、0 に設定します。

[in] EnableFlag

プロバイダーが書き込むイベントのカテゴリを決定するキーワードの 32 ビット ビットマスク。 プロバイダーは通常、イベントのキーワード (keyword) ビットがこの値に設定されているビットのいずれかと一致する場合、またはイベントに キーワード (keyword) ビットが設定されていない場合、EnableLevel クリテラを満たすだけでなく、イベントを書き込みます。

Note

EventRegister ベースのプロバイダーでは、64 ビット キーワードがサポートされています。 EnableTraceEx2 を使用して、64 ビットの MatchAnyKeyword マスクを使用してプロバイダーを有効にします。

[in] EnableLevel

プロバイダーが書き込むイベントの最大レベルを示す 値。 プロバイダーは、通常、イベントのレベルがこの値以下である場合、 EnableFlag 条件を満たすだけでなく、イベントを書き込みます。

この値は、1 ~ 255 の範囲である必要があります。 Microsoft では、次に示すように、レベル 1 から 5 のセマンティクスを定義します。 値が小さいほど、より重大なイベントを示します。 EnableLevel の各値は、指定されたレベルとより厳しいレベルをすべて有効にします。 たとえば、 を指定 TRACE_LEVEL_WARNINGすると、コンシューマーは警告、エラー、重大なイベントを受け取ります。

値 意味
TRACE_LEVEL_CRITICAL (1) 異常終了イベントまたは終了イベント
TRACE_LEVEL_ERROR (2) 重大なエラー イベント
TRACE_LEVEL_WARNING (3) 割り当てエラーなどの警告イベント
TRACE_LEVEL_INFORMATION (4) エラー以外の情報イベント
TRACE_LEVEL_VERBOSE (5) 詳細な診断イベント

定数は TRACE_LEVELevntrace.h で定義されます。 同等 WINMETA_LEVEL の定数は winmeta.h で定義されます。

[in] ControlGuid

有効または無効にするイベント プロバイダーのコントロール GUID (プロバイダー ID)。

[in] TraceHandle

プロバイダーを構成するイベント トレース セッションのハンドル。 StartTrace 関数は、新しいトレースが開始されたときにこのハンドルを返します。 既存のトレースのハンドルを取得するには、ControlTrace を使用してトレースの名前に基づいてトレース プロパティを照会し、返されたEVENT_TRACE_PROPERTIESデータの Wnode.HistoricalContext フィールドからハンドルを取得します。

戻り値

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

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

  • ERROR_INVALID_PARAMETER

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

    • ControlGuid が NULL です。
    • TraceHandle は NULL です。

  • ERROR_INVALID_FUNCTION

    プロバイダーが登録されていない場合は、有効化フラグとレベルを変更できません。

  • ERROR_WMI_GUID_NOT_FOUND

    プロバイダーが登録されていません。 KB307331 または Windows 2000 Service Pack 4 がインストールされ、プロバイダーが登録されていない場合に発生します。 このエラーを回避するには、まずプロバイダーを登録する必要があります。

  • ERROR_NO_SYSTEM_RESOURCES

    プロバイダーを有効にできるトレース セッションの数を超えました。

  • ERROR_ACCESS_DENIED

    管理者特権を持つユーザー、グループ内のPerformance Log Usersユーザー、および 、、または NetworkService としてLocalServiceLocalSystem実行されているサービスを持つユーザーのみが、クロスプロセス セッションに対してイベント プロバイダーを有効にすることができます。 制限付きユーザーにイベント プロバイダーを有効にする機能を付与するには、グループに Performance Log Users 追加するか、「 EventAccessControl」を参照してください。

    Windows XP と Windows 2000: イベント プロバイダーは誰でも有効にできます。

解説

イベント トレース コントローラーは、この関数を呼び出して、セッションにイベントを書き込むイベント プロバイダーを構成します。 たとえば、コントローラーは、プロバイダーからのイベントの収集を開始したり、プロバイダーから収集されるイベントのレベルまたはキーワードを調整したり、プロバイダーからのイベントの収集を停止したりするために、この関数を呼び出す場合があります。

この関数は、現在使用されていません。 追加の機能については、新しいコードで EnableTraceEx2 を使用する必要があります。

次の 2 つの関数呼び出しは同等です。

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

セッションのプロバイダーを構成するセマンティクスの詳細については、 EnableTraceEx2 のドキュメントを参照してください。

要件

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

関連項目

StartTrace

EnableTraceEx2