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 |