CmCallbackGetKeyObjectID-Funktion (wdm.h)

Artikel
02/29/2024

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

Ab Windows 8 sollten Registrierungsfiltertreiber die CmCallbackGetKeyObjectIDEx-Routine anstelle von CmCallbackGetKeyObjectID aufrufen. Weitere Informationen finden Sie weiter unten im Abschnitt Hinweise .

Syntax

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

Parameter

[in] Cookie

Der Cookiewert, den der Treiber zuvor durch Aufrufen der CmRegisterCallback - oder CmRegisterCallbackEx-Routine abgerufen hat.

[in] Object

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 eindeutigen Bezeichner empfängt, der den Registrierungsschlüssel darstellt, den Object angibt. Dieser Parameter ist optional und kann NULL sein.

[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 darf nicht in diese UNICODE_STRING-Struktur schreiben oder freigeben. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

CmCallbackGetKeyObjectID 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- oder Object-Parameter ist ungültig.

Hinweise

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

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

Nachdem der Treiber den Bezeichner oder Namen abgerufen hat, ist der Bezeichner oder Name gültig, bis die RegistryCallback-Routine des Treibers eine Vorabbenachrichtigung über das Schließen des Handle empfängt.

Der Treiber darf den Objektnamen nicht ändern.

Wenn zwei Registrierungsschlüsselobjekte denselben Registrierungsschlüssel darstellen, sind die Schlüsselbezeichner für beide Objekte identisch.

Weitere Informationen zu CmCallbackGetKeyObjectID und Registrierungsfiltervorgängen finden Sie unter Filtern von Registrierungsaufrufen.