Funzione ObReferenceObjectByHandleWithTag (wdm.h)

Articolo
08/08/2023

La routine ObReferenceObjectByHandleWithTag incrementa il conteggio dei riferimenti dell'oggetto identificato dall'handle specificato e scrive un valore tag a quattro byte nell'oggetto per supportare la traccia dei riferimenti a oggetti.

Sintassi

NTSTATUS ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

Parametri

[in] Handle

Specifica un handle aperto per un oggetto.

[in] DesiredAccess

Specifica i tipi di accesso all'oggetto richiesto dal chiamante. Questo parametro è una maschera di bit di tipo ACCESS_MASK. L'interpretazione di questo campo dipende dal tipo di oggetto. Non usare diritti di accesso generici.

[in, optional] ObjectType

Puntatore a una struttura opaca che specifica il tipo di oggetto. Questo parametro punta a una struttura OBJECT_TYPE . Impostare ObjectType su NULL o su uno dei valori del puntatore seguenti, dichiarati nel file di intestazione Wdm.h: *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType o *TmTransactionObjectType. Se ObjectType non è NULL, la routine verifica che il tipo di oggetto fornito corrisponda al tipo di oggetto dell'oggetto specificato dal parametro Handle .

[in] AccessMode

Specifica la modalità di accesso da usare per il controllo di accesso. Deve essere UserMode o KernelMode. I driver devono sempre specificare UserMode per gli handle ricevuti dallo spazio indirizzi utente.

[in] Tag

Specifica un valore di tag personalizzato a quattro byte. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[out] Object

Puntatore a una variabile in cui la routine scrive un puntatore all'oggetto. Nella tabella seguente sono elencati i tipi di puntatore Object designati dai possibili valori dei parametri ObjectType .

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 opachi 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 questo parametro su NULL.

Valore restituito

ObReferenceObjectByHandleWithTag restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti degli errori possibili includono quanto segue:

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	Il chiamante non dispone dei diritti di accesso necessari all'oggetto.
STATUS_INVALID_HANDLE	L'handle specificato non è valido.

Commenti

Questa routine esegue l'accesso alla convalida dell'handle oggetto specificato. Se è possibile concedere l'accesso, la routine incrementa il conteggio dei riferimenti dell'oggetto e fornisce un puntatore a oggetti al chiamante. Questo incremento impedisce l'eliminazione dell'oggetto mentre il chiamante usa l'oggetto. Quando l'oggetto non è più necessario, il chiamante deve decrerere il conteggio dei riferimenti chiamando la routine ObDereferenceObjectWithTag o ObDereferenceObjectDeferDeleteWithTag.

Per altre informazioni sui riferimenti agli oggetti, vedere Ciclo di vita di un oggetto.

ObReferenceObjectByHandleWithTag non chiude o invalida l'handle dell'oggetto specificato dal parametro Handle . Quando l'handle non è più necessario, il chiamante può chiudere l'handle chiamando la routine ZwClose .

Se il valore del parametro AccessMode è KernelMode, l'accesso richiesto è sempre consentito. Se AccessMode è UserMode, l'accesso richiesto viene confrontato con i diritti di accesso necessari al chiamante. Solo i driver di livello più alto possono specificare in modo sicuro il valore UserMode per il parametro AccessMode .

A partire da Windows 7, se AccessMode è KernelMode e handle viene ricevuto dallo spazio degli indirizzi utente, Driver Verifier genera bugcheck C4, sottocodice F6.

La routine ObReferenceObjectByHandle è simile a ObReferenceObjectByHandleWithTag, ad eccezione del fatto che non consente al chiamante di scrivere un tag personalizzato in un oggetto. In Windows 7 e versioni successive di Windows , ObReferenceObjectByHandle scrive sempre un valore di tag predefinito ('tlfD') nell'oggetto. Una chiamata a ObReferenceObjectByHandle ha lo stesso effetto di una chiamata a ObReferenceObjectByHandleWithTag che specifica Tag = 'tlfD'.

Per visualizzare una traccia di riferimento a oggetti negli strumenti di debug di Windows, usare l'estensione del debugger in modalità kernel !obtrace . L'estensione !obtrace è migliorata per visualizzare i tag di riferimento agli oggetti, se è abilitata la traccia dei riferimenti a oggetti. Per impostazione predefinita, la traccia dei riferimenti a oggetti viene disattivata. Usare l'editor di flag globali (Gflags) per abilitare la traccia dei riferimenti a oggetti. Per altre informazioni, vedere Traccia dei riferimenti a oggetti con tag.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport)