структура PCW_REGISTRATION_INFORMATION (wdm.h)

Статья
02/07/2025

Структура 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), необходимых поставщику.

При запуске в Windows до 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN) поле 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.

При использовании функций 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, необходимо задать Version = PCW_VERSION_1, как описано в документации по PcwRegister.

Name

Указатель на строку, содержащую имя набора счетчиков для регистрации. Эта строка не должна иметь значение NULL или пуста.

Обратите внимание, что сравнения имен счетчиков не учитывает регистр. Если одно и то же имя счетчика используется в двух регистрациях счетчиков, потребители будут собирать данные из обеих регистраций.

CounterCount

Количество дескрипторов, указанных в параметре Counters.

Counters

Массив дескрипторов для счетчиков этого набора счетчиков. Сведения из дескрипторов будут использоваться при извлечении значений счетчиков из блоков данных, предоставляемых вызовами PcwCreateInstance или PcwAddInstance.

Callback

Указатель на необязательную функцию обратного вызова PCW_CALLBACK, которая уведомляет поставщика о событиях, связанных с этим набором счетчиков. Это поле может иметь значение NULL, если обратный вызов не нужен (т. е. если экземпляры счетчиков будут управляться с помощью PcwCreateInstance и PcwCloseInstance).

CallbackContext

Значение указателя, которое будет передаваться в определяемую поставщиком функцию обратного вызова PCW_CALLBACK при каждом вызове.

Flags

Поле Flags доступно только в том случае, если NTDDI_VERSION >= NTDDI_WIN10_MN.

Поле Flags будет игнорироваться, если поле Version меньше PCW_VERSION_2.

Поле Flags обеспечивает специальное поведение PcwRegister. Задайте сочетание одного или нескольких значений PCW_REGISTRATION_FLAGS:

PCW_REGISTRATION_FLAGS Значение

PcwRegistrationNone (0x0) Значение по умолчанию (не требуется специальных действий).

PcwRegistrationSiloNeutral (0x1) Указывает, что эта регистрация должна быть видна потребителям во всех серверных оси. По умолчанию регистрация отображается только для потребителей в сервере silo, активной при создании регистрации (т. е. регистрации, присоединенной к потоку при вызове PcwRegister).

PCW_REGISTRATION_FLAGS	Значение
PcwRegistrationNone (0x0)	Значение по умолчанию (не требуется специальных действий).
PcwRegistrationSiloNeutral (0x1)	Указывает, что эта регистрация должна быть видна потребителям во всех серверных оси. По умолчанию регистрация отображается только для потребителей в сервере silo, активной при создании регистрации (т. е. регистрации, присоединенной к потоку при вызове `PcwRegister`).

Замечания

Функция PcwRegister принимает параметр Info, который является указателем на эту структуру.

Функция InitRegistrationInformationXx, созданная CTRPP

Большинству разработчиков не нужно напрямую использовать PCW_REGISTRATION_INFORMATION. Вместо этого они компилируют манифест с помощью средства CTRPP и используют функции RegisterXxx или InitRegistrationInformationXxx из заголовка CTRPP. Созданная функция 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;
}

Функция InitRegistrationInformation cTRPP будет называться префиксомInitRegistrationInformationсчетчиков. префикс обычно пуст, но может присутствовать, если параметр -prefix использовался в командной строке CTRPP. набор счетчиков — это имя набора счетчиков, как указано в манифесте. Созданная функция InitRegistrationInformation инициализирует предоставленную PCW_REGISTRATION_INFORMATION структуру со значениями из параметров функции и манифеста.

Функция InitRegistrationInformation, созданная CTRPP, может при необходимости убедиться, что размеры элементов структуры соответствуют размерам, объявленным в манифесте. По умолчанию CTRPP_VERIFY_COUNTER_SIZES имеет значение 0, отключив эту проверку. Чтобы включить эту проверку, #define CTRPP_VERIFY_COUNTER_SIZES 1 перед включением заголовка CTRPP. Если проверка включена, несоответствие размера приведет к возникновению ошибки компиляции из-за сбоя условия C_ASSERT.