次の方法で共有

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

こちらもご覧ください

PcwCloseInstance 関数

PcwRegister 関数