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

Статья
03/08/2023

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

Синтаксис

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

Параметры

[out] Instance

Указатель для получения только что созданного экземпляра. Экземпляр должен быть закрыт с помощью PcwCloseInstance.

[in] Registration

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

[in] Name

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

Значения экземпляра Name должны быть стабильными с течением времени (один и тот же логический экземпляр должен использовать одно и то же Name значение для всех вызовов обратного вызова) и должны быть уникальными. Если набор счетчиков зарегистрирован как один экземпляр, экземпляр Name должен быть пустым (длина 0). Если набор счетчиков зарегистрирован как несколько экземпляров, экземпляр Name не должен быть пустым. При сопоставлении имен экземпляров регистр не учитывается, поэтому Name значения не должны отличаться только по регистру.

[in] Count

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

[in] Data

Массив дескрипторов для блоков данных поставщика, содержащих значения счетчиков данного экземпляра. Блоки данных, на которые ссылаются дескрипторы, могут быть доступны в любое время и должны оставаться действительными PcwCloseInstance до тех пор, пока экземпляр не будет закрыт или PcwUnregister.

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

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

Код возврата	Описание
`STATUS_SUCCESS`	Экземпляр успешно создан.
`STATUS_INVALID_PARAMETER_4`	Число структур, указанное параметром `Count`, недопустимо для зарегистрированного поставщика.
`STATUS_INVALID_BUFFER_SIZE`	Один из блоков данных поставщика слишком мал. Например, предположим, что во время вызова PcwRegister поставщик указывает, что счетчик `X` находится на смещении 100 первого блока данных размером 4 байта. Если вызов `PcwCreateInstance` указывает, что первый блок данных равен 50 байтам, возвращается это состояние ошибки.
`STATUS_INTEGER_OVERFLOW`	Размер структуры, заданный параметром `Count`, переполняет буфер данных.

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

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

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

Поставщик должен поддерживать блоки данных (как правило, в разгружаемом или невыгружаемом пуле), содержащие текущие значения счетчиков для каждого экземпляра.

PcwCreateInstance автоматически назначит уникальный идентификатор экземпляру. Чтобы указать определенные значения для идентификатора экземпляра, реализуйте функцию PCW_CALLBACK вместо использования PcwCreateInstance.

Используйте функцию PcwCloseInstance, чтобы закрыть экземпляр .

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

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

EXTERN_C __inline NTSTATUS
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

Функция Create, созданная CTRPP, будет называться ПрефиксСоздатьcounterset. Префикс обычно пуст, но может присутствовать, если -prefix параметр использовался в командной строке CTRPP. Counterset — это имя набора счетчиков, указанное в манифесте. Функция будет иметь параметры Data на основе структур, определенных в манифесте. Функция заключит предоставленные пользователем блоки данных в массив PCW_DATA структур, а затем вызовет PcwCreateInstance. Обратите внимание, что функция ссылается на переменную counterset (MyCounterset в примере), которая является глобальной переменной, содержащей дескриптор регистрации набора счетчиков, инициализированный функцией RegisterXxx, созданной CTRPP.

Требования

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

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

Функция PcwCloseInstance

Функция PcwRegister

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