RegisterTraceGuidsA 関数 (evntrace.h)
RegisterTraceGuids 関数は、クラシック (Windows 2000 スタイル) ETW イベント トレース プロバイダーと、イベントの生成に使用するイベント トレース クラスを登録します。 この関数は、プロバイダーからのトレースを有効または無効にするためにシステムが使用するコールバック関数も指定します。
この関数は、現在使用されていません。 新しいコードでは 、EventRegister を使用して 、Windows Vista スタイル (真紅) ETW イベント トレース プロバイダーを登録する必要があります。
構文
ULONG WMIAPI RegisterTraceGuidsA(
[in] WMIDPREQUEST RequestAddress,
[in] PVOID RequestContext,
[in] LPCGUID ControlGuid,
[in] ULONG GuidCount,
[in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
[in] LPCSTR MofImagePath,
[in] LPCSTR MofResourceName,
[out] PTRACEHANDLE RegistrationHandle
);
パラメーター
[in] RequestAddress
イベント トレース セッションによってプロバイダーが有効または無効になったときに通知を受け取る ControlCallback 関数へのポインター。 EnableTrace 関数は、このコールバックをトリガーします。
[in] RequestContext
ETW が RequestAddress で指定した関数に渡す、オプションのプロバイダー定義コンテキストへのポインター。
[in] ControlGuid
登録プロバイダーの GUID (プロバイダー ID) を制御します。
[in] GuidCount
TraceGuidReg 配列内の要素の数。 TraceGuidReg が NULL の場合は、このパラメーターを 0 に設定します。
[in, out] TraceGuidReg
の配列へのポインター
TRACE_GUID_REGISTRATION 構造体。
各要素は、プロバイダーが提供するイベントのカテゴリを識別します。
入力時に、各構造体の Guid メンバーには、登録プロバイダーによって割り当てられたイベント トレース クラス GUID が含まれます。 クラス GUID は、プロバイダーが提供するイベントのカテゴリを識別します。 プロバイダーは、TraceEvent 関数を呼び出してイベントをログに記録するときに、同じクラス GUID を使用して EVENT_TRACE_HEADER の Guid メンバーを設定します。
出力時に、 RegHandle メンバーはイベントのクラス GUID 登録へのハンドルを受け取ります。 プロバイダーが TraceEventInstance 関数を呼び出す場合は、TRACE_GUID_REGISTRATION の RegHandle メンバーを使用して、EVENT_INSTANCE_HEADERの RegHandle メンバーを設定します。
プロバイダーが TraceEvent 関数のみを呼び出してイベントをログに記録する場合、このパラメーターは NULL にすることができます。 プロバイダーが TraceEventInstance 関数を呼び出してイベントをログに記録する場合、このパラメーターを NULL にすることはできません。
[in] MofImagePath
このパラメーターはサポートされていません。 NULL に設定します。 Mofcomp.exe を使用して、アプリケーションのセットアップ中に MOF リソースを登録する必要があります。 詳細については、「 イベント スキーマの発行」を参照してください。
SP1、Windows XP、Windows 2000 の Windows XP:MofResourceName で指定されたリソースを含む DLL または実行可能プログラムのパスを指定する省略可能な文字列へのポインター。 イベント プロバイダーとコンシューマーが別のメカニズムを使用してプロバイダーによって使用されるイベント トレース クラスに関する情報を共有する場合、このパラメーターは NULL にすることができます。
[in] MofResourceName
このパラメーターはサポートされていません。 NULL に設定します。 Mofcomp.exe を使用して、アプリケーションのセットアップ中に MOF リソースを登録する必要があります。 詳細については、「 イベント スキーマの発行」を参照してください。
SP1、Windows XP、Windows 2000 の Windows XP:MofImagePath の文字列リソースを指定する省略可能な文字列へのポインター。 文字列リソースには、プロバイダーでサポートされているイベント トレース クラスを記述するバイナリ MOF ファイルの名前が含まれています。
[out] RegistrationHandle
プロバイダーの登録ハンドルを受け取ります。 UnregisterTraceGuids 関数を呼び出すときは、返されるハンドルを使用します。
重要
DLL またはドライバーによって作成されたすべての登録ハンドルは、DLL またはドライバーがアンロードされる前に登録解除する必要があります。 プロバイダーが登録解除されていない場合、ETW がプロバイダーのコールバックを呼び出そうとするとクラッシュが発生します。
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。
関数が失敗した場合、戻り値は システム エラー コードの 1 つです。 一般的なエラーとその原因を次に示します。
重要
この関数は、コントローラーが EnableTrace を呼び出してプロバイダーを有効にし、プロバイダーがまだ RegisterTraceGuids を呼び出していない場合に、ControlCallback によって返される値を返すこともできます。 これが発生すると、登録が成功した場合、 RegisterTraceGuids はコールバックの戻り値を返します。
ERROR_INVALID_PARAMETER
次のいずれかが当てはまります。
- RequestAddress が NULL です。
- ControlGuid が NULL です。
- RegistrationHandle は NULL です。
Windows XP と Windows 2000:TraceGuidReg が NULL であるか、 GuidCount が 0 以下です。
解説
注意
ほとんどの開発者は、この関数を直接呼び出しません。 代わりに、開発者は通常 ETW フレームワークを使用します。 たとえば、TMF ベースの WPP は、 RegisterTraceGuids、 TraceMessage、 UnregisterTraceGuids の呼び出しを代理で管理します。
この関数は、TraceEvent、TraceEventInstance、TraceMessage、および TraceMessageVa を介して MOF および TMF ベースの WPP ETW イベントを書き込むのに使用できるクラシック (Windows 2000 スタイル) イベント プロバイダー ハンドルを開きます。
注意
EventWrite を介してマニフェスト ベースまたはトレース ログ ベースの ETW イベントを書き込む Windows Vista スタイルのプロバイダー ハンドルを開くには、EventRegister を使用します。
プロバイダーの ControlGuid が以前に登録され、有効になっている場合、同じ ControlGuid を参照する後続の登録が自動的に有効になります。
プロセスでは、最大 1,024 個のプロバイダー GUID を登録できます。ただし、プロセスで登録するプロバイダーの数を 1 つまたは 2 つに制限する必要があります。 この制限には、この関数と EventRegister 関数を使用して登録されたものが含まれます。
Windows Vista より前: プロセスで登録できるプロバイダーの数に制限はありません。
例
RegisterTraceGuids を使用する例については、「クラシック イベントの書き込み」を参照してください。
注意
evntrace.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして RegisterTraceGuids を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | evntrace.h |
| Library | Windows 8.1および Windows Server 2012 R2 の Sechost.lib。Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows XP 上の Advapi32.lib |
| [DLL] | Windows 8.1および Windows Server 2012 R2 で Sechost.dll。Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows XP で Advapi32.dll |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示