PcwCreateInstance 関数 (wdm.h)
関数は PcwCreateInstance 、新しいカウンターセット インスタンスを作成します。 ほとんどの開発者は、この関数を直接呼び出す代わりに 、CTRPP によって生成された CreateXxx 関数を使用します。
構文
NTSTATUS PcwCreateInstance(
[out] PPCW_INSTANCE *Instance,
[in] PPCW_REGISTRATION Registration,
[in] PCUNICODE_STRING Name,
[in] ULONG Count,
[in] PPCW_DATA Data
);
パラメーター
[out] Instance
新しく作成されたインスタンスを受け取るポインター。 インスタンスは PcwCloseInstance を使用して閉じる必要があります。
[in] Registration
このインスタンスを所有するカウンターセット登録へのポインター。 登録は PcwRegister を使用して作成されます。
[in] Name
カウンターセットのインスタンスの名前を含む Unicode 文字列へのポインター。 NULL にすることはできません。
インスタンス Name の値は、時間の経過と同時に安定している必要があります (同じ論理インスタンスがコールバックのすべての呼び出しに同じ Name 値を使用する必要があります)。また、一意である必要があります。 カウンターセットが単一インスタンスとして登録されている場合、インスタンス Name は空白 (0 長) である必要があります。 カウンターセットがマルチインスタンスとして登録されている場合は、インスタンス Name を空白にしないでください。 インスタンス名の一致では大文字と小文字が区別されないため Name 、値は大文字と小文字のみで異なるべきではありません。
[in] Count
パラメーターに指定された記述子の Data 数。
[in] Data
このインスタンスのカウンター値を含むプロバイダー データ ブロックの記述子の配列。 記述子によって参照されるデータ ブロックには、いつでもアクセスでき、インスタンスが または PcwUnregisterによってPcwCloseInstance閉じられるまで有効なままである必要があります。
戻り値
PcwCreateInstance は、次のいずれかの値を返します。
| リターン コード | 説明 |
|---|---|
STATUS_SUCCESS |
インスタンスが正常に作成されました。 |
STATUS_INVALID_PARAMETER_4 |
で Count指定された構造体の数が、登録済みプロバイダーに対して無効です。 |
STATUS_INVALID_BUFFER_SIZE |
プロバイダー データ ブロックの 1 つが小さすぎます。 たとえば、 PcwRegister の呼び出し中に、プロバイダーは、サイズ 4 バイトの最初のデータ ブロックのオフセット 100 にあるカウンター X を指定するとします。 の PcwCreateInstance 呼び出しで、最初のデータ ブロックが 50 バイトであることを指定した場合、このエラー状態が返されます。 |
STATUS_INTEGER_OVERFLOW |
で指定された構造体のサイズは Count、データ バッファーをオーバーフローします。 |
注釈
カウンターセット プロバイダーは、次の 2 つの異なるシステムを介してコンシューマーに情報を提供できます。
- プロバイダーは、データを
PCW_CALLBACK収集するために必要に応じてパフォーマンス カウンター ライブラリによって呼び出される関数を提供できます。 このシステムの詳細については、 PCW_CALLBACKに関するドキュメントを参照してください。 - プロバイダーは、 と
PcwCloseInstanceを使用PcwCreateInstanceして、使用可能なインスタンスと対応するカウンター データの一覧を維持できます。 このシステムは簡単に実装できますが、柔軟性は限られています。
プロバイダーがこの関数を使用する前に、プロバイダーは 関数を PcwRegister 呼び出して登録を作成する必要があります。
新しいインスタンスが到着すると (デバイスが接続されている場合など)、プロバイダーはインスタンスのデータ ブロックを割り当てて初期化し、インスタンスの名前とデータ ブロックを使用して を呼び出 PcwCreateInstance し、データ ブロック内の値をインスタンスのカウンター値で更新したままにする必要があります。 インスタンスが無効になると (デバイスが取り外された場合など)、プロバイダーは データ ブロックを呼び出 PcwCloseInstance して削除する必要があります。
プロバイダーは、各インスタンスの現在のカウンター値を含むデータ ブロック (通常はページ プールまたは非ページ プール内) を維持する必要があります。
PcwCreateInstance は、インスタンスの一意の ID を自動的に割り当てます。 インスタンス ID に特定の値を指定するには、 を使用する代わりに 関数をPCW_CALLBACKPcwCreateInstance実装します。
PcwCloseInstance 関数を使用してインスタンスを閉じます。
CTRPP によって生成された CreateXxx 関数
ほとんどの開発者は、 を直接呼び出す PcwCreateInstance 必要はありません。 代わりに、CTRPP ツールを使用してマニフェストをコンパイルし、CTRPP によって生成されたヘッダーから CreateXxx 関数を使用します。 生成された関数は次のようになります。
EXTERN_C __inline NTSTATUS
CreateMyCounterset(
__deref_out PPCW_INSTANCE *Instance,
__in PCUNICODE_STRING Name,
__in const MY_COUNTER_DATA *MyCounterData
)
{
PCW_DATA Data[1];
PAGED_CODE();
Data[0].Data = MyCounterData;
Data[0].Size = sizeof(MY_COUNTER_DATA);
return PcwCreateInstance(Instance,
MyCounterset,
Name,
1,
Data);
}
CTRPP によって生成される Create 関数には、 PrefixCreate Counterset という名前が付けられます。 プレフィックス は通常空白ですが、パラメーターが CTRPP コマンド ラインで使用された場合 -prefix は存在する可能性があります。 Counterset は、マニフェストで指定されているカウンターセットの名前です。 関数には、マニフェストで定義されている構造に基づく Data パラメーターがあります。 関数は、ユーザー指定のデータ ブロックを構造体の PCW_DATA 配列にラップし、 を呼び出します PcwCreateInstance。 関数は Counterset 変数 (MyCounterset の例) を参照しています。これは、CTRPP によって生成された RegisterXxx 関数によって初期化されたカウンターセット登録ハンドルを保持するグローバル変数です。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 7 以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |