EventRegister 関数 (evntprov.h)
ETW イベント プロバイダーを登録し、ETW イベントの書き込みに使用できるハンドルを作成します。
構文
ULONG EVNTAPI EventRegister(
[in] LPCGUID ProviderId,
[in, optional] PENABLECALLBACK EnableCallback,
[in, optional] PVOID CallbackContext,
[out] PREGHANDLE RegHandle
);
パラメーター
[in] ProviderId
プロバイダーを一意に識別する GUID(コントロール GUID と呼ばれることもあります)。 トレース コントローラーが GUID を使用してこのプロバイダーのイベントをサブスクライブできるようにするには、これは安定した識別子である必要があります。
[in, optional] EnableCallback
トレース セッションでこのプロバイダーが有効または無効になったときに ETW によって呼び出される EnableCallback (省略可能)。 コールバックが必要ない場合は、 を使用 NULL します。
[in, optional] CallbackContext
EnableCallback を呼び出すときに ETW によって提供されるオプションのコンテキスト データ。 コールバック コンテキストが必要ない場合は、 を使用 NULL します。
[out] RegHandle
イベント プロバイダー登録ハンドルを受け取ります。 ハンドルは、 EventWrite、 EventProviderEnabled、 EventRegister などのプロバイダー API への後続の呼び出しで使用されます。
プロバイダーがアンロードまたは終了する前に、 EventUnregister を呼び出してプロバイダー登録ハンドルを解放します。 登録されているすべてのプロバイダー ハンドルを解放せずにアンロードする DLL は、プロセスがクラッシュする可能性があります。
戻り値
成功した場合 はERROR_SUCCESS を返します。
EventRegister によって返されるエラー コードは、主にデバッグと診断のシナリオで使用することを目的としています。 ETW プロバイダーの登録に失敗した場合でも、ほとんどの運用コードは引き続き実行する必要があるため、リリース ビルドでは通常 、EventRegister によって返されるエラー コードを無視する必要があります。
解説
EventRegister は、EventWrite、EventWriteTransfer、または EventWriteEx を使用して ETW イベントを書き込む際に使用できるハンドルを作成します。
Note
ほとんどのイベント プロバイダーは、 EventRegister を直接呼び出しません。 代わりに、ほとんどのイベント プロバイダーは、EventRegister、EventWrite、および EventUnregister の呼び出しをラップする ETW フレームワークを使用して実装されます。 たとえば、 イベント マニフェストを記述 し、 メッセージ コンパイラ を使用してイベントの C/C++ コードを生成したり、 TraceLogging を 使用してマニフェストが不要になる場合があります。
イベント プロバイダーの登録は、イベント プロバイダーのマニフェストのインストールと混同しないでください。
- EventRegister API は、イベント プロバイダーの登録を実行してプロバイダー ハンドルを作成します。 これはプロセス スコープの操作です (ハンドルはプロセス内でのみ有効です)。 ハンドルを使用して ETW イベントを書き込むことができます。 ハンドルを使用して書き込まれたすべてのイベントは、プロバイダー登録時に指定された ProviderId でタグ付けされます。 イベントを書き込んだりトレースをキャプチャしたりするためにマニフェストをインストールする必要はありません (ただし、プロバイダーのイベントをデコードしたり、プロバイダーがイベント ログを操作するためにマニフェストをインストールする必要がある場合があります)。
- wevtutil.exe ツールは、イベント プロバイダーのマニフェストをインストールまたはアンインストールするために使用されます。 イベント プロバイダー マニフェストのインストールは、マニフェストからの情報がシステムに記録されることを意味します。 記録された情報はシステム グローバルであり、マニフェストがアンインストールされるまで保持されます。 記録された情報には、マニフェストで定義されているプロバイダーの名前、GUID、チャネル、およびリソース DLL パスが含まれます。 マニフェストからの情報は、トレース デコード ツールとイベント ログによって使用されます。
ほとんどのコンポーネントは、コンポーネントの初期化時にイベント プロバイダーを登録し、コンポーネントのシャットダウン時にイベント プロバイダーの登録を解除します。 たとえば、アプリケーション (EXE) は、アプリケーションの起動時に登録し、アプリケーションの終了時に登録を解除する場合があります。 動的ライブラリ (DLL) は、プロセスアタッチ中に に DllMain 登録され、プロセスデタッチ中に 登録 DllMain 解除される可能性があります。
イベント トレースはデバッグ/診断上の問題であり、通常はアプリケーションクリティカルな機能ではないため、ほとんどの小売アプリケーションでは 、EventRegister によって返されるエラーをサイレントに無視する必要があります。 失敗した場合、 EventRegister は RegHandle パラメーターを 0 に設定して、その後の RegHandle の使用 (つまり 、EventWrite とEventUnregister の呼び出し) が無効になるようにします。
各プロセスでは、最大 1,024 のプロバイダーを登録できます。 ただし、コンポーネントが登録するプロバイダーの数を 1 つまたは 2 つに制限する必要があります。 この制限には、この関数を使用して登録されたプロバイダーと、 RegisterTraceGuids を使用して登録されたプロバイダーが含まれます。
Windows Vista より前: プロセスで登録できるプロバイダーの数に特定の制限はありません。
要件
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | evntprov.h |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |