estructura PCW_REGISTRATION_INFORMATION (wdm.h)

Artículo
03/08/2023

La estructura PCW_REGISTRATION_INFORMATION proporciona detalles sobre el proveedor y el conjunto de contadores. La mayoría de los desarrolladores usarán las funciones RegisterXxx o InitRegistrationInformationXxx generadas por CTRPP en lugar de usar esta estructura directamente.

Sintaxis

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

Miembros

Version

Valor numérico que especifica la versión de contadores de rendimiento para Windows (PCW) que requiere el proveedor.

Cuando se ejecuta en Windows antes de la versión 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), el Version campo debe establecerse en PCW_VERSION_1 (0x100). Cuando se ejecuta en Windows 10.0.19645 y versiones posteriores (NTDDI_VERSION >= NTDDI_VERSION_MN), puede establecerse en PCW_VERSION_1 (0x100) o PCW_VERSION_2 (0x200). Si el Version campo se establece en un valor no reconocido, PcwRegister devolverá STATUS_INVALID_PARAMETER_2.

Al usar las funciones RegisterXxx o InitRegistrationInformationXxx generadas por CTRPP, el Version campo se establecerá PCW_CURRENT_VERSIONen , que equivale a uno de los valores siguientes, según el valor en tiempo de compilación de NTDDI_VERSION:

Condición	valor de PCW_CURRENT_VERSION
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

Si el código se compila con NTDDI_VERSION >= NTDDI_WIN10_FE pero necesita ejecutarse en una versión anterior de Windows, deberá establecer Version = PCW_VERSION_1 como se describe en la documentación de PcwRegister.

Name

Puntero a la cadena que contiene el nombre del conjunto de contadores que se va a registrar. Esta cadena no debe ser NULL ni estar en blanco.

Tenga en cuenta que las comparaciones de nombres del conjunto de contadores no distinguen mayúsculas de minúsculas. Si se usa el mismo nombre de conjunto de contadores en dos registros de conjuntos de contadores, los consumidores recopilarán datos de ambos registros.

CounterCount

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

Counters

Matriz de descriptores para los contadores de este conjunto de contadores. La información de los descriptores se usará al extraer valores de contador de bloques de datos proporcionados por llamadas a PcwCreateInstance o PcwAddInstance.

Callback

Puntero a la función de devolución de llamada opcional PCW_CALLBACK que notifica al proveedor los eventos relacionados con este conjunto de contadores. Este campo puede ser NULL si la devolución de llamada no es necesaria (es decir, si las instancias del conjunto de contadores se administrarán a través PcwCreateInstance de y PcwCloseInstance).

CallbackContext

Valor de puntero que se pasará a la función de devolución de llamada definida por PCW_CALLBACK el proveedor cada vez que se invoque.

Flags

El Flags campo solo está disponible cuando NTDDI_VERSION >= NTDDI_WIN10_MN.

El Flags campo se omitirá si el Version campo es menor que PCW_VERSION_2.

El campo habilita el Flags comportamiento especial de PcwRegister. Establezca en una combinación de uno o varios PCW_REGISTRATION_FLAGS valores:

PCW_REGISTRATION_FLAGS	Significado
PcwRegistrationNone (0x0)	Valor predeterminado (no se requieren comportamientos especiales).
PcwRegistrationSiloNeutral (0x1)	Indica que este registro debe ser visible para los consumidores en todos los silos de servidor. De forma predeterminada, un registro solo es visible para los consumidores del silo de servidor que estaba activo cuando se creó el registro (es decir, el registro que se adjuntó al subproceso cuando `PcwRegister` se llamó).

Comentarios

La función PcwRegister toma un Info parámetro que es un puntero a esta estructura.

Función InitRegistrationInformationXxx generada por CTRPP

La mayoría de los desarrolladores no necesitan usar PCW_REGISTRATION_INFORMATION directamente. En su lugar, compilarán un manifiesto con la herramienta CTRPP y usarán las funciones RegisterXxx o InitRegistrationInformationXxx desde el encabezado generado por CTRPP. La función Register generada llama a InitRegistrationInformation y, a continuación, llama a PcwRegister (consulte PcwRegister para obtener más información). La función InitRegistrationInformation generada tendrá el siguiente aspecto:

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

La función InitRegistrationInformation generada por CTRPP se denominará PrefixInitRegistrationInformationCounterset. 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 InitRegistrationInformation generada inicializará la estructura proporcionada PCW_REGISTRATION_INFORMATION con valores de los parámetros de función y el manifiesto.

La función InitRegistrationInformation generada por CTRPP puede comprobar opcionalmente que los tamaños de los miembros de la estructura coincidan con los tamaños declarados en el manifiesto. De forma predeterminada, CTRPP_VERIFY_COUNTER_SIZES se establece en 0, deshabilitando esta comprobación. Para habilitar esta comprobación, #define CTRPP_VERIFY_COUNTER_SIZES 1 antes de incluir el encabezado generado por CTRPP. Si la comprobación está habilitada, una discrepancia de tamaño desencadenará un error de compilación debido a un error de C_ASSERT condición.