Функция PcwAddInstance (wdm.h)
Функция PcwAddInstance
добавляет указанный экземпляр набора счетчиков в буфер потребителя. Большинство разработчиков будут использовать функцию AddXxx, созданную CTRPP, вместо того чтобы вызывать эту функцию напрямую. Дополнительные сведения см. в разделе Примечания ниже.
Синтаксис
NTSTATUS PcwAddInstance(
[in] PPCW_BUFFER Buffer,
[in] PCUNICODE_STRING Name,
[in] ULONG Id,
[in] ULONG Count,
[in] PPCW_DATA Data
);
Параметры
[in] Buffer
Дескриптор управляемого системой буфера, в который будет добавлен экземпляр набора счетчиков. Когда буфер поступает из PcwCallbackEnumerateInstances
уведомления, PcwAddInstance
записывает только имя и идентификатор экземпляра. Когда буфер поступает из PcwCallbackCollectData
уведомления, PcwAddInstance
записывает значения Name, Id и Data (значения счетчиков) экземпляра.
[in] Name
Указатель на строку Юникода, содержащую имя экземпляра набора счетчиков. Это значение не должно иметь значение NULL.
Значения экземпляра Name
должны быть стабильными с течением времени (один и тот же логический экземпляр должен использовать одно и то же Name
значение для всех вызовов обратного вызова) и должны быть уникальными. Если набор счетчиков зарегистрирован как один экземпляр, экземпляр Name
должен быть пустым (длина 0). Если набор счетчиков зарегистрирован как многоэкземлярный, экземпляр Name
не должен быть пустым. При сопоставлении имен экземпляров регистр не учитывается, поэтому Name
значения не должны отличаться только по регистру.
[in] Id
Числовое значение, указывающее Id
(идентификатор), связанный с экземпляром набора счетчиков.
Значения экземпляра Id
должны быть стабильными с течением времени (один и тот же экземпляр должен использовать одно и то же Id
значение для всех вызовов обратного вызова), быть уникальными (например, не использовать 0 для всех экземпляров) и быть меньше 0xFFFFFFFE (не использовать PCW_ANY_INSTANCE_ID
для каких-либо экземпляров). По возможности экземпляр Id
должен быть значимым (например, набор счетчиков process может использовать PID в качестве Id
) вместо произвольного (например, порядковый номер).
[in] Count
Количество дескрипторов, указанных в параметре Data
.
[in] Data
Массив дескрипторов для блоков данных поставщика, содержащих значения счетчиков данного экземпляра.
Возвращаемое значение
PcwAddInstance
возвращает одно из следующих значений:
Код возврата | Описание |
---|---|
STATUS_SUCCESS |
Экземпляр успешно добавлен в буфер. |
STATUS_INVALID_BUFFER_SIZE |
Один из блоков данных поставщика слишком мал. Например, предположим, что во время вызова PcwRegister поставщик указывает, что счетчик X имеет смещение 100 первого блока данных размером 4 байта. Если вызов PcwAddInstance указывает, что первый блок данных равен 50 байтам, возвращается это состояние ошибки. |
Комментарии
Функция PcwAddInstance
должна вызываться PCW_CALLBACK подпрограммой , определяемой поставщиком, если тип уведомления имеет значение PcwCallbackEnumerateInstances
или PcwCallbackCollectData
. Используемый Buffer
объект исходит из Info
параметра для подпрограммы PCW_CALLBACK
, например Info->EnumerateInstances.Buffer
или Info->CollectData.Buffer
.
При вызове PcwCallbackEnumerateInstances
уведомления PcwAddInstance
добавляет Name
значения и Id
в буфер. При вызове PcwCallbackCollectData
для уведомления PcwAddInstance
добавляет значения данных счетчика Name
, Id
и в буфер.
Функция Add***, созданная CTRPP
Большинству разработчиков не нужно вызывать PcwAddInstance
напрямую. Вместо этого они компилируют манифест с помощью средства CTRPP и используют функцию Add*** из заголовка, созданного CTRPP. Созданная функция будет выглядеть следующим образом:
EXTERN_C __inline NTSTATUS
AddMyCounterset(
__in PPCW_BUFFER Buffer,
__in PCUNICODE_STRING Name,
__in ULONG Id,
__in_opt const MY_COUNTER_DATA *MyCounterData
)
{
PCW_DATA Data[1];
PAGED_CODE();
Data[0].Data = MyCounterData;
Data[0].Size = sizeof(MY_COUNTER_DATA);
return PcwAddInstance(Buffer,
Name,
Id,
1,
Data);
}
Функция Add, созданная CTRPP, будет называться ПрефиксДобавитьсчетчик. Префикс обычно пуст, но может присутствовать, если -prefix
параметр использовался в командной строке CTRPP. Counterset — это имя набора счетчиков, как указано в манифесте. Функция будет иметь параметры Data на основе структур, определенных в манифесте. Функция заключит предоставленные пользователем блоки данных в массив PCW_DATA
структур, а затем вызовет PcwAddInstance
.
Требования
Требование | Значение |
---|---|
Минимальная версия клиента | Доступно в Windows 7 и более поздних версиях Windows. |
Целевая платформа | Универсальное |
Верхняя часть | wdm.h (включая Wdm.h, Ntddk.h) |
Библиотека | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | IRQL <= APC_LEVEL |