WdfIoTargetWdmGetTargetFileHandle-Funktion (wdfiotarget.h)

[Gilt für KMDF und UMDF]

Die WdfIoTargetWdmGetTargetFileHandle-Methode gibt ein Handle an die Datei zurück, die einem angegebenen Remote-E/A-Ziel zugeordnet ist.

Syntax

HANDLE WdfIoTargetWdmGetTargetFileHandle(
  [in] WDFIOTARGET IoTarget
);

Parameter

[in] IoTarget

Ein Handle für ein Remote-E/A-Zielobjekt. Dieses Handle wurde aus einem vorherigen Aufruf von WdfIoTargetCreate abgerufen.

Rückgabewert

Wenn der Treiber beim Aufrufen von WdfIoTargetOpen einen Objektnamen angegeben hat, gibt WdfIoTargetWdmGetTargetFileHandle das Dateihandle zurück, das dem angegebenen E/A-Ziel zugeordnet ist. Andernfalls gibt WdfIoTargetWdmGetTargetFileHandleNULL zurück.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Für KMDF ist das zurückgegebene Dateihandle ein Kernelmodushandle, das in einem beliebigen Threadkontext gültig ist. Informationen dazu, wie ein Treiber dieses Dateihandle verwenden kann, finden Sie unter Verwenden eines Dateihandles.

Das Dateihandle, das von der WdfIoTargetWdmGetTargetFileHandle-Methode zurückgegeben wird, ist gültig, bis der Treiber WdfIoTargetClose oder WdfIoTargetCloseForQueryRemove aufruft oder bis das Remote-E/A-Zielobjekt gelöscht wird. Wenn der Treiber eine EvtCleanupCallback-Funktion für das Remote-E/A-Zielobjekt bereitstellt und das Objekt gelöscht wird, bevor das E/A-Remoteziel geschlossen wird, ist der Zeiger gültig, bis die EvtCleanupCallback-Funktion zurückgegeben wird.

Wenn der Treiber versucht, auf das WDM-Geräteobjekt zuzugreifen, nachdem es entfernt wurde, kann der Treiber dazu führen, dass das System abstürzt. Das Toastmonbeispiel veranschaulicht, wie der Treiber eine EvtIoTargetQueryRemove-Rückruffunktion bereitstellen kann, sodass sie benachrichtigt wird, wenn das E/A-Ziel entfernt wird.

Für UMDF gibt WdfIoTargetWdmGetTargetFileHandle ein Win32-HANDLE zurück, das nur im aktuellen Prozess gültig ist. Ein älteren UMDF-Treiber (Version 1.x) ruft IWDFDevice::RetrieveDeviceName auf, um den Namen des zugrunde liegenden Kernelmodusgeräts abzurufen, und öffnet dann mit CreateFile ein Handle dafür. Der Treiber kann dann mithilfe von DeviceIoControl E/A direkt an die unteren Geräte senden. Ab UMDF 2.15 können UMDF v2-Treiber das lokale E/A-Ziel nach Datei (WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE) öffnen und das Dateihandle mithilfe von WdfIoTargetWdmGetTargetFileHandle abrufen. Das Framework öffnet und schließt das Dateihandle, wenn das Remoteziel geschlossen oder gelöscht wird. Das Dateihandle bleibt innerhalb des oben beschriebenen Vertrags von WdfIoTargetWdmGetTargetFileHandle gültig.

Warnung

Wenn ein UMDF v2-Treiber WdfIoTargetWdmGetTargetFileHandle aufruft , um das Win32-Handle von einem Remoteziel abzurufen, das mit WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_FILE geöffnet wurde, übermitteln Sie keine überlappende/asynchrone E/A mit APIs wie DeviceIoControl. Dies kann den Prozess, der den Treiber hosten, abstürzen. Wenn der Treiber überlappende E/A-Vorgänge übermitteln muss, muss er auch das Bit mit niedriger Reihenfolge des hEvent-Elements der OVERLAPPED-Struktur festlegen. Dies liegt daran, dass das Framework das Handle intern an einen E/A-Abschlussport bindet. Ein gültiges Ereignishandle, dessen Bit in niedriger Reihenfolge festgelegt ist, verhindert, dass der E/A-Abschluss bis zum Abschlussport in die Warteschlange eingereiht wird.

Weitere Informationen zu WdfIoTargetWdmGetTargetFileHandle finden Sie unter Abrufen von Informationen zu einem allgemeinen E/A-Ziel.

Weitere Informationen zu E/A-Zielen finden Sie unter Verwenden von E/A-Zielen.

Beispiele

Im folgenden Codebeispiel wird ein Handle für die Datei abgerufen, die einem angegebenen Remote-E/A-Ziel zugeordnet ist.

HANDLE h;

h = WdfIoTargetWdmGetTargetFileHandle(IoTarget);

Ein älteren UMDF-Treiber (Version 1.x) ruft IWDFDevice::RetrieveDeviceName auf, um den Namen des zugrunde liegenden Kernelmodusgeräts abzurufen und dann mit CreateFile ein Handle dafür zu öffnen. Der Treiber sendet dann mithilfe von DeviceIoControl E/A direkt an das Gerät.

Ab UMDF 2.15 öffnet der Treiber das lokale E/A-Ziel nach Datei und ruft dessen Handle ab. Das Framework öffnet und schließt das Dateihandle. Das Dateihandle bleibt innerhalb des Vertrags von WdfIoTargetWdmGetTargetFileHandle gültig.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.15
Kopfzeile	wdfiotarget.h (include Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WdfIoTargetCreate

WdfIoTargetWdmGetTargetFileObject