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 disizeof(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
), ilVersion
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::Version
PCW_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é impostaRegInfo.Version = PCW_CURRENT_VERSION
. QuandoNTDDI_VERSION >= NTDDI_VERSION_FE
, verrà impostato suPCW_VERSION_2
,PCW_CURRENT_VERSION
causandoPcwRegister
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
chiamarePcwRegister
.
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 |