CmCallbackGetKeyObjectIDEx-Funktion (wdm.h)
Die CmCallbackGetKeyObjectIDEx Routine ruft den eindeutigen Bezeichner und objektnamen ab, der einem angegebenen Registrierungsschlüsselobjekt zugeordnet ist.
Diese Routine ist ab Windows 8 verfügbar. Verwenden Sie in früheren Versionen von Windows stattdessen die CmCallbackGetKeyObjectID Routine. Weitere Informationen finden Sie im Abschnitt Anmerkungen weiter unten.
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- Callbackroutine 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 eine Position, die einen Zeiger auf den Schlüsselbezeichner für den Registrierungsschlüssel empfängt, der Object darstellt. Dieser Bezeichner ist für alle Schlüssel in der Registrierung eindeutig. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen finden Sie im Abschnitt Anmerkungen weiter unten.
[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 die CmCallbackReleaseKeyObjectIDEx Routine aufgerufen wird. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen finden Sie in den Hinweisen.
[in] Flags
Reserviert. Auf Null festgelegt.
Rückgabewert
CmCallbackGetKeyObjectIDEx gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Mögliche Fehlerrücklaufwerte sind der folgende Statuscode:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INVALID_PARAMETER | Der Cookie, Objectoder Flags Parameter ist ungültig. |
Bemerkungen
Treiber können CmCallbackGetKeyObjectIDEx- verwenden, um den Registrierungsschlüsselbezeichner, den Objektnamen oder beide abzurufen, indem nicht-NULL- Werte für die parameter ObjectID oder ObjectName angegeben werden.
Der Aufrufer kann den Schlüsselbezeichner über den parameter ObjectID abrufen. Wenn zwei Registrierungsschlüsselobjekte denselben Registrierungsschlüssel darstellen, sind die schlüsselbezeichner, die von CmCallbackGetKeyObjectIDEx für die beiden Objekte abgerufen werden, identisch. Wenn sich der Name des Registrierungsschlüssels ändert, ändert sich der schlüsselbezeichner, der von CmCallbackGetKeyObjectIDEx abgerufen wurde. Der Aufrufer kann den Schlüsselbezeichner verwenden, um Zugriffe, die an einem bestimmten Registrierungsschlüssel vorgenommen werden, über mehrere Schlüsselobjekte zuverlässig nachzuverfolgen, und sogar über Änderungen am Namen des Registrierungsschlüssels hinweg.
Der Aufrufer kann den Objektnamen über den parameter ObjectName 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 CmCallbackGetKeyObjectIDExaufrufen. Treiber, die nur in Windows 8 und höheren Versionen von Windows ausgeführt werden, sollten CmCallbackGetKeyObjectIDEx- anstelle von CmCallbackGetKeyObjectIDaufrufen.
CmCallbackGetKeyObjectIDEx verfügt über zwei wichtige Features, die von CmCallbackGetKeyObjectIDnicht verfügbar sind.
Zunächst ermöglicht CmCallbackGetKeyObjectIDEx- einem Registrierungsfiltertreiber die explizite Steuerung der Lebensdauer der ObjectName--Struktur. Der Treiber kann jederzeit CmCallbackReleaseKeyObjectIDEx- aufrufen, um diese Struktur frei zu geben. Im Gegensatz dazu kann der Treiber die ObjectName- Struktur, die von CmCallbackGetKeyObjectIDempfangen wurde, nicht explizit freigeben. Diese Struktur wird automatisch freigegeben, wenn alle Ziehpunkte für den Schlüssel geschlossen werden.
Zweitens: Wenn ein Registrierungsfiltertreiber CmCallbackGetKeyObjectID aufruft, um einen ObjectName Strukturzeiger abzurufen, und nach diesem Aufruf ändert sich der Name des Registrierungsschlüssels, werden nachfolgende Aufrufe von CmCallbackGetKeyObjectID einen Zeiger auf eine veraltete Kopie der ObjectName Struktur abrufen, 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 ObjectName- Struktur, die von CmCallbackGetKeyObjectIDEx abgerufen wird, immer den up-to-date-Schlüsselnamen.
Weitere Informationen zu Registrierungsfiltertreibern finden Sie unter Filtern von Registrierungsaufrufen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 8. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | IRQL-<= APC_LEVEL |