PM_COLLECT_PROC funzione di callback (winperf.h)

Articolo
03/04/2024

Raccoglie i dati sulle prestazioni e lo restituisce al consumer. Implementare ed esportare questa funzione se si sta scrivendo una DLL delle prestazioni per fornire dati sulle prestazioni. Il sistema chiama questa funzione ogni volta che un consumer esegue una query nel Registro di sistema per i dati sulle prestazioni.

La funzione CollectPerformanceData è un segnaposto per il nome della funzione definita dall'applicazione.

Sintassi

PM_COLLECT_PROC PmCollectProc;

DWORD PmCollectProc(
                 LPWSTR pValueName,
                 void **ppData,
                 DWORD *pcbTotalBytes,
                 DWORD *pNumObjectTypes
)
{...}

Parametri

pValueName

ppData

pcbTotalBytes

pNumObjectTypes

Valore restituito

Uno dei valori seguenti:

Codice restituito	Descrizione
ERROR_MORE_DATA	Le dimensioni del buffer pData (dove pData fa riferimento al puntatore a cui punta lppData) come specificato da lpcbTotalBytes non sono sufficienti per archiviare i dati. Lasciare invariato pData e impostare lpcbTotalBytes e lpNumObjectTypes su zero. Non viene effettuato alcun tentativo di indicare le dimensioni del buffer necessarie, perché può essere modificato prima della chiamata successiva.
ERROR_SUCCESS	Restituisce questo valore in tutti i casi diversi dal caso ERROR_MORE_DATA , anche se non vengono restituiti dati o si verifica un errore. Per segnalare errori diversi dalle dimensioni del buffer insufficienti, usare il registro eventi dell'applicazione.

Codice restituito

Descrizione

ERROR_MORE_DATA

Le dimensioni del buffer pData (dove pData fa riferimento al puntatore a cui punta lppData) come specificato da lpcbTotalBytes non sono sufficienti per archiviare i dati. Lasciare invariato pData e impostare lpcbTotalBytes e lpNumObjectTypes su zero. Non viene effettuato alcun tentativo di indicare le dimensioni del buffer necessarie, perché può essere modificato prima della chiamata successiva.

ERROR_SUCCESS

Restituisce questo valore in tutti i casi diversi dal caso ERROR_MORE_DATA , anche se non vengono restituiti dati o si verifica un errore. Per segnalare errori diversi dalle dimensioni del buffer insufficienti, usare il registro eventi dell'applicazione.

Commenti

Se gli oggetti richiesti specificati nel parametro lpValueName non corrispondono ad alcun indice dell'oggetto supportato dalla DLL delle prestazioni, lasciare invariato il parametro pData (dove pData fa riferimento al puntatore a cui punta lppData) e impostare i parametri lpcbTotalBytes e lpNumObjectTypes su zero. Indica che non sono stati restituiti dati.

Se si supporta uno o più oggetti sottoposti a query, determinare se le dimensioni del buffer pData specificato da lpcbTotalBytes sono sufficienti per archiviare i dati. In caso contrario, lasciare invariato pData e impostare lpcbTotalBytes e lpNumObjectTypes su zero. Non viene effettuato alcun tentativo di indicare le dimensioni del buffer necessarie, perché questa operazione può cambiare prima della chiamata successiva. Restituisce ERROR_MORE_DATA.

Se la raccolta dati richiede molto tempo, è consigliabile rispondere solo alle query per oggetti specifici o a query costose. È anche consigliabile ridurre la priorità del thread che raccoglie i dati, in modo che non influisca negativamente sulle prestazioni del sistema. Per il formato della stringa di query, vedere Uso delle funzioni del Registro di sistema per utilizzare i dati dei contatori.

Se il consumer è in esecuzione in un altro computer (in remoto), le funzioni OpenPerformanceData, ClosePerformanceData e CollectPerformanceData vengono chiamate nel contesto del processo Winlogon, che gestisce il lato server della connessione remota. Questa distinzione è importante per la risoluzione dei problemi che si verificano solo in remoto.

Al termine della restituzione della funzione, il sistema può eseguire alcuni test di base per garantire l'integrità dei dati. Per impostazione predefinita, non vengono eseguiti test. Se un test ha esito negativo, il sistema genera un messaggio del registro eventi e i dati vengono eliminati per evitare eventuali altri problemi dovuti a puntatori non validi. Il valore del Registro di sistema seguente controlla il livello di test: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel.

Di seguito sono riportati i possibili livelli di test per ExtCounterTestLevel.

Level	Significato
1	Testare i puntatori e i buffer delle DLL dei contatori attendibili. Invia una copia del buffer dell'utente.
2	Testare i puntatori e le lunghezze del buffer, ma non testa i riferimenti al puntatore o il contenuto del buffer. Invia una copia del buffer dell'utente.
3	Non testare puntatori o buffer. Invia una copia del buffer dell'utente.
4	Non testare puntatori o buffer. Invia il buffer dell'utente, non una copia. Si tratta del valore predefinito.

I test seguenti vengono eseguiti ai livelli 1 e 2:

Verifica che il valore di lpcbTotalBytes sia coerente con il puntatore al buffer restituito, pData. Se si aggiunge il valore lpcbTotalBytes al puntatore del buffer originale passato a questa funzione, è necessario terminare con lo stesso puntatore del buffer restituito da questa funzione. Se non sono uguali, viene registrato un messaggio di errore e i dati vengono ignorati.
Verificare che non sia stato eseguito un sovraccarico del buffer. Il sistema aggiunge una pagina di protezione da 1 KB prima e dopo il buffer allocato dal consumer. Se il puntatore al buffer restituito, pData, punta oltre il primo byte della pagina di protezione aggiunta, si presuppone che il buffer non sia valido e che i dati vengano ignorati. Se il puntatore al buffer supera la fine del buffer, ma non la fine della pagina di protezione, viene registrato un errore di overrun del buffer. Se il puntatore al buffer supera la fine della pagina di protezione, viene registrato un errore dell'heap perché l'heap da cui è stato allocato il buffer potrebbe essere stato danneggiato, causando altri errori di memoria.
Verificare che le pagine di protezione non siano state danneggiate. Le pagine di protezione da 1 KB aggiunte prima e dopo l'inizializzazione del buffer con un modello di dati prima della chiamata a questa funzione. Questo modello di dati viene controllato dopo la restituzione della procedura di raccolta. Se viene rilevata una discrepanza, si presuppone un sovraccarico del buffer o un altro errore di memoria e i dati vengono ignorati.

I test seguenti vengono eseguiti solo se viene usato il livello di test 1:

Verificare che la somma del membro TotalByteLength di ogni oggetto corrisponda al valore di lpcbTotalBytes. In caso contrario, i dati vengono ignorati.
Verificare che il membro ByteLength di ogni istanza sia coerente. Le lunghezze sono coerenti se l'oggetto successivo o la fine del buffer segue l'ultima istanza. In caso contrario, i dati vengono ignorati.

Esempio

Vedere Implementazione di CollectPerformanceData.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winperf.h

Condividi tramite