PCW_REGISTRATION_INFORMATION 構造体 (wdm.h)

[アーティクル]
03/08/2023

PCW_REGISTRATION_INFORMATION構造体は、プロバイダーとカウンターセットに関する詳細を提供します。ほとんどの開発者は、この構造体を直接使用する代わりに、 CTRPP によって生成された 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 () より前の Windows で実行する場合は、フィールドを Version PCW_VERSION_1 (NTDDI_VERSION < NTDDI_VERSION_MN0x100) に設定する必要があります。 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

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

Callback

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

CallbackContext

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

Flags

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

FlagsフィールドがよりPCW_VERSION_2小さい場合、Versionフィールドは無視されます。

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

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