Funzione WdfObjectDereferenceActual (wdfobject.h)

Articolo
03/22/2025

[Si applica a KMDF e UMDF]

Il metodo WdfObjectDereferenceActual decrementa 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 WdfObjectDereferenceActual(
  [in]           WDFOBJECT Handle,
  [in, optional] PVOID     Tag,
  [in]           LONG      Line,
  [in, optional] PCCH      File
);

Parametri

[in] Handle

Handle per un oggetto framework.

[in, optional] Tag

Valore definito dal driver che identifica un riferimento a un oggetto. Il valore del tag deve corrispondere a un valore di tag fornito in precedenza dal driver a WdfObjectReferenceActual.

[in] Line

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

[in, optional] 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 conteggio dei riferimenti dell'oggetto diventa zero, l'oggetto potrebbe essere eliminato prima di restituisce WdfObjectDereferenceActual.

Chiamando WdfObjectDereferenceActual o WdfObjectDereferenceWithTag anziché WdfObjectDereference fornisce informazioni aggiuntive (stringa di tag, numero di riga e nome file) ai debugger Microsoft. WdfObjectDereferenceActual consente al driver di specificare il numero di riga e il nome del file, mentre WdfObjectDereferenceWithTag 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 debugger di !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 e sulle regole di pulizia per una gerarchia di oggetti framework, vedere Ciclo di vita degli oggetti framework.

Esempi

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

WdfObjectDereferenceActual(
                           object,
                           pTag,
                           line,
                           FILE_NAME
                           );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfobject.h (include Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
regole di conformità DDI	DriverCreate(kmdf)

Vedere anche

WdfObjectDereference

WdfObjectReferenceActual

Condividi tramite