WdfRequestForwardToParentDeviceIoQueue-Funktion (wdfrequest.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WdfRequestForwardToParentDeviceIoQueue Methode stellt eine E/A-Anforderung aus der E/A-Warteschlange eines untergeordneten Geräts in eine angegebene E/A-Warteschlange des übergeordneten Geräts des untergeordneten Geräts zurück.

Syntax

NTSTATUS WdfRequestForwardToParentDeviceIoQueue(
  [in] WDFREQUEST                   Request,
  [in] WDFQUEUE                     ParentDeviceQueue,
  [in] PWDF_REQUEST_FORWARD_OPTIONS ForwardOptions
);

Parameter

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt.

[in] ParentDeviceQueue

Ein Handle zu einem Framework-Warteschlangenobjekt.

[in] ForwardOptions

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_REQUEST_FORWARD_OPTIONS Struktur.

Rückgabewert

WdfRequestForwardToParentDeviceIoQueue 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_INFO_LENGTH_MISMATCH	Die Größe der angegebenen WDF_REQUEST_FORWARD_OPTIONS Struktur ist ungültig.
STATUS_INVALID_PARAMETER	Ein Element der angegebenen WDF_REQUEST_FORWARD_OPTIONS-Struktur enthält einen ungültigen Wert.
STATUS_INVALID_DEVICE_REQUEST	Dieser Wert wird zurückgegeben, wenn einer der folgenden Aktionen auftritt: Der Treiber hat die E/A-Anforderung nicht aus einer E/A-Warteschlange abgerufen. Die Quell- und Ziel-E/A-Warteschlangen sind identisch. Die angegebene E/A-Warteschlange gehört nicht zum übergeordneten Gerät. Der Treiber hat garantierten Vorwärtsfortschritt aktiviert, und die angegebene E/A-Anforderung ist für Situationen mit geringem Arbeitsspeicher reserviert. Der Treiber hat WdfPdoInitAllowForwardingRequestToParentnicht aufgerufen.
STATUS_WDF_BUSY	Die angegebene E/A-Warteschlange akzeptiert keine neuen Anforderungen.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Bevor ein Treiber WdfRequestForwardToParentDeviceIoQueueaufrufen kann, muss er WdfPdoInitAllowForwardingRequestToParentaufrufen.

Der Treiber muss dieselbe Methode verwenden, um auf Datenpuffer zuzugreifen, die für das übergeordnete Gerät und das untergeordnete Gerät (gepuffert, direkt oder nicht) verwendet werden.

Wenn Ihr Treiber WdfRequestForwardToParentDeviceIoQueue aufruft, um eine E/A-Anforderung erneut abzufragen, darf der Treiber das Anforderungsobjekt nicht als übergeordnetes Element anderer Frameworkobjekte verwenden, z. B. Timerobjekte oder Arbeitsaufgabenobjekte.

Wenn Ihr Treiber WdfDeviceInitSetRequestAttributes aufgerufen, um Kontextbereich anzugeben, für die anforderungsobjekte des übergeordneten Geräts angegeben wird, fügt das Framework diesen Kontextbereich nicht hinzu, um Objekte anzufordern, die der Treiber in der Warteschlange eines untergeordneten Geräts empfängt. Der Treiber kann WdfObjectAllocateContext- aufrufen, um den Kontextbereich zu einem Anforderungsobjekt hinzuzufügen, bevor der Treiber WdfRequestForwardToParentDeviceIoQueueaufruft. Wenn der Treiber WdfDeviceInitSetRequestAttributes für die Anforderungsobjekte des untergeordneten Geräts aufgerufen wird und wenn die Anforderungsobjekte des übergeordneten Geräts Kontextbereich verwenden, der dem Kontextbereich des untergeordneten Geräts entspricht oder kleiner ist, kann der Treiber den Kontextbereich des Anforderungsobjekts verwenden, ohne WdfObjectAllocateContextaufrufen zu müssen.

Derzeit muss der Treiber die option senden und vergessen für alle erneuten E/A-Anforderungen verwenden. Beachten Sie daher, dass das Framework möglicherweise bereits das untergeordnete Gerät entfernt hat, das das Anforderungsobjekt ursprünglich empfangen hat. Daher darf der Treiber nicht die EvtCleanupCallback oder EvtDestroyCallback Funktion eines erneuten Anforderungsobjekts verwenden, um auf untergeordnete Geräteressourcen zuzugreifen, da die Ressourcen möglicherweise entfernt werden, bevor die EvtCleanupCallback oder EvtDestroyCallback-Funktion ausgeführt wird.

Weitere Informationen zu WdfRequestForwardToParentDeviceIoQueuefinden Sie unter Requeuing I/O Requests.

Beispiele

Im folgenden Codebeispiel wird zuerst das übergeordnete Gerät eines Geräts bestimmt, das eine E/A-Anforderung empfangen hat, und anschließend wird die E/A-Anforderung an die Standard-E/A-Warteschlange des übergeordneten Geräts zurückverfragt.

WDFDEVICE device, parentDevice;
WDF_REQUEST_FORWARD_OPTIONS forwardOptions;
NTSTATUS status;

device = WdfIoQueueGetDevice(WdfRequestGetIoQueue(Request));
parentDevice = WdfPdoGetParent(device);

WDF_REQUEST_FORWARD_OPTIONS_INIT(&forwardOptions);
status = WdfRequestForwardToParentDeviceIoQueue(
             Request,
             WdfDeviceGetDefaultQueue(parentDevice),
             &forwardOptions
             );
if (!NT_SUCCESS(status)) {
    WdfRequestComplete(
                       Request,
                       status
                       );
  }

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.9
Header-	wdfrequest.h (include Wdf.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf)

Siehe auch

WdfPdoInitAllowForwardingRequestToParent

Freigeben über