Funzione CmCallbackGetKeyObjectIDEx (wdm.h)

Articolo
03/08/2023

La routine CmCallbackGetKeyObjectIDEx recupera l'identificatore univoco e il nome dell'oggetto associati a un oggetto chiave del Registro di sistema specificato.

Questa routine è disponibile a partire da Windows 8. Nelle versioni precedenti di Windows usare invece la routine CmCallbackGetKeyObjectID . Per altre informazioni, vedere la sezione Osservazioni di seguito.

Sintassi

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

Parametri

[in] Cookie

Valore del cookie che rappresenta la registrazione del chiamante per ricevere i callback del filtro del Registro di sistema. Il driver ha ottenuto in precedenza questo valore del cookie dalla routine CmRegisterCallback o CmRegisterCallbackEx .

[in] Object

Puntatore all'oggetto chiave del Registro di sistema. Questo parametro è il valore del puntatore ricevuto dalla routine di callback RegistryCallback del driver nel membro Object di una delle strutture REG_XXX_KEY_INFORMATION .

Avviso

In determinate circostanze le strutture di notifica di callback del Registro di sistema possono contenere puntatori a oggetti non NULL non validi. I driver di filtro del Registro di sistema non devono passare tali puntatori a questa routine. Per altre informazioni, vedere Puntatori a oggetti chiave non validi nelle notifiche del Registro di sistema.

[out, optional] ObjectID

Puntatore a una posizione che riceve un puntatore all'identificatore di chiave per la chiave del Registro di sistema rappresentata da Object . Questo identificatore è univoco in tutte le chiavi del Registro di sistema. Questo parametro è facoltativo e può essere NULL. Per altre informazioni, vedere la sezione Osservazioni di seguito.

[out, optional] ObjectName

Puntatore a una posizione che riceve un puntatore a una struttura UNICODE_STRING . Questa struttura contiene il nome dell'oggetto chiave del Registro di sistema specificato da Object . Il nome dell'oggetto è in realtà il nome completo della chiave del Registro di sistema rappresentata dall'oggetto. Il chiamante è responsabile della liberazione di questa struttura chiamando la routine CmCallbackReleaseKeyObjectIDEx . Questo parametro è facoltativo e può essere NULL. Per altre informazioni, vedere la sezione Osservazioni.

[in] Flags

Riservato. Imposta su zero.

Valore restituito

CmCallbackGetKeyObjectIDEx restituisce STATUS_SUCCESS se l'operazione ha esito positivo. I valori restituiti di errore possibili includono il codice di stato seguente:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il parametro Cookie, Object o Flags non è valido.

Commenti

I driver possono usare CmCallbackGetKeyObjectIDEx per ottenere l'identificatore della chiave del Registro di sistema, il nome dell'oggetto o entrambi, fornendo valori non NULL per i parametri ObjectID o ObjectName .

Il chiamante può ottenere l'identificatore di chiave tramite il parametro ObjectID . Se due oggetti chiave del Registro di sistema rappresentano la stessa chiave del Registro di sistema, gli identificatori di chiave ottenuti da CmCallbackGetKeyObjectIDEx per i due oggetti sono identici. Se il nome della chiave del Registro di sistema viene modificato, l'identificatore della chiave ottenuto da CmCallbackGetKeyObjectIDEx non cambia. Il chiamante può usare l'identificatore di chiave per tenere traccia in modo affidabile degli accessi effettuati a una determinata chiave del Registro di sistema tramite più oggetti chiave e anche tra le modifiche apportate al nome della chiave del Registro di sistema.

Il chiamante può ottenere il nome dell'oggetto tramite il parametro ObjectName . Lo spazio di archiviazione per la struttura UNICODE_STRING che contiene il nome dell'oggetto rimane valido fino a quando il chiamante chiama CmCallbackReleaseKeyObjectIDEx per liberare la struttura.

CmCallbackGetKeyObjectIDEx è una versione migliorata della routine CmCallbackGetKeyObjectID , disponibile a partire da Windows Vista. I driver eseguiti nelle versioni di Windows precedenti a Windows 8 devono chiamare CmCallbackGetKeyObjectID anziché CmCallbackGetKeyObjectIDEx. I driver eseguiti solo in Windows 8 e versioni successive di Windows devono chiamare CmCallbackGetKeyObjectIDEx anziché CmCallbackGetKeyObjectID.

CmCallbackGetKeyObjectIDEx dispone di due importanti funzionalità non disponibili da CmCallbackGetKeyObjectID.

In primo luogo, CmCallbackGetKeyObjectIDEx consente a un driver di filtro del Registro di sistema di controllare in modo esplicito la durata della struttura ObjectName . Il driver può chiamare CmCallbackReleaseKeyObjectIDEx in qualsiasi momento per liberare questa struttura. Al contrario, il driver non può liberare in modo esplicito la struttura ObjectName ricevuta da CmCallbackGetKeyObjectID. Questa struttura viene rilasciata automaticamente quando tutti gli handle della chiave vengono chiusi.

In secondo luogo, se un driver di filtro del Registro di sistema chiama CmCallbackGetKeyObjectID per ottenere un puntatore alla struttura ObjectName e, dopo questa chiamata, il nome della chiave del Registro di sistema cambia, le chiamate successive a CmCallbackGetKeyObjectID ottengono un puntatore a una copia non aggiornata della struttura ObjectName , che contiene il nome della chiave precedente. La copia non aggiornata di questa struttura viene mantenuta finché tutti gli handle della chiave non vengono chiusi. Al contrario, la struttura ObjectName ottenuta da CmCallbackGetKeyObjectIDEx contiene sempre il nome di chiave più aggiornato.

Per altre informazioni sui driver di filtro del Registro di sistema, vedere Filtro delle chiamate al Registro di sistema.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile a partire da Windows 8.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL