Funzione ObReferenceObjectByPointerWithTag (wdm.h)
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) |