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

При работе в 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, созданных CTRPP, 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) Указывает, что эта регистрация должна быть видимой для потребителей во всех разрозненных серверах. По умолчанию регистрация видна только потребителям в серверном хранилище, который был активен при создании регистрации (т. е. регистрация, присоединенная к потоку при PcwRegister вызове).

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

Большинству разработчиков не нужно использовать 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, будет называться PrefixInitRegistrationInformationCounterset. Префикс обычно пуст, но может присутствовать, если -prefix параметр использовался в командной строке CTRPP. Counterset — это имя набора счетчиков, как указано в манифесте. Созданная функция InitRegistrationInformation инициализирует предоставленную PCW_REGISTRATION_INFORMATION структуру значениями из параметров функции и манифеста.

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