PM_COLLECT_PROC Rückruffunktion (winperf.h)

  • Artikel

Erfasst die Leistungsdaten und gibt sie an den Consumer zurück. Implementieren und exportieren Sie diese Funktion, wenn Sie eine Leistungs-DLL schreiben, um Leistungsdaten bereitzustellen. Das System ruft diese Funktion auf, wenn ein Consumer die Registrierung nach Leistungsdaten fragt.

Die CollectPerformanceData-Funktion ist ein Platzhalter für den anwendungsdefinierte Funktionsnamen.

Syntax

PM_COLLECT_PROC PmCollectProc;

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

Parameter

pValueName

ppData

pcbTotalBytes

pNumObjectTypes

Rückgabewert

Einer der folgenden Werte:

Rückgabecode Beschreibung
ERROR_MORE_DATA Die Von lpcbTotalBytes angegebene Größe des pData-Puffers (wobei pData auf den Zeiger verweist, auf den von lppData verwiesen wird) ist nicht groß genug, um die Daten zu speichern. Lassen Sie pData unverändert, und legen Sie lpcbTotalBytes und lpNumObjectTypes auf 0 fest. Es wird nicht versucht, die erforderliche Puffergröße anzugeben, da sich dies vor dem nächsten Aufruf ändern kann.
ERROR_SUCCESS Geben Sie diesen Wert in allen anderen Fällen als im ERROR_MORE_DATA Fall zurück, auch wenn keine Daten zurückgegeben werden oder ein Fehler auftritt. Verwenden Sie das Anwendungsereignisprotokoll, um andere Fehler als die unzureichende Puffergröße zu melden.

Hinweise

Wenn die angeforderten Objekte, die im lpValueName-Parameter angegeben sind, keinem der von Ihrer Leistungs-DLL unterstützten Objektindizes entsprechen, lassen Sie den pData-Parameter unverändert (wobei pData auf den Zeiger verweist, auf den von lppData verwiesen wird), und legen Sie die Parameter lpcbTotalBytes und lpNumObjectTypes auf Null fest. Dies gibt an, dass keine Daten zurückgegeben wurden.

Wenn Sie mindestens eins der abgefragten Objekte unterstützen, bestimmen Sie, ob die größe des pData-Puffers , wie von lpcbTotalBytes angegeben, groß genug ist, um die Daten zu speichern. Wenn nicht, lassen Sie pData unverändert, und legen Sie lpcbTotalBytes und lpNumObjectTypes auf 0 fest. Es wird nicht versucht, die erforderliche Puffergröße anzugeben, da sich dies vor dem nächsten Aufruf ändern kann. Gibt ERROR_MORE_DATA zurück.

Wenn Ihre Datensammlung zeitaufwändig ist, sollten Sie nur auf Abfragen für bestimmte Objekte oder kostspielige Abfragen reagieren. Sie sollten auch die Priorität des Threads senken, der die Daten sammelt, damit die Systemleistung nicht beeinträchtigt wird. Informationen zum Abfragezeichenfolgenformat finden Sie unter Verwenden der Registrierungsfunktionen zum Nutzen von Zählerdaten.

Wenn der Consumer auf einem anderen Computer (remote) ausgeführt wird, werden die Funktionen OpenPerformanceData, ClosePerformanceData und CollectPerformanceData im Kontext des Winlogon-Prozesses aufgerufen, der die Serverseite der Remoteverbindung verarbeitet. Diese Unterscheidung ist wichtig bei der Problembehandlung von Problemen, die nur remote auftreten.

Nachdem Ihre Funktion erfolgreich zurückgegeben wurde, kann das System einige grundlegende Tests durchführen, um die Integrität der Daten sicherzustellen. Standardmäßig werden keine Tests durchgeführt. Wenn ein Test fehlschlägt, generiert das System eine Ereignisprotokollmeldung, und die Daten werden verworfen, um weitere Probleme aufgrund ungültiger Zeiger zu verhindern. Der folgende Registrierungswert steuert die Testebene: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Perflib\ExtCounterTestLevel.

Im Folgenden sind die möglichen Teststufen für ExtCounterTestLevel aufgeführt.

Ebene Bedeutung
1 Testen Sie die Zeiger und Puffer von vertrauenswürdigen Indikator-DLLs. Sendet eine Kopie des Puffers des Benutzers.
2 Testen Sie Zeiger und Pufferlängen, aber keine Zeigerverweise oder Pufferinhalte. Sendet eine Kopie des Puffers des Benutzers.
3 Testen Sie keine Zeiger oder Puffer. Sendet eine Kopie des Puffers des Benutzers.
4 Testen Sie keine Zeiger oder Puffer. Sendet den Puffer des Benutzers, nicht eine Kopie. Dies ist der Standardwert.

Die folgenden Tests werden auf den Ebenen 1 und 2 durchgeführt:

  • Überprüft, ob der Wert von lpcbTotalBytes mit dem zurückgegebenen Pufferzeiger pData konsistent ist. Wenn Sie dem ursprünglichen Pufferzeiger, der an diese Funktion übergeben wurde, den Wert lpcbTotalBytes hinzufügen, sollten Sie denselben Pufferzeiger erhalten, der von dieser Funktion zurückgegeben wird. Wenn sie nicht identisch sind, wird eine Fehlermeldung protokolliert, und die Daten werden ignoriert.
  • Vergewissern Sie sich, dass kein Pufferüberlauf aufgetreten ist. Das System fügt eine 1-KB-Schutzseite vor und nach dem vom Consumer zugewiesenen Puffer hinzu. Wenn der zurückgegebene Pufferzeiger pData über das erste Byte der angefügten Schutzseite hinaus zeigt, wird davon ausgegangen, dass der Puffer ungültig ist und die Daten ignoriert werden. Wenn der Pufferzeiger das Ende des Puffers, aber nicht das Ende der Schutzseite überschreitet, wird ein Pufferüberlauffehler protokolliert. Wenn sich der Pufferzeiger am Ende der Schutzseite befindet, wird ein Heapfehler protokolliert, da der Heap, von dem der Puffer zugeordnet wurde, beschädigt sein könnte, was zu anderen Speicherfehlern führte.
  • Vergewissern Sie sich, dass die Schutzseiten nicht beschädigt wurden. Die 1-KB-Schutzseiten, die vor und nach dem Puffer hinzugefügt wurden, werden mit einem Datenmuster initialisiert, bevor diese Funktion aufgerufen wird. Dieses Datenmuster wird überprüft, nachdem die Sammelprozedur zurückgegeben wurde. Wenn Abweichungen erkannt werden, wird eine Pufferüberlaufung oder ein anderer Speicherfehler angenommen, und die Daten werden ignoriert.

Die folgenden Tests werden nur durchgeführt, wenn die Teststufe 1 verwendet wird:

  • Stellen Sie sicher, dass die Summe des TotalByteLength-Elements jedes Objekts mit dem Wert von lpcbTotalBytes übereinstimmt. Andernfalls werden die Daten ignoriert.
  • Vergewissern Sie sich, dass das ByteLength-Element jedes instance konsistent ist. Die Längen sind konsistent, wenn das nächste Objekt oder ende des Puffers auf die letzte instance folgt. Andernfalls werden die Daten ignoriert.

Beispiele

Weitere Informationen finden Sie unter Implementieren von CollectPerformanceData.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winperf.h

Weitere Informationen