PcwAddInstance-Funktion (wdm.h)

Die PcwAddInstance Funktion fügt dem Consumerpuffer die angegebene instance des Gegensatzes hinzu. Die meisten Entwickler verwenden eine von CTRPP generierte AddXxx-Funktion, anstatt diese Funktion direkt aufzurufen. Weitere Informationen finden Sie unter Hinweise unten.

Syntax

NTSTATUS PcwAddInstance(
  [in] PPCW_BUFFER      Buffer,
  [in] PCUNICODE_STRING Name,
  [in] ULONG            Id,
  [in] ULONG            Count,
  [in] PPCW_DATA        Data
);

Parameter

[in] Buffer

Ein Handle für den vom System verwalteten Puffer, dem die instance des Countersets hinzugefügt wird. Wenn der Puffer aus einer PcwCallbackEnumerateInstances Benachrichtigung stammt, PcwAddInstance werden nur der Name und die ID des instance. Wenn der Puffer aus einer PcwCallbackCollectData Benachrichtigung stammt, PcwAddInstance werden Name, ID und Daten (Zählerwerte) des instance.

[in] Name

Ein Zeiger auf die Unicode-Zeichenfolge, die den Namen des Gegensatzes instance enthält. Dies darf nicht NULL sein.

Instanzwerte Name MÜSSEN im Laufe der Zeit stabil sein (dieselbe logische instance sollte für alle Aufrufe des Rückrufs den gleichen Name Wert verwenden) und MÜSSEN eindeutig sein. Wenn das Zählerset als single-instance registriert ist, sollte die instance Name leer (0 Länge) sein. Wenn die Zählermenge als multi-instance registriert ist, sollte die instance Name nicht leer sein. Bei der Abgleichung von Instanznamen wird die Groß-/Kleinschreibung nicht beachtet. Daher Name sollten sich die Werte nicht nur nach Groß- und Kleinschreibung unterscheiden.

[in] Id

Ein numerischer Wert, der den Id (Bezeichner) angibt, der dem Gegensatz instance zugeordnet ist.

Instanzwerte Id MÜSSEN im Laufe der Zeit stabil sein (derselbe instance sollte für alle Aufrufe des Rückrufs denselben Id Wert verwenden), sollten eindeutig sein (z. B. nicht 0 für alle Instanzen verwenden), und sollten kleiner als 0xFFFFFFFE sein (nicht für Instanzen verwendenPCW_ANY_INSTANCE_ID). Wenn möglich, sollte die instance Id sinnvoll sein (z. B. kann ein Process-Zählerset eine PID als Id) anstelle von willkürlich (z. B. eine Sequenznummer) verwenden.

[in] Count

Die Anzahl der im Data Parameter angegebenen Deskriptoren.

[in] Data

Ein Array von Deskriptoren für die Anbieterdatenblöcke, die die Zählerwerte dieser instance enthalten.

Rückgabewert

PcwAddInstance gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die instance wurde dem Puffer erfolgreich hinzugefügt.
STATUS_INVALID_BUFFER_SIZE	Einer der Anbieterdatenblöcke ist zu klein. Angenommen, während des Aufrufs von PcwRegister gibt der Anbieter an, dass sich der Zähler X im Offset 100 des ersten Datenblocks der Größe 4 Bytes befindet. Wenn der Aufruf von PcwAddInstance an angibt, dass der erste Datenblock 50 Bytes beträgt, wird dieser Fehler status zurückgegeben.

Hinweise

Die PcwAddInstance Funktion sollte vom vom Anbieter definierten PCW_CALLBACK Routine aufgerufen werden, wenn der Benachrichtigungstyp entweder PcwCallbackEnumerateInstances oder PcwCallbackCollectDataist. Der Buffer zu verwendende stammt aus dem Info Parameter für die PCW_CALLBACK Routine, z. B. Info->EnumerateInstances.Buffer oder Info->CollectData.Buffer.

Wenn sie für eine PcwCallbackEnumerateInstances Benachrichtigung aufgerufen werden, PcwAddInstance fügt sie dem Puffer die Name Werte und Id hinzu. Wenn sie für eine PcwCallbackCollectData Benachrichtigung aufgerufen werden, PcwAddInstance fügt sie dem Puffer die NameDatenwerte , Id, und hinzu.

CTRPP-generierte Add***-Funktion

Die meisten Entwickler müssen nicht direkt aufrufen PcwAddInstance . Stattdessen kompilieren sie ein Manifest mit dem CTRPP-Tool und verwenden die Add***-Funktion aus dem CTRPP-generierten Header. Die generierte Funktion sieht wie folgt aus:

EXTERN_C __inline NTSTATUS
AddMyCounterset(
    __in PPCW_BUFFER Buffer,
    __in PCUNICODE_STRING Name,
    __in ULONG Id,
    __in_opt const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwAddInstance(Buffer,
                          Name,
                          Id,
                          1,
                          Data);
}

Die von CTRPP generierte Add-Funktion heißt PräfixAddCounterset. Das Präfix ist normalerweise leer, kann aber vorhanden sein, wenn der -prefix Parameter in der CTRPP-Befehlszeile verwendet wurde. Counterset ist der Name des Countersets, wie im Manifest angegeben. Die Funktion verfügt über Datenparameter, die auf den im Manifest definierten Strukturen basieren. Die Funktion umschließt die vom Benutzer bereitgestellten Datenblöcke in ein Array von PCW_DATA Strukturen und ruft dann auf PcwAddInstance.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 7 und späteren Windows-Versionen.
Zielplattform	Universell
Header	wdm.h (include Wdm.h, Ntddk.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

Weitere Informationen

PCW_CALLBACK Rückruffunktion