Функция 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 возвращает одно из следующих значений:

Комментарии

Функция 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.

Требования

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

функция обратного вызова PCW_CALLBACK