Funzione PcwRegister (wdm.h)

La PcwRegister funzione crea una nuova registrazione del contatore. La maggior parte degli sviluppatori userà una funzione RegisterXxx generata da CTRPP anziché chiamare direttamente questa funzione.

Sintassi

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

Parametri

[out] Registration

Puntatore a un PPCW_REGISTRATION. Riceve l'handle alla nuova registrazione. La registrazione deve essere chiusa usando PcwUnregister.

[in] Info

Puntatore a una struttura PCW_REGISTRATION_INFORMATION che contiene i dettagli relativi al contatore registrato.

Valore restituito

PcwRegister restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	Il contatore viene registrato correttamente.
STATUS_INTEGER_OVERFLOW	Il numero dei contatori esposti da questa registrazione supera il massimo supportato.
STATUS_NO_MEMORY	Non è disponibile spazio sufficiente per allocare memoria per i contatori.
STATUS_INVALID_PARAMETER_2	Si è verificato un problema nel Info parametro . Per alcune possibili cause, vedere di seguito.

PcwRegister può restituire STATUS_INVALID_PARAMETER_2 nei casi seguenti:

• Il Info->Name->Length campo è 0 o non è un multiplo di sizeof(WCHAR).

• Il Info->Version campo non corrisponde a un valore supportato per questa versione di Windows. Quando viene eseguito in Windows prima della versione 10.0.19645 (NTDDI_VERSION < NTDDI_VERSION_MN), il Version campo deve essere impostato su PCW_VERSION_1 (0x100). Quando viene eseguito in Windows 10.0.19645 e versioni successive (NTDDI_VERSION >= NTDDI_VERSION_MN), è possibile impostare su PCW_VERSION_1 (0x100) o PCW_VERSION_2 (0x200).

• Il Info->Flags campo contiene un valore non riconosciuto dalla versione in esecuzione di Windows.

Commenti

Il provider chiama questa funzione per creare una nuova registrazione del contatore. Tutti gli argomenti di input vengono acquisiti in modo che il chiamante non deve conservare una copia di essi.

Per impostazione predefinita, il nuovo contatore è visibile solo al silo del server attivo al momento della registrazione, ad esempio PcwRegister associa la registrazione appena creata al silo del server collegato al thread quando PcwRegister viene chiamato. Se in esecuzione in Windows 10.0.19645 e versioni successive (NTDDI_VERSION >= NTDDI_VERSION_MN) è possibile creare una registrazione contatore visibile a tutti i silo del server impostando PCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2 su e impostando PCW_REGISTRATION_INFORMATION::Flags su PcwRegistrationSiloNeutral.

Funzione RegisterXxx generata da CTRPP

La maggior parte degli sviluppatori non deve chiamare PcwRegister direttamente. Verranno invece compilati un manifesto con lo strumento CTRPP e useranno la funzione RegisterXxx dall'intestazione generata da CTRPP. La funzione generata avrà un aspetto simile al seguente:

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 funzione Di registrazione generata da CTRPP verrà denominataContatore registro prefisso. Il prefisso è in genere vuoto, ma può essere presente se il -prefix parametro è stato usato nella riga di comando CTRPP. Il contatore è il nome del contatore, come specificato nel manifesto. La funzione Register generata richiama la funzioneContatorePrefixInitRegistrationInformation per inizializzare una struttura e quindi richiamare PcwRegister per creare una PCW_REGISTRATION_INFORMATION nuova registrazione e archiviare l'handle nella variabile contatore globale (dichiarata nell'intestazione generata da CTRPP, MyCounterset nell'esempio).

In alcuni casi, la funzione Add generata da CTRPP potrebbe non essere appropriata.

• Se è necessario compilare con NTDDI_VERSION >= NTDDI_VERSION_FE ma deve essere eseguito nelle versioni precedenti di Windows, la funzione Register generata da CTRPP non funzionerà perché imposta RegInfo.Version = PCW_CURRENT_VERSION. Quando NTDDI_VERSION >= NTDDI_VERSION_FE, verrà impostato su PCW_VERSION_2, PCW_CURRENT_VERSION causando PcwRegister la restituzione di un errore.

• Se è necessario supportare più registrazioni contatori (ad esempio per supportare una registrazione separata per silo server), la funzione Registrazione generata da CTRPP non funzionerà perché archivia l'handle restituito in una variabile globale.

• Se si vuole creare una registrazione del contatore silo-neutrale, la funzione Register generata da CTRPP non funzionerà perché non è possibile modificare il valore di prima di RegInfo.Flags chiamare PcwRegister.

In questi casi, usare il codice simile al seguente anziché chiamare la funzione Register generata da 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 funzione InitRegistrationInformationXxx generata da CTRPP inizializza la RegInfo struttura in base alle dichiarazioni del manifesto. Per altre informazioni sulla funzione InitRegistrationInformation generata, vedere la documentazione per PCW_REGISTRATION_INFORMATION.

Se si usano variabili di handle personalizzate anziché Counterset per archiviare l'handle, potrebbe essere necessario chiamare PcwUnregister e PcwCreateInstance direttamente anziché usare le funzioni CTRPP generate da UnregisterXxx e CreateXxx .

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive di Windows.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

Vedi anche

PcwUnregister

_PCW_REGISTRATION_INFORMATION