WMIDPREQUEST
コールバックシグネチャ
DWORD WMIDPREQUEST(
WMIDPREQUESTCODE RequestCode,
void* RequestContext,
DWORD* BufferSize,
void* Buffer
);パラメーター
| フィールド | 型 | 説明 | ||||||
|---|---|---|---|---|---|---|---|---|
| RequestCode | WMIDPREQUESTCODE | 要求コード。次のいずれかの値になります。
| ||||||
| RequestContext | void* | プロバイダーが定義するコンテキストです。プロバイダーは、RegisterTraceGuids の RequestContext パラメーターでコンテキストを指定します。 | ||||||
| BufferSize | DWORD* | 内部使用のために予約されています。 | ||||||
| Buffer | void* | プロバイダーが有効化または無効化されるイベントトレースセッションに関する情報を格納した WNODE_HEADER 構造体へのポインターです。 |
公式ドキュメント
RegisterTraceGuids ベースの(「クラシック」)イベントプロバイダーは、コントローラーからの有効化または無効化の通知要求を受け取るために、この関数を実装します。
WMIDPREQUEST 型は、このコールバック関数へのポインターを定義します。ControlCallback は、アプリケーション定義の関数名のプレースホルダーです。
戻り値
コールバックが成功した場合は ERROR_SUCCESS を返してください。なお ETW は、この関数の戻り値を無視します。ただし、コントローラーが EnableTrace を呼び出してプロバイダーを有効にしたときに、そのプロバイダーがまだ RegisterTraceGuids を呼び出していない場合は例外です。この場合、登録が成功していれば、RegisterTraceGuids はこのコールバックの戻り値を返します。
解説(Remarks)
この関数は RegisterTraceGuids 関数で指定します。コントローラーが EnableTrace 関数を呼び出して有効化、無効化、または enable フラグやレベルの変更を行うと、ETW はこのコールバックを呼び出します。プロバイダーは RequestCode の値に基づいて自身を有効または無効にします。通常、プロバイダーはこの値を使用して、有効状態を示すグローバルフラグを設定します。
有効または無効であることをどう解釈するかは、プロバイダーが定義します。一般に、プロバイダーは有効な間はイベントを生成し、無効な間は生成しません。
ETW は、コントローラーが EnableTrace 関数に渡した enable フラグと enable レベルを、このコールバックには渡しません。これらの情報を取得するには、それぞれ GetTraceEnableFlags 関数と GetTraceEnableLevel 関数を呼び出します。
また、以降の呼び出しに備えて、このコールバック内でセッションハンドルを取得しておく必要があります。セッションハンドルを取得するには、GetTraceLoggerHandle 関数を呼び出します。
コールバック関数からは、LoadLibrary を発生させる可能性があるもの(より具体的には、ローダーロックを必要とするもの)を一切呼び出してはいけません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)