Función PcwRegister (wdm.h)

La PcwRegister función crea un nuevo registro de conjunto de contadores. La mayoría de los desarrolladores usarán una función RegisterXxx generada por CTRPP en lugar de llamar a esta función directamente.

Sintaxis

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

Parámetros

[out] Registration

Puntero a un PPCW_REGISTRATION. Recibe el identificador del nuevo registro. El registro debe cerrarse con PcwUnregister.

[in] Info

Puntero a una estructura PCW_REGISTRATION_INFORMATION que contiene los detalles sobre el conjunto de contadores que se está registrando.

Valor devuelto

PcwRegister devuelve uno de los valores siguientes:

Código devuelto	Descripción
STATUS_SUCCESS	El conjunto de contadores se registra correctamente.
STATUS_INTEGER_OVERFLOW	El número de contadores expuestos por este registro supera el máximo admitido.
STATUS_NO_MEMORY	No hay suficiente espacio disponible para asignar memoria para los contadores.
STATUS_INVALID_PARAMETER_2	Se encontró un problema en el Info parámetro . Consulte a continuación algunas causas posibles.

PcwRegister puede devolver STATUS_INVALID_PARAMETER_2 en los casos siguientes:

• El Info->Name->Length campo es 0 o no es un múltiplo de sizeof(WCHAR).

• El Info->Version campo no coincide con un valor admitido para esta versión de Windows. 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), se puede establecer en PCW_VERSION_1 (0x100) o PCW_VERSION_2 (0x200).

• El Info->Flags campo contiene un valor no reconocido por la versión en ejecución de Windows.

Comentarios

El proveedor llama a esta función para crear un nuevo registro de conjunto de contadores. Todos los argumentos de entrada se capturan para que el autor de la llamada no tenga que conservar una copia de ellos.

De forma predeterminada, el nuevo conjunto de contadores solo es visible para el silo de servidor que estaba activo en el momento del registro (es decir, PcwRegister asocia el registro recién creado con el silo de servidor que se adjuntó al subproceso cuando PcwRegister se llama). Si se ejecuta en Windows 10.0.19645 y versiones posteriores (NTDDI_VERSION >= NTDDI_VERSION_MN), puede crear un registro de conjunto de contadores visible para todos los silos de servidor estableciendo PCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2 en y estableciendo PCW_REGISTRATION_INFORMATION::Flags en PcwRegistrationSiloNeutral.

Función RegisterXxx generada por CTRPP

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

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

La función Register generada por CTRPP se denominará PrefixRegisterCounterset. El prefijo suele estar en blanco, pero puede estar presente si el -prefix parámetro se usó en la línea de comandos CTRPP. Counterset es el nombre del conjunto de contadores, tal y como se especifica en el manifiesto. La función Register generada invocará la función PrefixInitRegistrationInformationCounterset para inicializar una estructura y, a continuación, invocará PcwRegister para crear un PCW_REGISTRATION_INFORMATION nuevo registro y almacenar el identificador en la variable global Counterset (declarada en el encabezado generado por CTRPP, MyCounterset en el ejemplo).

En algunos casos, es posible que la función Add generada por CTRPP no sea adecuada.

• Si debe compilar con NTDDI_VERSION >= NTDDI_VERSION_FE pero debe ejecutarse en versiones anteriores de Windows, la función Register generada por CTRPP no funcionará porque establece RegInfo.Version = PCW_CURRENT_VERSION. Cuando NTDDI_VERSION >= NTDDI_VERSION_FE, PCW_CURRENT_VERSION se establecerá en PCW_VERSION_2, lo que PcwRegister provocará que devuelva un error.

• Si necesita admitir varios registros de conjuntos de contadores (por ejemplo, para admitir un registro independiente por silo de servidor), la función Register generada por CTRPP no funcionará porque almacena el identificador devuelto en una variable global.

• Si desea crear un registro de conjunto de contadores silo-neutral, la función Register generada por CTRPP no funcionará porque no hay ninguna manera de cambiar el valor de antes de RegInfo.Flags llamar a PcwRegister.

En estos casos, use código como el siguiente en lugar de llamar a la función Register generada por CTRPP:

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

La función InitRegistrationInformationXxx generada por CTRPP inicializa la RegInfo estructura basada en declaraciones del manifiesto. Para obtener más información sobre la función InitRegistrationInformation generada, consulte la documentación de PCW_REGISTRATION_INFORMATION.

Si usa sus propias variables handle en lugar de Counterset para almacenar el identificador, es posible que también tenga que llamar PcwUnregister a y PcwCreateInstance directamente en lugar de usar las funciones UnregisterXxx y CreateXxx generadas 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

PcwUnregister

_PCW_REGISTRATION_INFORMATION