Funzione ObReferenceObjectByHandle (wdm.h)
La routine ObReferenceObjectByHandle fornisce la convalida dell'accesso sull'handle dell'oggetto e, se è possibile concedere l'accesso, restituisce il puntatore corrispondente al corpo dell'oggetto.
Sintassi
NTSTATUS ObReferenceObjectByHandle(
[in] HANDLE Handle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_TYPE ObjectType,
[in] KPROCESSOR_MODE AccessMode,
[out] PVOID *Object,
[out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);
Parametri
[in] Handle
Specifica un handle aperto per un oggetto .
[in] DesiredAccess
Specifica i tipi richiesti di accesso all'oggetto . L'interpretazione di questo campo dipende dal tipo di oggetto. Non usare diritti di accesso generici. Per altre informazioni, vedere ACCESS_MASK.
[in, optional] ObjectType
Puntatore al tipo di oggetto. ObjectType può essere *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType o *TmTransactionObjectType.
Se ObjectType non è NULL, il sistema operativo verifica che il tipo di oggetto fornito corrisponda al tipo di oggetto dell'oggetto specificato da Handle .
[in] AccessMode
Specifica la modalità di accesso da utilizzare per il controllo di accesso. Deve essere UserMode o KernelMode. I driver devono sempre specificare UserMode per gli handle ricevuti dallo spazio indirizzi utente.
[out] Object
Puntatore a una variabile che riceve un puntatore al corpo dell'oggetto. La tabella seguente contiene i tipi di puntatore.
| Parametro ObjectType | Tipo di puntatore a oggetti |
|---|---|
| *ExEventObjectType | PKEVENT |
| *ExSemaphoreObjectType | PKSEMAPHORE |
| *IoFileObjectType | PFILE_OBJECT |
| *PsProcessType | PEPROCESS o PKPROCESS |
| *PsThreadType | PETHREAD o PKTHREAD |
| *SeTokenObjectType | PACCESS_TOKEN |
| *TmEnlistmentObjectType | PKENLISTMENT |
| *TmResourceManagerObjectType | PKRESOURCEMANAGER |
| *TmTransactionManagerObjectType | PKTM |
| *TmTransactionObjectType | PKTRANSACTION |
Le strutture a cui fanno riferimento i tipi di puntatore sono opache e i driver non possono accedere ai membri della struttura. Poiché le strutture sono opache, PEPROCESS equivale a PKPROCESS e PETHREAD equivale a PKTHREAD.
[out, optional] HandleInformation
I driver impostano questa proprietà su NULL.
Valore restituito
ObReferenceObjectByHandle restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti possibili includono i codici di errore seguenti:
| Codice restituito | Descrizione |
|---|---|
| STATUS_OBJECT_TYPE_MISMATCH | Il parametro ObjectType specifica il tipo di oggetto errato per l'oggetto identificato dal parametro Handle . |
| STATUS_ACCESS_DENIED | Al chiamante non è possibile concedere i diritti di accesso richiesti all'oggetto . |
| STATUS_INVALID_HANDLE | Il parametro Handle non è un handle di oggetto valido. |
Commenti
Un puntatore al corpo dell'oggetto viene recuperato dalla voce della tabella dell'oggetto e restituito al chiamante tramite il parametro Object .
Se AccessMode è UserMode, l'accesso richiesto viene confrontato con l'accesso concesso per l'oggetto. Se AccessMode è KernelMode, l'handle deve avere origine nello spazio indirizzi del kernel.
A partire da Windows 7, se AccessMode è KernelMode e l'handle viene ricevuto dallo spazio degli indirizzi utente, Driver Verifier genera bugcheck C4, subcode F6.
Se la chiamata ha esito positivo, viene restituito un puntatore al corpo dell'oggetto al chiamante e il conteggio dei riferimenti del puntatore viene incrementato. L'incremento di questo conteggio impedisce l'eliminazione dell'oggetto mentre viene fatto riferimento al puntatore. Il chiamante deve decrementare il conteggio dei riferimenti con ObDereferenceObject non appena viene eseguito con l'oggetto .
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Disponibile a partire da Windows 2000. |
| Piattaforma di destinazione | Universale |
| Intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Libreria | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Regole di conformità DDI | HwStorPortProhibitedDDIs(storport), IrqlObPassive(wdm), TargetRelationNeedsRef(wdm) |