Macro ObReferenceObjectWithTag (wdm.h)

  • Articolo

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

Sintassi

void ObReferenceObjectWithTag(
  [in]  Object,
  [in]  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] Tag

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

Valore restituito

nessuno

Osservazioni

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

ObReferenceObjectWithTag incrementa semplicemente il conteggio dei riferimenti del puntatore per un oggetto, senza effettuare controlli di accesso sull'oggetto specificato. Al contrario, le routine ObReferenceObjectByHandleWithTag e ObReferenceObjectByPointerWithTag verificano che il chiamante disponga dei diritti di accesso necessari per l'oggetto e non abbia questi diritti se il chiamante non ha questi diritti.

Una chiamata ObReferenceObjectWithTag impedisce l'eliminazione dell'oggetto specificato almeno finché il driver chiama la routine ObDereferenceObjectWithTag o chiude l'oggetto. Dopo che l'oggetto non è più necessario, il driver deve chiamare ObDereferenceObjectWithTag per rimuovere il riferimento all'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 dovrebbe mai tentare di eliminare qualsiasi oggetto che non è stato creato.

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

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

Vedi anche

ObDereferenceObjectWithTag

ObReferenceObject

ObReferenceObjectByHandleWithTag

ObReferenceObjectByPointerWithTag