Funzione WdfIoTargetWdmGetTargetFileHandle (wdfiotarget.h)

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetWdmGetTargetFileHandle restituisce un handle al file associato a una destinazione di I/O remota specificata.

Sintassi

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Parametri

[in] IoTarget

Handle a un oggetto di destinazione di I/O remoto. Questo handle è stato ottenuto da una chiamata precedente a WdfIoTargetCreate.

Valore restituito

Se il driver ha specificato un nome di oggetto quando viene chiamato WdfIoTargetOpen, WdfIoTargetWdmGetTargetFileHandle restituisce l'handle di file associato alla destinazione I/O specificata. In caso contrario , WdfIoTargetWdmGetGetTargetFileHandle restituisceNULL.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Per KMDF, l'handle di file restituito è un handle in modalità kernel valido in un contesto di thread arbitrario. Per informazioni su come un driver può usare questo handle di file, vedere Uso di un handle file.

L'handle di file restituito dal metodo WdfIoTargetWdmGetTargetFileHandle è valido fino a quando il driver chiama WdfIoTargetClose o WdfIoTargetCloseForQueryRemove o fino all'eliminazione dell'oggetto di destinazione I/O remoto. Se il driver fornisce una funzione EvtCleanupCallback per l'oggetto di destinazione di I/O remoto e se l'oggetto viene eliminato prima della chiusura della destinazione di I/O remota, il puntatore è valido fino a quando non viene restituita la funzione EvtCleanupCallback .

Se il driver tenta di accedere all'oggetto dispositivo WDM dopo che è stato rimosso, il driver può causare l'arresto anomalo del sistema. L'esempio di avviso popup illustra come il driver può fornire una funzione di callback EvtIoTargetQueryRemove in modo che venga notificata se la destinazione di I/O viene rimossa.

Per UMDF, WdfIoTargetWdmGetGetTargetFileHandle restituisce un handle Win32 valido solo nel processo corrente. Driver UMDF legacy (versione 1).x) chiama IWDFDevice::RetrieveDeviceName per ottenere il nome del dispositivo in modalità kernel sottostante e quindi apre un handle con CreateFile. Il driver può quindi inviare I/O direttamente ai dispositivi inferiori usando DeviceIoControl. A partire da UMDF 2.15, i driver UMDF v2 possono aprire la destinazione di I/O locale per file (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) e recuperare l'handle file usando WdfIoTargetWdmGetTargetFileHandle. Il framework apre e chiude l'handle di file quando la destinazione remota viene chiusa o eliminata. L'handle di file rimane valido all'interno del contratto WdfIoTargetWdmGetTargetFileHandle descritto in precedenza.

Avviso

Se un driver UMDF v2 chiama WdfIoTargetWdmGetTargetFileHandle per ottenere l'handle Win32 aperto tramite WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE, non inviare operazioni di I/O sovrapposte o asincrone con API come DeviceIoControl. In questo modo, è possibile arrestare il processo che ospita il driver. Se il driver deve inviare l'I/O sovrapposto, deve anche impostare il bit a basso ordine del membro hEvent della struttura OVERLAPPED . Questo perché il framework associa internamente l'handle a una porta di completamento di I/O. Un handle di eventi valido il cui bit a basso ordine è impostato mantiene in coda il completamento di I/O alla porta di completamento.

Per altre informazioni su WdfIoTargetWdmGetTargetFileHandle, vedere Ottenere informazioni su una destinazione di I/O generale.

Per altre informazioni sulle destinazioni di I/O, vedere Uso delle destinazioni di I/O.

Esempio

Nell'esempio di codice seguente viene ottenuto un handle per il file associato a una destinazione di I/O remota specificata.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Driver UMDF legacy (versione 1).x) chiama IWDFDevice::RetrieveDeviceName per ottenere il nome del dispositivo in modalità kernel sottostante e quindi aprire un handle con CreateFile. Il driver invia quindi I/O direttamente al dispositivo usando DeviceIoControl.

A partire da UMDF 2.15, il driver apre la destinazione di I/O locale per file e recupera il relativo handle. Il framework apre e chiude l'handle di file. L'handle di file rimane valido all'interno del contratto di WdfIoTargetWdmGetTargetFileHandle.

NTSTATUS status;

WDF_IO_TARGET_OPEN_PARAMS params;

WDFIOTARGET ioTarget = NULL;

HANDLE handle = NULL;

status = WdfIoTargetCreate(Device, &attr, &ioTarget);

if (!NT_SUCCESS(status)) {

    // error handling

}

WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE(&params, NULL);

status = WdfIoTargetOpen(ioTarget, &params);

if (!NT_SUCCESS(status)) {

    // error handling

}

handle = WdfIoTargetWdmGetTargetFileHandle(ioTarget);

if (handle == NULL) {

    // error handling

}

if (ioTarget != NULL) {
    WdfIoTargetClose(ioTarget);
}
// You can now call DeviceIoControl(handle, ...) etc.
// NOTE: See Warning above on submitting overlapped or asynchronous I/O

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1,0
Versione UMDF minima	2.15
Intestazione	wdfiotarget.h (include Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject