PERFLIBREQUEST-Rückruffunktion (perflib.h)

Artikel
08/25/2023

Anbieter können diese Funktion implementieren, um Benachrichtigungen zu erhalten, wenn Consumer bestimmte Aktionen ausführen, z. B. das Hinzufügen oder Entfernen von Indikatoren zu einer Abfrage. PERFLIB ruft den Rückruf auf, bevor die Anforderung des Consumers abgeschlossen ist.

Der PERFLIBREQUEST-Typ definiert einen Zeiger auf diese Rückruffunktion. Die ControlCallback-Funktion ist ein Platzhalter für den anwendungsdefinierte Funktionsnamen.

Syntax

PERFLIBREQUEST Perflibrequest;

ULONG Perflibrequest(
  [in] ULONG RequestCode,
  [in] PVOID Buffer,
  [in] ULONG BufferSize
)
{...}

Parameter

[in] RequestCode

Der Anforderungscode kann einer der folgenden Werte sein.

Wert	Bedeutung
PERF_ADD_COUNTER	Der Consumer fügt der Abfrage einen Zähler hinzu. PERFLIB ruft den Rückruf mit diesem Anforderungscode für jeden Leistungsindikator auf, der der Abfrage hinzugefügt wird. Der Buffer-Parameter enthält eine PERF_COUNTER_IDENTITY-Struktur , die den hinzugefügten Zähler identifiziert. Anbieter können diese Benachrichtigung verwenden, um mit dem Zählen zu beginnen.
PERF_REMOVE_COUNTER	Der Consumer entfernt einen Zähler aus der Abfrage. PERFLIB ruft den Rückruf mit diesem Anforderungscode für jeden Leistungsindikator auf, der aus der Abfrage entfernt wird. Der Parameter Buffer enthält eine PERF_COUNTER_IDENTITY-Struktur , die den zu entfernenden Indikator identifiziert. Anbieter können diese Benachrichtigung verwenden, um das Zählen zu beenden.
PERF_ENUM_INSTANCES	Der Consumer listet Instanzen des Leistungsindikatorsatzes auf. Der Buffer-Parameter enthält eine Unicode-Zeichenfolge mit NULL-Beendigung, die den Namen des Computers (oder seiner IP-Adresse) identifiziert, von dem der Consumer die Instanzen aufzählt.
PERF_COLLECT_START	Der Consumer beginnt mit der Erfassung von Zählerdaten. Der Buffer-Parameter enthält eine Unicode-Zeichenfolge mit NULL-Termin, die den Namen des Computers (oder seiner IP-Adresse) identifiziert, von dem der Consumer Daten sammelt. Anbieter können diese Benachrichtigung verwenden, wenn der Rohdatenzustand kritisch ist (z. B. transaktionsbezogene Leistungsindikatoren, bei denen partielle Updates nicht zulässig sind). Diese Benachrichtigung gibt dem Anbieter die Möglichkeit, alle ausstehenden Updates zu leeren und zukünftige Updates zu sperren, bevor die Sammlung beginnt.
PERF_COLLECT_END	Die Zählerdatensammlung ist abgeschlossen. Der Buffer-Parameter enthält eine Unicode-Zeichenfolge mit NULL-Termin, die den Namen des Computers (oder seiner IP-Adresse) identifiziert, von dem der Consumer Daten gesammelt hat. Anbieter können diese Benachrichtigung verwenden, um die update-Sperre, die durch die Sammlungsstartbenachrichtigung verhängt wurde, aufzuheben, damit Updates der Zählerdaten fortgesetzt werden können.

[in] Buffer

Der Inhalt des Puffers hängt von der Anforderung ab. Mögliche Inhalte finden Sie im RequestCode-Parameter .

[in] BufferSize

Größe des Buffer-Parameters in Byte.

Rückgabewert

Gibt ERROR_SUCCESS zurück, wenn der Rückruf erfolgreich ist.

Wenn der Rückruf fehlschlägt, gibt PERFLIB den Fehlercode an den Consumer zurück, wenn die Anforderung PERF_ADD_COUNTER, PERF_ENUM_INSTANCES oder PERF_COLLECT_START ist. Andernfalls wird der Fehlercode ignoriert.

Hinweise

Wenn das Rückrufattribut des Anbieterelements "custom" lautet oder Sie beim Aufrufen von CTRPP das Argument -NotificationCallback verwendet haben, müssen Sie diese Funktion implementieren. Sie übergeben den Namen Ihrer Rückruffunktion an CounterInitialize.

Windows Vista: Die CounterInitialize-Funktion heißt PerfAutoInitialize. Das CTRPP-Tool generiert auch ein Gerüst dieses Rückrufs für Sie, das alle Anforderungscodes enthält. Anschließend fügen Sie code zu den Anforderungscodes hinzu, die Sie unterstützen möchten, und entfernen die anderen.

Der Rückruf muss innerhalb einer Sekunde abgeschlossen werden. Wenn der Rückruf nicht rechtzeitig abgeschlossen wird, setzt PERFLIB mit der Anforderung des Consumers fort und ignoriert den Rückgabewert des Rückrufs, wenn er abgeschlossen ist.

Beispiele

Das folgende Beispiel zeigt eine einfache Implementierung einer ControlCallback-Funktion .

ULONG MyControlCallback(ULONG RequestCode, PVOID pBuffer, ULONG* pBufferSize)
{
    ULONG Status = ERROR_SUCCESS;
    PWNODE_HEADER Wnode = (PWNODE_HEADER)pBuffer;
    LPWSTR pComputerName = NULL;
    LPWSTR pInstance = NULL;
    PPERF_COUNTER_IDENTITY pCounter;
    UNREFERENCED_PARAMETER(pBufferSize);

    switch (RequestCode) 
    {
        case PERF_ADD_COUNTER:
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0) 
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_REMOVE_COUNTER: 
            pCounter = (PPERF_COUNTER_IDENTITY)(((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            pComputerName = (LPWSTR)(((LPBYTE) pCounter) + pCounter->MachineOffset);
            pInstance = (pCounter->NameOffset > 0)
                ? (LPWSTR) (((LPBYTE) pCounter) + pCounter->NameOffset) : NULL;
            
            break;

        case PERF_ENUM_INSTANCES:
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_START: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        case PERF_COLLECT_END: 
            pComputerName = (LPWSTR) (((LPBYTE) Wnode) + sizeof(WNODE_HEADER));
            
            break;

        default:
            wprintf(L"Unknown request code, %lu\n", RequestCode);
    }

    return Status;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	perflib.h

Freigeben über