PcwCreateInstance-Funktion (wdm.h)

Artikel
08/08/2023

Die PcwCreateInstance Funktion erstellt ein neues Gegenset instance. Die meisten Entwickler verwenden eine von CTRPP generierte CreateXxx-Funktion, anstatt diese Funktion direkt aufzurufen.

Syntax

NTSTATUS PcwCreateInstance(
  [out] PPCW_INSTANCE     *Instance,
  [in]  PPCW_REGISTRATION Registration,
  [in]  PCUNICODE_STRING  Name,
  [in]  ULONG             Count,
  [in]  PPCW_DATA         Data
);

Parameter

[out] Instance

Ein Zeiger zum Empfangen des neu erstellten instance. Die instance sollte mit PcwCloseInstance geschlossen werden.

[in] Registration

Ein Zeiger auf die Gegensatzregistrierung, die diese instance besitzt. Die Registrierung wird mit PcwRegister erstellt.

[in] Name

Ein Zeiger auf die Unicode-Zeichenfolge, die den Namen des instance des Countersets 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] 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. Auf die Datenblöcke, auf die von den Deskriptoren verwiesen wird, kann jederzeit zugegriffen werden und muss gültig bleiben, bis die instance von PcwCloseInstance oder PcwUnregistergeschlossen wird.

Rückgabewert

PcwCreateInstance gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
`STATUS_SUCCESS`	Die instance wurde erfolgreich erstellt.
`STATUS_INVALID_PARAMETER_4`	Die Anzahl von Strukturen, die durch `Count`angegeben wird, ist für den registrierten Anbieter ungültig.
`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 `PcwCreateInstance` an angibt, dass der erste Datenblock 50 Bytes beträgt, wird dieser Fehler status zurückgegeben.
`STATUS_INTEGER_OVERFLOW`	Die Größe der Struktur, die durch angegeben wird `Count`, überläuft den Datenpuffer.

Hinweise

Counterset-Anbieter können dem Verbraucher Informationen über zwei verschiedene Systeme bereitstellen:

Der Anbieter kann eine PCW_CALLBACK Funktion bereitstellen, die von der Leistungsindikatorbibliothek nach Bedarf aufgerufen wird, um Daten zu sammeln. Weitere Informationen zu diesem System finden Sie in der Dokumentation für PCW_CALLBACK.
Der Anbieter kann und verwenden PcwCreateInstance , PcwCloseInstance um eine Liste der verfügbaren Instanzen und die entsprechenden Zählerdaten zu verwalten. Dieses System ist einfach zu implementieren, aber begrenzt in der Flexibilität.

Bevor der Anbieter diese Funktion verwendet, muss der Anbieter die PcwRegister Funktion aufrufen, um eine Registrierung zu erstellen.

Wenn ein neuer instance eintrifft (z. B. wenn ein Gerät angeschlossen ist), sollte der Anbieter einen Datenblock für die instance zuordnen und initialisieren, mit dem Namen und dem Datenblock für den instance aufrufen PcwCreateInstance und dann die Werte im Datenblock mit Zählerwerten für die instance aktualisieren. Wenn die instance ungültig wird (z. B. wenn ein Gerät getrennt wird), sollte der Anbieter den Datenblock aufrufen PcwCloseInstance und dann löschen.

Der Anbieter muss Datenblöcke (in der Regel im ausgelagerten oder nicht ausgelagerten Pool) verwalten, die die aktuellen Zählerwerte für jede instance enthalten.

PcwCreateInstanceweist dem instance automatisch eine eindeutige ID zu. Um bestimmte Werte für die instance-ID bereitzustellen, implementieren Sie eine Funktion, anstatt zu PCW_CALLBACK verwendenPcwCreateInstance.

Verwenden Sie die Funktion PcwCloseInstance, um die instance zu schließen.

CTRPP-generierte CreateXxx-Funktion

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

EXTERN_C __inline NTSTATUS
CreateMyCounterset(
    __deref_out PPCW_INSTANCE *Instance,
    __in PCUNICODE_STRING Name,
    __in const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

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

    return PcwCreateInstance(Instance,
                             MyCounterset,
                             Name,
                             1,
                             Data);
}

Die von CTRPP generierte Create-Funktion heißt PräfixCreateCounterset. 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 PcwCreateInstance. Beachten Sie, dass die Funktion auf eine Counterset-Variable (MyCounterset im Beispiel) verweist, bei der es sich um eine globale Variable handelt, die das Von der CTRPP-generierten RegisterXxx-Funktion initialisierte Gegensetregistrierungshandle enthält.

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

PcwCloseInstance-Funktion

PcwRegister-Funktion

Freigeben über