CmCallbackGetKeyObjectIDEx-Funktion (wdm.h)

Artikel
02/27/2024

Die CmCallbackGetKeyObjectIDEx-Routine ruft den eindeutigen Bezeichner und objektnamen ab, die einem angegebenen Registrierungsschlüsselobjekt zugeordnet sind.

Diese Routine ist ab Windows 8 verfügbar. Verwenden Sie in früheren Versionen von Windows stattdessen die CmCallbackGetKeyObjectID-Routine . Weitere Informationen finden Sie weiter unten im Abschnitt Hinweise .

Syntax

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

Parameter

[in] Cookie

Ein Cookiewert, der die Registrierung des Aufrufers zum Empfangen von Registrierungsfilterrückrufen darstellt. Der Treiber hat diesen Cookiewert zuvor aus der CmRegisterCallback - oder CmRegisterCallbackEx-Routine abgerufen.

[in] Object

Ein Zeiger auf das Registrierungsschlüsselobjekt. Dieser Parameter ist der Zeigerwert, den die RegistryCallback-Rückrufroutine des Treibers im Object-Member einer der REG_XXX_KEY_INFORMATION strukturen empfangen hat.

Warnung

Unter bestimmten Umständen können Registrierungsrückrufbenachrichtigungsstrukturen ungültige Nicht-NULL-Objektzeiger enthalten. Registrierungsfiltertreiber dürfen solche Zeiger nicht an diese Routine übergeben. Weitere Informationen finden Sie unter Ungültige Schlüsselobjektzeiger in Registrierungsbenachrichtigungen.

[out, optional] ObjectID

Ein Zeiger auf einen Speicherort, der einen Zeiger auf den Schlüsselbezeichner für den Registrierungsschlüssel empfängt, den Object darstellt. Dieser Bezeichner ist für alle Schlüssel in der Registrierung eindeutig. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie weiter unten im Abschnitt Hinweise .

[out, optional] ObjectName

Ein Zeiger auf eine Position, die einen Zeiger auf eine UNICODE_STRING Struktur empfängt. Diese Struktur enthält den Objektnamen des Registrierungsschlüsselobjekts, das Object angibt. Der Objektname ist tatsächlich der vollständige Pfadname des Registrierungsschlüssels, den das Objekt darstellt. Der Aufrufer ist für das Freigeben dieser Struktur verantwortlich, indem er die CmCallbackReleaseKeyObjectIDEx-Routine aufruft. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie in den Hinweisen.

[in] Flags

Reserviert. Auf NULL festlegen.

Rückgabewert

CmCallbackGetKeyObjectIDEx gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Mögliche Fehlerrückgabewerte umfassen den folgenden status Code:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der Cookie-, Object- oder Flags-Parameter ist ungültig.

Hinweise

Treiber können CmCallbackGetKeyObjectIDEx verwenden, um den Registrierungsschlüsselbezeichner, den Objektnamen oder beides abzurufen, indem sie Werte ohne NULL für die Parameter ObjectID oder ObjectName angeben.

Der Aufrufer kann den Schlüsselbezeichner über den ObjectID-Parameter abrufen. Wenn zwei Registrierungsschlüsselobjekte denselben Registrierungsschlüssel darstellen, sind die Schlüsselbezeichner, die von CmCallbackGetKeyObjectIDEx für die beiden Objekte abgerufen wurden, identisch. Wenn sich der Name des Registrierungsschlüssels ändert, wird der Schlüsselbezeichner, der von CmCallbackGetKeyObjectIDEx abgerufen wurde, nicht geändert. Der Aufrufer kann den Schlüsselbezeichner verwenden, um Zugriffe, die über mehrere Schlüsselobjekte auf einen bestimmten Registrierungsschlüssel vorgenommen werden, zuverlässig nachzuverfolgen, und sogar über Änderungen am Namen des Registrierungsschlüssels hinweg.

Der Aufrufer kann den Objektnamen über den ObjectName-Parameter abrufen. Der Speicher für die UNICODE_STRING-Struktur , die den Objektnamen enthält, bleibt gültig, bis der Aufrufer CmCallbackReleaseKeyObjectIDEx aufruft, um die Struktur frei zu geben.

CmCallbackGetKeyObjectIDEx ist eine verbesserte Version der CmCallbackGetKeyObjectID-Routine , die ab Windows Vista verfügbar ist. Treiber, die in Versionen von Windows vor Windows 8 ausgeführt werden, sollten CmCallbackGetKeyObjectID anstelle von CmCallbackGetKeyObjectIDEx aufrufen. Treiber, die nur in Windows 8 und höheren Versionen von Windows ausgeführt werden, sollten CmCallbackGetKeyObjectIDEx anstelle von CmCallbackGetKeyObjectID aufrufen.

CmCallbackGetKeyObjectIDEx verfügt über zwei wichtige Features, die in CmCallbackGetKeyObjectID nicht verfügbar sind.

Zunächst ermöglicht CmCallbackGetKeyObjectIDEx einem Registrierungsfiltertreiber, die Lebensdauer der ObjectName-Struktur explizit zu steuern. Der Treiber kann cmCallbackReleaseKeyObjectIDEx jederzeit aufrufen, um diese Struktur freizusetzen. Im Gegensatz dazu kann der Treiber die Von CmCallbackGetKeyObjectID empfangene ObjectName-Struktur nicht explizit freigeben. Diese Struktur wird automatisch freigegeben, wenn alle Handles für den Schlüssel geschlossen werden.

Zweitens: Wenn ein Registrierungsfiltertreiber CmCallbackGetKeyObjectID aufruft, um einen ObjectName-Strukturzeiger abzurufen, und sich nach diesem Aufruf der Name des Registrierungsschlüssels ändert, erhalten nachfolgende Aufrufe von CmCallbackGetKeyObjectID einen Zeiger auf eine veraltete Kopie der ObjectName-Struktur , die den alten Schlüsselnamen enthält. Die veraltete Kopie dieser Struktur bleibt bestehen, bis alle Handles für den Schlüssel geschlossen werden. Im Gegensatz dazu enthält die von CmCallbackGetKeyObjectIDEx abgerufene ObjectName-Struktur immer den aktuellsten Schlüsselnamen.

Weitere Informationen zu Registrierungsfiltertreibern finden Sie unter Filtern von Registrierungsaufrufen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL