TraceLoggingRegister 関数 (traceloggingprovider.h)

  • [アーティクル]

イベントをログに記録するために使用できるように、TraceLogging プロバイダーを登録します。 登録は、プロバイダーの登録が解除されるか、プロセスが終了するまで有効です。

構文

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

パラメーター

hProvider

登録するトレース ログ プロバイダーのハンドル。 ハンドルがまだ登録されていない必要があります。

戻り値

この関数をユーザー モード コードから呼び出すと、関数は を HRESULT返します。 マクロを SUCCEEDED() 使用して、関数が成功するかどうかを判断します。

カーネル モード コードからこの関数を呼び出すと、関数は を NTSTATUS返します。 マクロを NT_SUCCESS() 使用して、関数が成功するかどうかを判断します。

注意

TraceLoggingRegister によって返されるエラー コードは、主にデバッグと診断のシナリオで使用することを目的としています。 ETW プロバイダーが登録に失敗した場合でも、ほとんどの運用コードは引き続き実行する必要があるため、リリース ビルドでは通常 、TraceLoggingRegister によって返されるエラー コードを無視する必要があります。

注釈

コンポーネントの実行が開始されると、コンポーネント内のすべての TraceLogging プロバイダー ハンドルは未登録の状態になり、プロバイダーのハンドルを使用してイベントを生成しようとすると、警告なしに無視されます。 プロバイダーがイベントを書き込む前に、 TraceLoggingRegister を使用してプロバイダーを登録する必要があります。 これは通常、コンポーネントの起動時 (、、 など) にmainDllMain(DLL_PROCESS_ATTACH)wmainWinMain行います。DriverEntry コンポーネントのシャットダウン時に、 TraceLoggingUnregister を呼び出してプロバイダーの登録を解除します。

既に登録されているプロバイダー ハンドルで TraceLoggingRegister を呼び出さないでください。 ハンドルの登録を解除し、必要に応じて再度登録することもできますが、ハンドルの登録と登録解除を繰り返し行うとパフォーマンスの問題が発生する可能性があり、回避する必要があります (つまり、登録を行わず、いくつかのイベントを書き込んでから登録を解除します。代わりに、コンポーネントの起動時に 1 回登録し、コンポーネントのシャットダウン時に登録を解除します)。

TraceLoggingRegister は、同じハンドル上の TraceLoggingRegister または TraceLoggingUnregister への他の呼び出しに関してはスレッド セーフではありません。 別のスレッドが同じハンドルで TraceLoggingRegister または TraceLoggingUnregister を同時に呼び出す可能性がある場合は、TraceLoggingRegister を呼び出さないでください。

TraceLoggingRegister が失敗した場合、プロバイダー ハンドルは登録解除されたままになり、プロバイダー ハンドルのすべての使用は安全な操作なしになります。 特に、登録されていないプロバイダー ハンドルを使用して TraceLoggingWrite または TraceLoggingUnregister を呼び出しても安全な操作はありません。

重要

DLL またはドライバーがプロバイダー ハンドルで TraceLoggingRegister を呼び出す場合は、DLL またはドライバーをアンロードする前に、そのプロバイダー ハンドルで TraceLoggingUnregister を呼び出す必要があります。 TraceLoggingUnregister を呼び出さずに DLL がアンロードされると、その後プロセスがクラッシュする可能性があります。 ドライバーが TraceLoggingUnregister を呼び出さずにアンロードすると、システムは後でクラッシュする可能性があります。 TraceLoggingRegister 関数は ETW 構成コールバックを確立し、TraceLoggingUnregister はコールバックを取り消します。 コールバックが取り消されず、モジュールがアンロードされると、次回 ETW がコールバックを呼び出そうとしたときにクラッシュが発生します。

警告

ドライバーが TraceLoggingRegister を呼び出し、DriverEntry 中にエラーが発生した場合は、DriverEntry からエラーを返す前に TraceLoggingUnregister を呼び出す必要があります。 ドライバーが DriverEntry からエラーを返し、 TraceLoggingUnregister の呼び出しに失敗すると、システムがクラッシュする場合、通常のドライバー クリーンアップ ルーチンは呼び出されません。

TraceLoggingRegister は次の処理を行います。

  • EventRegister を呼び出して ETW への接続を開きます。
  • EventRegister が成功した場合は、InformationClassEventProviderSetTraits を使用して TraceLoggingSetInformation を呼び出して、TraceLogging サポート用にプロバイダーを構成します。

TraceLoggingRegister の呼び出しは、コールバックパラメーターとコンテキスト パラメーターに NULL を指定した TraceLoggingRegisterEx の呼び出しと同じです。 セッションでプロバイダーを有効または無効にするときに ETW Enable コールバックを受け取る必要がある場合は、TraceLoggingRegisterEx を使用します。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
Header traceloggingprovider.h
Library Advapi32.lib

こちらもご覧ください

EventRegister

TraceLoggingRegisterEx

TraceLoggingUnregister

TraceLoggingWrite

TRACELOGGING_DEFINE_PROVIDER