WdfIoTargetOpen-Funktion (wdfiotarget.h)

[Gilt für KMDF und UMDF]

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

Syntax

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

Parameter

[in] IoTarget

Ein Handle zu einem I/O-Zielobjekt, das von einem vorherigen Aufruf von WdfIoTargetCreate abgerufen wurde.

[in] OpenParams

Ein Zeiger auf eine aufrufer-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 I/O-Ziel ist bereits geöffnet.
STATUS_INSUFFICIENT_RESOURCES
Verfügbare Systemressourcen waren nicht ausreichend, um den Vorgang abzuschließen.
STATUS_INFO_LENGTH_MISMATCH
Die Größe der WDF_IO_TARGET_OPEN_PARAMS Struktur, die OpenParams angegeben hat, 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.

Bemerkungen

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

Um einen Geräteschnittstellennamen vor dem Aufrufen von WdfIoTargetOpen abzurufen, sollte ein UMDF-Treiber CM_Register_Notification aufrufen, um sich für die Ankunft und Entfernung der Schnittstelle zu registrieren. Anschließend kann es das Remoteziel mithilfe des symbolischen Schnittstellennamens öffnen, den er in der Rückrufroutine für die Schnittstellenbenachrichtigung empfängt. Der Treiber sollte weiterhin auf die Entfernungsbenachrichtigung lauschen, während der Handle geöffnet ist. Wenn der Zieltreiber fehlschlägt, muss der UMDF-Treiber den Handle schließen.

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

Wenn Ihr Treiber sein lokales I/O-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 I/O-Zielobjekt zu löschen.

Weitere Informationen zu WdfIoTargetOpen finden Sie unter Initialisieren eines allgemeinen I/O-Ziels.

Weitere Informationen zu I/O-Zielen finden Sie unter Verwenden von I/O-Zielen.

Beispiele

Im folgenden Beispiel wird ein I/O-Zielobjekt erstellt, eine WDF_IO_TARGET_OPEN_PARAMS Struktur initialisiert und ein Remote-I/O-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;
}

Requirements (Anforderungen)

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header 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)

Weitere Informationen

DEVICE_OBJECT

WDF_IO_TARGET_OPEN_PARAMS

WdfDeviceGetIoTarget

WdfIoTargetClose

WdfIoTargetCreate

WdfIoTargetOpen

WdfObjectDelete