PCW_REGISTRATION_INFORMATION構造体 (wdm.h)

[アーティクル]
02/07/2025

PCW_REGISTRATION_INFORMATION 構造体は、プロバイダーとカウンターセットに関する詳細を提供します。ほとんどの開発者は、この構造体を直接使用する代わりに、CTRPP-generated RegisterXxx または InitRegistrationInformationXxx 関数を使用します。

構文

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

メンバーズ

Version

プロバイダーが必要とする Windows (PCW) のパフォーマンスカウンターのバージョンを指定する数値。

10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN) より前の Windows で実行する場合は、Version フィールドを PCW_VERSION_1 (0x100) に設定する必要があります。 Windows 10.0.19645 以降 (NTDDI_VERSION >= NTDDI_VERSION_MN) で実行する場合は、PCW_VERSION_1 (0x100) またはPCW_VERSION_2 (0x200) に設定できます。 Version フィールドが認識できない値に設定されている場合、PcwRegister はSTATUS_INVALID_PARAMETER_2を返します。

CTRPP で生成された RegisterXxx または InitRegistrationInformationXxx 関数を使用する場合、Version フィールドは PCW_CURRENT_VERSIONに設定されます。これは、NTDDI_VERSIONのコンパイル時の値に応じて、次のいずれかの値に相当します。

条件	PCW_CURRENT_VERSION値
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

コードが NTDDI_VERSION >= NTDDI_WIN10_FE でビルドされていても、以前のバージョンの Windows で実行する必要がある場合は、PcwRegisterのドキュメントで説明されているように Version = PCW_VERSION_1 を設定する必要があります。

Name

登録するカウンターセットの名前を含む文字列へのポインター。この文字列は NULL または空白にすることはできません。

カウンターセット名の比較では、大文字と小文字は区別されないことに注意してください。 2 つのカウンターセット登録で同じカウンターセット名が使用されている場合、コンシューマーは両方の登録からデータを収集します。

CounterCount

Counters パラメーターで指定された記述子の数。

Counters

このカウンターセットのカウンターの記述子の配列。記述子からの情報は、PcwCreateInstance または PcwAddInstanceの呼び出しによって提供されるデータブロックからカウンター値を抽出するときに使用されます。

Callback

このカウンターセットに関連するイベントについてプロバイダーに通知する省略可能な PCW_CALLBACK コールバック関数へのポインター。このフィールドは、コールバックが必要ない場合 (つまり、カウンターセットインスタンスが PcwCreateInstance および PcwCloseInstanceを介して管理される場合) に NULL になる可能性があります。

CallbackContext

呼び出されるたびにプロバイダー定義の PCW_CALLBACK コールバック関数に渡されるポインター値。

Flags

Flags フィールドは、NTDDI_VERSION >= NTDDI_WIN10_MN場合にのみ使用できます。

Version フィールドが PCW_VERSION_2未満の場合、Flags フィールドは無視されます。

Flags フィールドを使用すると、PcwRegisterの特殊な動作が可能になります。 1 つ以上の PCW_REGISTRATION_FLAGS 値の組み合わせに設定します。

PCW_REGISTRATION_FLAGS	意味
PcwRegistrationNone (0x0)	既定値 (特別な動作は必要ありません)。
PcwRegistrationSiloNeutral (0x1)	この登録をすべてのサーバーサイロのコンシューマーに表示する必要があることを示します。既定では、登録は、登録の作成時にアクティブだったサーバーサイロ内のコンシューマー (つまり、`PcwRegister` が呼び出されたときにスレッドにアタッチされた登録) にのみ表示されます。

備考

PcwRegister 関数は、この構造体へのポインターである Info パラメーターを受け取ります。

CTRPP によって生成された InitRegistrationInformationXxx 関数

ほとんどの開発者は、PCW_REGISTRATION_INFORMATION を直接使用する必要はありません。代わりに、CTRPP ツールを使用してマニフェストをコンパイルし、CTRPP で生成されたヘッダーから RegisterXxx または InitRegistrationInformationXxx 関数を使用します。生成された Register 関数は InitRegistrationInformation を呼び出し、PcwRegister を呼び出します (詳細については、PcwRegister を参照してください)。生成された InitRegistrationInformation 関数は次のようになります。

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

CTRPP によって生成された InitRegistrationInformation 関数には、Prefix InitRegistrationInformationCountersetという名前が付けられます。 Prefix は通常空白ですが、-prefix パラメーターが CTRPP コマンドラインで使用された場合は存在する可能性があります。 Counterset は、マニフェストで指定されているカウンターセットの名前です。生成された InitRegistrationInformation 関数は、指定された PCW_REGISTRATION_INFORMATION 構造体を関数パラメーターとマニフェストの値で初期化します。

CTRPP によって生成された InitRegistrationInformation 関数は、必要に応じて、構造体メンバーのサイズがマニフェストで宣言されているサイズと一致することを確認できます。既定では、CTRPP_VERIFY_COUNTER_SIZES は 0 に設定され、このチェックは無効になっています。このチェックを有効にするには、CTRPP で生成されたヘッダーを含める前に #define CTRPP_VERIFY_COUNTER_SIZES 1 します。チェックが有効になっている場合、サイズの不一致により、C_ASSERT条件のエラーが原因でコンパイルエラーがトリガーされます。

必要条件

要件	価値
ヘッダー	wdm.h (Wdm.h、Ntddk.h を含む)

次の方法で共有

PCW_REGISTRATION_INFORMATION構造体 (wdm.h)

構文

メンバーズ

備考

CTRPP によって生成された InitRegistrationInformationXxx 関数

必要条件

関連項目

フィードバック

その他のリソース