Función PcwCreateInstance (wdm.h)

La PcwCreateInstance función crea una nueva instancia de conjunto de contadores. La mayoría de los desarrolladores usarán una función CreateXxx generada por CTRPP en lugar de llamar a esta función directamente.

Sintaxis

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

Parámetros

[out] Instance

Puntero para recibir la instancia recién creada. La instancia debe cerrarse con PcwCloseInstance.

[in] Registration

Puntero al registro del conjunto de contadores que posee esta instancia. El registro se crea mediante PcwRegister.

[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] 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. Los bloques de datos a los que hacen referencia los descriptores se pueden tener acceso en cualquier momento y deben permanecer válidos hasta que la instancia esté cerrada por PcwCloseInstance o PcwUnregister.

Valor devuelto

PcwCreateInstance devuelve uno de los siguientes valores:

Código devuelto	Descripción
STATUS_SUCCESS	La instancia se creó correctamente.
STATUS_INVALID_PARAMETER_4	El número de estructuras, especificadas por Count, no es válida para el proveedor registrado.
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 PcwCreateInstance especifica que el primer bloque de datos es de 50 bytes, se devuelve este estado de error.
STATUS_INTEGER_OVERFLOW	El tamaño de la estructura, especificado por Count, desborda el búfer de datos.

Comentarios

Los proveedores de conjuntos de contadores pueden proporcionar información al consumidor a través de dos sistemas diferentes:

• El proveedor puede proporcionar una PCW_CALLBACK función que la biblioteca de contadores de rendimiento invocará según sea necesario para recopilar datos. Para obtener más información sobre este sistema, consulte la documentación de PCW_CALLBACK.
• El proveedor puede usar PcwCreateInstance y PcwCloseInstance para mantener una lista de instancias disponibles y los datos de contador correspondientes. Este sistema es sencillo de implementar pero limitado en flexibilidad.

Antes de que el proveedor use esta función, el proveedor debe llamar a la PcwRegister función para crear un registro.

Cuando llega una nueva instancia (por ejemplo, cuando un dispositivo está conectado), el proveedor debe asignar e inicializar un bloque de datos para la instancia, llamar a PcwCreateInstance con el nombre y el bloque de datos de la instancia y, a continuación, mantener los valores en el bloque de datos actualizados con valores de contador para la instancia. Cuando la instancia deja de ser válida (por ejemplo, cuando un dispositivo está desconectado), el proveedor debe llamar a PcwCloseInstance y, a continuación, eliminar el bloque de datos.

El proveedor debe mantener bloques de datos (normalmente en grupos paginados o no paginados) que contengan los valores de contador actuales para cada instancia.

PcwCreateInstance asignará automáticamente un identificador único para la instancia. Para proporcionar valores específicos para el identificador de instancia, implemente una PCW_CALLBACK función en lugar de usar PcwCreateInstance.

Use la función PcwCloseInstance para cerrar la instancia.

Función CreateXxx generada por CTRPP

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

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

La función Create generada por CTRPP se denominará PrefixCreateCounterset. 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 PcwCreateInstance. Tenga en cuenta que la función hace referencia a una variable Counterset (MyCounterset en el ejemplo), que es una variable global que contiene el identificador de registro del conjunto de contadores inicializado por la función RegisterXxx generada por CTRPP.

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

Función PcwCloseInstance

Función PcwRegister