WdfIoTargetOpen-Funktion (wdfiotarget.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfIoTargetOpen-Methode öffnet ein Remote-E/A-Ziel, damit der Treiber E/A-Anforderungen an ihn senden kann.

Syntax

NTSTATUS WdfIoTargetOpen(
  [in] WDFIOTARGET                IoTarget,
  [in] PWDF_IO_TARGET_OPEN_PARAMS OpenParams
);

Parameter

[in] IoTarget

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

[in] OpenParams

Ein Zeiger auf eine aufruferseitig zugeordnete WDF_IO_TARGET_OPEN_PARAMS-Struktur .

Rückgabewert

WdfIoTargetOpen gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_STATE	Das angegebene E/A-Ziel ist bereits geöffnet.
STATUS_INSUFFICIENT_RESOURCES	Die verfügbaren Systemressourcen reichten nicht aus, um den Vorgang abzuschließen.
STATUS_INFO_LENGTH_MISMATCH	Die Größe der von OpenParams angegebenen WDF_IO_TARGET_OPEN_PARAMS-Struktur war falsch.
STATUS_NO_SUCH_DEVICE	Das TargetFileObject-Element der WDF_IO_TARGET_OPEN_PARAMS-Struktur des Aufrufers hat ein ungültiges Dateiobjekt angegeben.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_NOT_FOUND	Der Gerätename, der im OpenParams-Parameter identifiziert wird, kann nicht gefunden werden.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

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

Hinweise

Treiber können Remote-E/A-Ziele öffnen, indem sie eine Unicode-Zeichenfolge angeben, die einen Objektnamen darstellt, oder indem sie einen Zeiger auf ein Windows-Treibermodell (WDM) DEVICE_OBJECT Struktur bereitstellen. (Frameworkbasierte Treiber verfügen in der Regel nicht über Zeiger auf die DEVICE_OBJECT Strukturen anderer Treiber.)

Um vor dem Aufruf von WdfIoTargetOpen einen Geräteschnittstellennamen zu erhalten, sollte ein UMDF-Treiber CM_Register_Notification aufrufen, um sich für die Benachrichtigung zum Eintreffen und Entfernen der Schnittstelle zu registrieren. Anschließend kann das Remoteziel mithilfe des symbolischen Schnittstellennamens geöffnet werden, den es in der Rückrufroutine für Schnittstellenbenachrichtigungen empfängt. Der Treiber sollte weiterhin auf die Entfernungsbenachrichtigung lauschen, während das Handle geöffnet ist. Wenn der Zieltreiber ausfällt, muss der UMDF-Treiber das Handle schließen.

Wenn die Schnittstelle bereits vorhanden ist, sollte ein UMDF-Treiber CM_Get_Device_Interface_List aufrufen und möglicherweise zuerst CM_Get_Device_Interface_List_Size aufrufen, um die erforderliche Puffergröße zu bestimmen.

Wenn Ihr Treiber sein lokales E/A-Ziel verwenden soll, muss der Treiber WdfDeviceGetIoTarget anstelle von WdfIoTargetOpen aufrufen.

Wenn ein Aufruf von WdfIoTargetOpen fehlschlägt, sollte der Treiber WdfObjectDelete aufrufen, um das E/A-Zielobjekt zu löschen.

Weitere Informationen zu WdfIoTargetOpen finden Sie unter Initialisieren eines allgemeinen E/A-Ziels.

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

Beispiele

Im folgenden Beispiel wird ein E/A-Zielobjekt erstellt, eine WDF_IO_TARGET_OPEN_PARAMS-Struktur initialisiert und ein Remote-E/A-Ziel geöffnet, indem der symbolische Linkname eines Geräts angegeben wird.

WDF_OBJECT_ATTRIBUTES  ioTargetAttrib;
WDFIOTARGET  ioTarget;
WDF_IO_TARGET_OPEN_PARAMS  openParams;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &ioTargetAttrib,
                                        TARGET_DEVICE_INFO
                                        );
status = WdfIoTargetCreate(
                           device,
                           &ioTargetAttrib,
                           &ioTarget
                           );
if (!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_TARGET_OPEN_PARAMS_INIT_OPEN_BY_NAME(
                                            &openParams,
                                            SymbolicLink,
                                            STANDARD_RIGHTS_ALL
                                            );
status = WdfIoTargetOpen(
                         ioTarget,
                         &openParams
                         );
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(ioTarget);
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfiotarget.h (include Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)