Macro ObDereferenceObjectWithTag (wdm.h)

Articolo
02/27/2024

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

Sintassi

void ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

Parametri

[in] a

Puntatore all'oggetto . Il chiamante ottiene questo puntatore quando crea l'oggetto o da una chiamata precedente alla routine ObReferenceObjectByHandleWithTag dopo l'apertura dell'oggetto.

[in] t

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

Valore restituito

nessuno

Osservazioni

ObDereferenceObjectWithTag restituisce un valore riservato per l'uso del sistema. I driver devono considerare questo valore come VOID.

Un driver in modalità kernel chiama questa routine per decrementare il numero di riferimenti di un oggetto di uno. Se l'oggetto è stato creato come temporaneo ( ovvero, il flag di OBJ_PERMANENT non è stato specificato al momento della creazione dell'oggetto) e il conteggio dei riferimenti raggiunge lo zero, il gestore oggetti elimina l'oggetto.

Quando il conteggio dei riferimenti per un oggetto raggiunge zero, un componente in modalità kernel può eliminare l'oggetto. Tuttavia, un driver può eliminare solo gli oggetti creati e un driver non deve mai tentare di eliminare alcun oggetto che non ha creato.

Un oggetto è permanente se è stato creato con il flag di attributo dell'oggetto OBJ_PERMANENT specificato. Per altre informazioni sugli attributi dell'oggetto, vedere InitializeObjectAttributes. Un oggetto permanente viene creato con un conteggio dei riferimenti iniziale di uno, quindi l'oggetto non viene eliminato quando il driver rimuove l'ultimo riferimento all'oggetto.

Per preparare un oggetto permanente da eliminare, un driver può chiamare la routine ZwMakeTemporaryObject per rendere temporaneo l'oggetto. Un driver deve eliminare solo un oggetto permanente creato. Per eliminare un oggetto permanente, seguire questa procedura:

Chiamare ObDereferenceObjectWithTag.
Ottiene l'handle per l'oggetto . Se necessario, chiamare la routine ZwOpenXxx o ZwCreateXxx appropriata per ottenere l'handle dell'oggetto.
Chiamare ZwMakeTemporaryObject con l'handle ottenuto nel passaggio 2.
Chiamare ZwClose con l'handle ottenuto nel passaggio 2.

Se l'eliminazione immediata di un oggetto da parte del thread corrente potrebbe causare un deadlock, non chiamare ObDereferenceObjectWithTag per dereferenziare l'oggetto. Chiamare invece la routine ObDereferenceObjectDeferDeleteWithTag per dereferenziare l'oggetto.

Ad esempio, un deadlock di questo tipo può verificarsi se ObDereferenceObjectWithTag viene usato per dereferenziare un oggetto Kernel Transaction Manager (KTM) quando un driver di livello superiore nello stack di driver mantiene un blocco.

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

La routine ObDereferenceObject è simile a ObDereferenceObjectWithTag, 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 ObDereferenceObject scrive sempre un valore di tag predefinito ('tlfD') nell'oggetto . Una chiamata a ObDereferenceObject ha lo stesso effetto di una chiamata a ObDereferenceObjectWithTag che specifica Tag = 'tlfD'.

Per visualizzare una traccia di riferimento a oggetti negli strumenti di debug di Windows, usare l'estensione del debugger !obtrace in modalità kernel. 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 è disattivata. Utilizzare l'Editor flag globali (Gflags) per abilitare la traccia dei riferimenti agli oggetti. Per altre informazioni, vedere Traccia di riferimento a oggetti con tag.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Desktop
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	HwStorPortProhibitedDDIs(storport)