Funzione ObReferenceObjectByPointerWithTag (wdm.h)

Articolo
03/18/2023

La routine ObReferenceObjectByPointerWithTag incrementa il conteggio dei riferimenti dell'oggetto specificato e scrive un valore di tag a quattro byte nell'oggetto per supportare la traccia di riferimento agli oggetti.

Sintassi

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           Tag
);

Parametri

[in] Object

Puntatore all'oggetto. Il chiamante ottiene questo puntatore quando crea l'oggetto o da una chiamata precedente alla routine ObReferenceObjectByHandleWithTag dopo aver aperto l'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. Questo parametro può essere NULL se AccessMode è KernelMode. 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

Indica la modalità di accesso da usare per il controllo di accesso. Impostare questo parametro su uno dei valori di enumerazione MODE seguenti:

Usermode
KernelMode

I driver di livello inferiore devono specificare KernelMode.

[in] Tag

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

Valore restituito

ObReferenceObjectByPointerWithTag 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 a cui punta il parametro Object o ObjectType è NULL, ma AccessMode è UserMode.

Commenti

Questa routine accede alla convalida dell'oggetto specificato. Se è possibile concedere l'accesso, la routine incrementa il conteggio dei riferimenti all'oggetto. 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.

La routine ObReferenceObjectByPointer è simile a ObReferenceObjectByPointerWithTag, tranne che non consente al chiamante di scrivere un tag personalizzato in un oggetto. In Windows 7 e versioni successive di Windows , ObReferenceObjectByPointer scrive sempre un valore di tag predefinito ('tlfD') nell'oggetto. Una chiamata a ObReferenceObjectByPointer ha lo stesso effetto di una chiamata a ObReferenceObjectByPointerWithTag 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 . In Windows 7 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	<= DISPATCH_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDDIs(storport)