Función PcwAddInstance (wdm.h)

La PcwAddInstance función agrega la instancia especificada del conjunto de contadores al búfer del consumidor. La mayoría de los desarrolladores usarán una función AddXxx generada por CTRPP en lugar de llamar a esta función directamente. Consulta los comentarios a continuación para obtener más información.

Sintaxis

NTSTATUS PcwAddInstance(
  [in] PPCW_BUFFER      Buffer,
  [in] PCUNICODE_STRING Name,
  [in] ULONG            Id,
  [in] ULONG            Count,
  [in] PPCW_DATA        Data
);

Parámetros

[in] Buffer

Identificador del búfer administrado por el sistema al que se agregará la instancia del conjunto de contadores. Cuando el búfer proceda de una PcwCallbackEnumerateInstances notificación, PcwAddInstance registrará solo el nombre y el identificador de la instancia. Cuando el búfer proceda de una PcwCallbackCollectData notificación, PcwAddInstance registrará el nombre, el identificador y los datos (valores de contador) de la instancia.

[in] Name

Puntero a la cadena Unicode que contiene el nombre de la instancia del conjunto de contadores. Esto no debe ser NULL.

Los valores de instancia Name DEBEN ser estables con el tiempo (la misma instancia lógica debe usar el mismo Name valor para todas las invocaciones de la devolución de llamada) y DEBEN ser únicos. Si el conjunto de contadores se registra como instancia única, la instancia Name debe estar en blanco (0 longitud). Si el conjunto de contadores registrado como instancias múltiples, la instancia Name no debe estar en blanco. La coincidencia de nombres de instancia no distingue mayúsculas de minúsculas, por lo que Name los valores no deben diferir solo por mayúsculas y minúsculas.

[in] Id

Valor numérico que especifica el Id (identificador) asociado a la instancia del conjunto de contadores.

Los valores de instancia Id DEBEN ser estables con el tiempo (la misma instancia debe usar el mismo Id valor para todas las invocaciones de la devolución de llamada), deben ser únicos (por ejemplo, no use 0 para todas las instancias) y deben ser menores que 0xFFFFFFFE (no use PCW_ANY_INSTANCE_ID para ninguna instancia). Cuando sea posible, la instancia Id debe ser significativa (por ejemplo, un conjunto de contadores de procesos podría usar un PID como Id) en lugar de arbitrario (por ejemplo, un número de secuencia).

[in] Count

Número de descriptores proporcionados en el Data parámetro .

[in] Data

Matriz de descriptores para los bloques de datos del proveedor que contienen los valores de contador de esta instancia.

Valor devuelto

PcwAddInstance devuelve uno de los siguientes valores:

Código devuelto	Descripción
STATUS_SUCCESS	La instancia se agregó correctamente al búfer.
STATUS_INVALID_BUFFER_SIZE	Uno de los bloques de datos del proveedor es demasiado pequeño. Por ejemplo, supongamos que durante la llamada a PcwRegister, el proveedor especifica que el contador X está en desplazamiento 100 del primer bloque de datos de tamaño 4 bytes. Si la llamada a PcwAddInstance especifica que el primer bloque de datos es de 50 bytes, se devuelve este estado de error.

Comentarios

La PcwAddInstance función debe llamar a la rutina de PCW_CALLBACK definida por el proveedor cuando el tipo de notificación es PcwCallbackEnumerateInstances o PcwCallbackCollectData. El Buffer que se va a usar procede del Info parámetro para la PCW_CALLBACK rutina, por ejemplo Info->EnumerateInstances.Buffer , o Info->CollectData.Buffer.

Cuando se llama a para una PcwCallbackEnumerateInstances notificación, PcwAddInstance agrega los Name valores y Id al búfer. Cuando se llama a para una PcwCallbackCollectData notificación, PcwAddInstance agrega los Namevalores de datos de contador , Idy al búfer.

Función Add*** generada por CTRPP

La mayoría de los desarrolladores no necesitan llamar PcwAddInstance directamente. En su lugar, compilarán un manifiesto con la herramienta CTRPP y usarán la función Add*** del encabezado generado por CTRPP. La función generada tendrá este aspecto:

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);
}

La función Add generada por CTRPP se denominará PrefixAddCounterset. El prefijo suele estar en blanco, pero puede estar presente si el -prefix parámetro se usó en la línea de comandos de CTRPP. Counterset es el nombre del conjunto de contadores, como se especifica en el manifiesto. La función tendrá parámetros data en función de las estructuras definidas en el manifiesto. La función encapsulará los bloques de datos proporcionados por el usuario en una matriz de PCW_DATA estructuras y, a continuación, llamará a PcwAddInstance.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 7 y versiones posteriores de Windows.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

Consulte también

PCW_CALLBACK función de devolución de llamada