Funzione WdfObjectReferenceActual (wdfobject.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfObjectReferenceActual incrementa il conteggio dei riferimenti per un oggetto framework specificato e assegna un valore di tag, un numero di riga e un nome di file al riferimento.

Sintassi

void WdfObjectReferenceActual(
  [in]           WDFOBJECT Handle,
  [in, optional] PVOID     Tag,
  [in]           LONG      Line,
  [in]           PCCH      File
);

Parametri

[in] Handle

Handle per un oggetto framework.

[in, optional] Tag

Valore definito dal driver archiviato dal framework come tag di identificazione per il riferimento all'oggetto.

[in] Line

Valore numerico che rappresenta un numero di riga in un file di origine del driver.

[in] File

Puntatore a una stringa di caratteri costante con terminazione Null che rappresenta il nome di un file di origine del driver. Questo parametro è facoltativo e può essere NULL.

Valore restituito

nessuno

Osservazioni

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Se il driver chiama WdfObjectReferenceActual per incrementare un conteggio dei riferimenti, il driver deve chiamare WdfObjectDereferenceActual per decrementare il conteggio.

La chiamata a WdfObjectReferenceActual o WdfObjectReferenceWithTag anziché WdfObjectReference fornisce informazioni aggiuntive (valore tag, numero di riga e nome file) ai debugger Microsoft. WdfObjectReferenceActual consente al driver di specificare il numero di riga e il nome del file, mentre WdfObjectReferenceWithTag usa il numero di riga e il nome file correnti del driver.

È possibile visualizzare i valori di tag, numero di riga e nome file usando l'estensione del debugger !wdftagtracker . L'estensione del debugger visualizza il valore del tag sia come puntatore che come serie di caratteri. Per altre informazioni sulle estensioni del debugger, vedere Debug di un driver KMDF.

Per altre informazioni sui conteggi dei riferimenti agli oggetti, vedere Ciclo di vita degli oggetti framework.

Per altre informazioni sulle regole di pulizia per una gerarchia di oggetti framework, vedere Framework Object Life Cycle.

Esempio

Nell'esempio di codice seguente il conteggio dei riferimenti di un oggetto viene incrementato e viene assegnato un valore, un numero di riga e un nome di file al riferimento.

WdfObjectReferenceActual(
                         object,
                         pTag,
                         line,
                         FILE_NAME
                         );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfobject.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf)

Vedi anche

WdfObjectReference

Condividi tramite