PcwRegister 関数 (wdm.h)
関数は PcwRegister 、新しいカウンターセット登録を作成します。 ほとんどの開発者は、この関数を直接呼び出す代わりに 、CTRPP によって生成された RegisterXxx 関数を使用します。
構文
NTSTATUS PcwRegister(
[out] PPCW_REGISTRATION *Registration,
[in] PPCW_REGISTRATION_INFORMATION Info
);
パラメーター
[out] Registration
PPCW_REGISTRATIONへのポインター。 新しい登録へのハンドルを受け取ります。 登録は PcwUnregister を使用して閉じる必要があります。
[in] Info
登録されているカウンターセットに関する詳細を含む PCW_REGISTRATION_INFORMATION 構造体へのポインター。
戻り値
PcwRegister は、次のいずれかの値を返します。
| リターン コード | 説明 |
|---|---|
STATUS_SUCCESS |
カウンターセットが正常に登録されました。 |
STATUS_INTEGER_OVERFLOW |
この登録によって公開されるカウンターの数が、サポートされている最大数を超えています。 |
STATUS_NO_MEMORY |
カウンターにメモリを割り当てるのに十分な領域がありません。 |
STATUS_INVALID_PARAMETER_2 |
パラメーターに Info 問題が見つかりました。 考えられる原因については、以下を参照してください。 |
PcwRegister は、次の場合に を返す STATUS_INVALID_PARAMETER_2 場合があります。
フィールドが
Info->Name->Length0 であるか、 のsizeof(WCHAR)倍数ではありません。フィールドは
Info->Version、このバージョンの Windows でサポートされている値と一致しません。 10.0.19645 () より前の Windows で実行する場合は、フィールドをVersionPCW_VERSION_1 (NTDDI_VERSION < NTDDI_VERSION_MN0x100) に設定する必要があります。 Windows 10.0.19645 以降 () で実行する場合はNTDDI_VERSION >= NTDDI_VERSION_MN、PCW_VERSION_1 (0x100) またはPCW_VERSION_2 (0x200) に設定できます。Info->Flagsフィールドには、実行中のバージョンの Windows で認識されない値が含まれています。
注釈
プロバイダーはこの関数を呼び出して、新しいカウンターセット登録を作成します。 すべての入力引数がキャプチャされ、呼び出し元がそれらのコピーを保持する必要がないようにします。
既定では、新しいカウンターセットは、登録時にアクティブだったサーバー サイロにのみ表示されます (つまり PcwRegister 、新しく作成された登録を、呼び出されたときに PcwRegister スレッドにアタッチされたサーバー サイロに関連付けます)。 Windows 10.0.19645 以降 (NTDDI_VERSION >= NTDDI_VERSION_MN) で実行している場合は、 を に設定し、 を に設定PCW_REGISTRATION_INFORMATION::FlagsPCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2することで、すべてのサーバー サイロに表示されるカウンターセット登録をPcwRegistrationSiloNeutral作成できます。
CTRPP によって生成された RegisterXxx 関数
ほとんどの開発者は、 を直接呼び出す PcwRegister 必要はありません。 代わりに、CTRPP ツールを使用してマニフェストをコンパイルし、CTRPP によって生成されたヘッダーから RegisterXxx 関数を使用します。 生成された関数は次のようになります。
EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
__in_opt PPCW_CALLBACK Callback,
__in_opt PVOID CallbackContext
)
{
PCW_REGISTRATION_INFORMATION RegInfo;
PAGED_CODE();
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);
return PcwRegister(&MyCounterset, &RegInfo);
}
CTRPP によって生成された Register 関数には、 プレフィックスレジスタ カウンターセットという名前が付けられます。 プレフィックス は通常は空白ですが、パラメーターが -prefix CTRPP コマンド ラインで使用された場合は存在する可能性があります。 Counterset は、マニフェストで指定されているカウンターセットの名前です。 生成された Register 関数は、PrefixInitRegistrationInformationCounterset 関数を呼び出して構造体をPCW_REGISTRATION_INFORMATION初期化し、 を呼び出PcwRegisterして新しい登録を作成し、MyCountersetグローバル Counterset 変数 (この例では CTRPP によって生成されたヘッダーで宣言) にハンドルを格納します。
場合によっては、CTRPP によって生成された Add 関数が適切でない場合があります。
を使用
NTDDI_VERSION >= NTDDI_VERSION_FEしてコンパイルする必要があるが、以前のバージョンの Windows で実行する必要がある場合、CTRPP によって生成された Register 関数は を設定RegInfo.Version = PCW_CURRENT_VERSIONするため機能しません。PCW_CURRENT_VERSIONの場合NTDDI_VERSION >= NTDDI_VERSION_FE、 が にPCW_VERSION_2PcwRegister設定され、エラーが返されます。複数のカウンターセット登録をサポートする必要がある場合 (サーバー サイロごとに個別の登録をサポートする場合など)、返されたハンドルをグローバル変数に格納するため、CTRPP で生成された Register 関数は機能しません。
サイロに依存しないカウンターセット登録を作成する場合、CTRPP によって生成された Register 関数は機能しません。これは、 を呼び出す
PcwRegister前に のRegInfo.Flags値を変更する方法がないためです。
このような場合は、CTRPP によって生成された Register 関数を呼び出す代わりに、次のようなコードを使用します。
PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);
// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.
// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);
CTRPP によって生成された InitRegistrationInformationXxx 関数は、マニフェストからの宣言に基づいて構造体を初期化 RegInfo します。 生成された InitRegistrationInformation 関数の詳細については、 PCW_REGISTRATION_INFORMATIONのドキュメントを参照してください。
Counterset の代わりに独自のハンドル変数を使用してハンドルを格納する場合は、CTRPP によって生成された UnregisterXxx 関数と PcwCreateInstanceCreateXxx 関数を使用する代わりに、 と を直接呼び出PcwUnregisterす必要がある場合もあります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 7 以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |