Функция PcwRegister (wdm.h)

Статья
08/08/2023

Функция PcwRegister создает новую регистрацию набора счетчиков. Большинство разработчиков будут использовать созданную CTRPP функцию RegisterXxx вместо прямого вызова этой функции.

Синтаксис

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

Параметры

[out] Registration

Указатель на PPCW_REGISTRATION. Получает дескриптор новой регистрации. Регистрация должна быть закрыта с помощью PcwUnregister.

[in] Info

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

Возвращаемое значение

PcwRegister возвращает одно из следующих значений:

Код возврата	Описание
`STATUS_SUCCESS`	Набор счетчиков успешно зарегистрирован.
`STATUS_INTEGER_OVERFLOW`	Количество счетчиков, предоставляемых этой регистрацией, превышает максимальное поддерживаемого значения.
`STATUS_NO_MEMORY`	Недостаточно места для выделения памяти счетчикам.
`STATUS_INVALID_PARAMETER_2`	В параметре обнаружена `Info` проблема. Некоторые возможные причины см. ниже.

PcwRegister может возвращать данные STATUS_INVALID_PARAMETER_2 в следующих случаях:

Поле Info->Name->Length равно 0 или не кратно sizeof(WCHAR).
Поле Info->Version не соответствует поддерживаемое значение для этой версии Windows. При работе в 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).
Поле Info->Flags содержит значение, которое не распознается работающей версией Windows.

Поставщик вызывает эту функцию для создания новой регистрации набора счетчиков. Все входные аргументы записываются таким образом, что вызывающему объекту не нужно хранить их копию.

По умолчанию новый набор счетчиков отображается только для сервера, который был активен во время регистрации (т. е. PcwRegister связывает созданную регистрацию с серверным хранилищем, подключенным к потоку при PcwRegister вызове ). При запуске в Windows 10.0.19645 и более поздних версий (NTDDI_VERSION >= NTDDI_VERSION_MN) можно создать регистрацию набора счетчиков, видимую для всех серверных разрозненных серверов, задав значение PCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2 , а — значение PCW_REGISTRATION_INFORMATION::FlagsPcwRegistrationSiloNeutral.

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

Большинству разработчиков не нужно вызывать PcwRegister напрямую. Вместо этого они компилируют манифест с помощью средства CTRPP и используют функцию RegisterXxx из созданного CTRPP заголовка. Созданная функция будет выглядеть следующим образом:

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

Созданная CTRPP функция Register будет называться ПрефиксRegisterCounterset. Префикс обычно пуст, но может присутствовать, если -prefix параметр использовался в командной строке CTRPP. Counterset — это имя набора счетчиков, указанное в манифесте. Созданная функция Register вызовет функцию PrefixInitRegistrationInformationCounterset для инициализации PCW_REGISTRATION_INFORMATION структуры, а затем вызовет PcwRegister для создания новой регистрации и сохранения дескриптора в глобальной переменной Counterset (в примере объявленной в заголовке MyCounterset CTRPP).

В некоторых случаях созданная CTRPP функция Add может быть неуместна.

Если необходимо выполнить компиляцию с NTDDI_VERSION >= NTDDI_VERSION_FE помощью , но она должна выполняться в более ранних версиях Windows, функция Register, созданная CTRPP, не будет работать, так как она задает RegInfo.Version = PCW_CURRENT_VERSION. При NTDDI_VERSION >= NTDDI_VERSION_FEзначении PCW_CURRENT_VERSION будет задано значение PCW_VERSION_2, что приводит PcwRegister к возврату ошибки.
Если требуется поддержка регистрации нескольких наборов счетчиков (например, для поддержки отдельной регистрации для каждого серверного хранилища), созданная CTRPP функция Register не будет работать, так как она сохраняет возвращенный дескриптор в глобальной переменной.
Если вы хотите создать регистрацию набора счетчиков, не зависящий от распределения, функция Register, созданная CTRPP, не будет работать, так как невозможно изменить значение RegInfo.Flags перед вызовом PcwRegister.

В таких случаях вместо вызова функции Register, созданной CTRPP, используйте следующий код:

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

Созданная CTRPP функция InitRegistrationInformationXxx инициализирует структуру RegInfo на основе объявлений из манифеста. Дополнительные сведения о созданной функции InitRegistrationInformation см. в документации по PCW_REGISTRATION_INFORMATION.

Если для хранения дескриптора используются собственные переменные дескриптора вместо counterset , может потребоваться вызвать PcwUnregister и PcwCreateInstance напрямую вместо использования созданных CTRPP функций Отменить регистрациюXxx и CreateXxx .

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows 7 и более поздних версиях Windows.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

См. также раздел

PcwUnregister

_PCW_REGISTRATION_INFORMATION

Поделиться через