Funzione ObReferenceObjectByHandle (wdm.h)

Articolo
02/29/2024

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)

Vedi anche

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer

Condividi tramite