IWDFDevice::CreateIoQueue-Methode (wudfddi.h)
[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 für neuere Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]
Die CreateIoQueue-Methode konfiguriert die Standard-E/A-Warteschlange, die einem Gerät zugeordnet ist, oder erstellt eine sekundäre E/A-Warteschlange für das Gerät.
Syntax
HRESULT CreateIoQueue(
[in, optional] IUnknown *pCallbackInterface,
[in] BOOL bDefaultQueue,
[in] WDF_IO_QUEUE_DISPATCH_TYPE DispatchType,
[in] BOOL bPowerManaged,
[in] BOOL bAllowZeroLengthRequests,
[out] IWDFIoQueue **ppIoQueue
);
Parameter
[in, optional] pCallbackInterface
Ein Zeiger auf die IUnknown-Schnittstelle , die das Framework verwendet, um die Ereignisrückruffunktionen zu bestimmen, die der Treiber in der Warteschlange abonniert. Dies sind die Funktionen, die das Framework aufruft, wenn die relevanten Ereignisse auftreten.
Für UMDF-Versionen 1.9 und höher ist dieser Parameter für E/A-Warteschlangen erforderlich, die die sequenzielle oder parallele Verteilmethode verwenden, und er ist optional (kann NULL) für E/A-Warteschlangen sein, die die manuelle Verteilmethode verwenden. Für UMDF-Versionen vor 1.9 ist dieser Parameter für alle Verteilmethoden erforderlich.
[in] bDefaultQueue
Ein BOOL-Wert, der angibt, ob die Standard-E/A-Warteschlange konfiguriert oder eine sekundäre E/A-Warteschlange für das Gerät erstellt werden soll. TRUE gibt an, die Standard-E/A-Warteschlange zu konfigurieren. FALSE gibt an, eine sekundäre E/A-Warteschlange zu erstellen.
[in] DispatchType
Ein WDF_IO_QUEUE_DISPATCH_TYPE typisierter Wert, der angibt, wie der Treiber Anforderungen aus der E/A-Warteschlange empfangen muss.
[in] bPowerManaged
Ein BOOL-Wert, der angibt, ob die E/A-Warteschlange energieverwaltet ist. TRUE gibt an, dass das Framework die Verteilung für die E/A-Warteschlange automatisch mit Plug & Play (PnP) und dem Energiezustand des Geräts koordiniert. FALSE gibt an, dass keine automatisch koordinierte Verteilung erfolgt.
[in] bAllowZeroLengthRequests
Ein BOOL-Wert, der angibt, ob das Framework E/A-Anforderungen der Länge null direkt in die E/A-Warteschlange für den Treiber platziert, der verarbeitet werden soll. TRUE gibt an, dass der Treiber Lese- und Schreibanforderungen mit Puffern der Länge null empfangen soll. Das Heißt, das Framework platziert diese Anforderungstypen automatisch direkt in der E/A-Warteschlange für den Treiber. FALSE gibt an, dass das Framework E/A-Anforderungen der Länge null abschließt, anstatt sie in der E/A-Warteschlange zu platzieren.
[out] ppIoQueue
Ein Zeiger auf eine Variable, die einen Zeiger auf die IWDFIoQueue-Schnittstelle für das neu erstellte E/A-Warteschlangenobjekt oder das Standard-E/A-Warteschlangenobjekt empfängt.
Rückgabewert
CreateIoQueue gibt einen der folgenden Werte zurück:
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Die E/A-Warteschlange wurde erfolgreich erstellt. |
|
Die E/A-Warteschlange wird auf eine der folgenden Arten konfiguriert:
|
CreateIoQueue gibt möglicherweise auch andere HRESULT-Werte zurück.
Hinweise
Die IUnknown-Schnittstelle , die der Treiber für den pCallbackInterface-Parameter bereitstellt, kann mehrere Warteschlangenrückruffunktionen unterstützen. Das Framework ruft die QueryInterface-Methode auf der bereitgestellten IUnknown-Schnittstelle mehrmals auf, um die vom Treiber unterstützten Schnittstellenmethoden abzurufen. Wenn Anwendungen Aktionen ausführen, die sich auf die Methoden der unterstützten Schnittstellen beziehen (z. B. eine E/A-Leseanforderung), ruft das Framework die Methoden (z. B. die IQueueCallbackRead::OnRead-Methode ) auf, um den Treiber zu benachrichtigen. Das Framework ruft QueryInterface für die folgenden Schnittstellen auf:
IQueueCallbackDefaultIoHandler
Wenn der Treiber entweder WdfIoQueueDispatchSequential oder WdfIoQueueDispatchParallel für den DispatchType-Parameter von CreateIoQueue übergibt, um eine nichtmanuelle Warteschlange zu erstellen, kann CreateIoQueue S_OK nur zurückgeben, wenn das Warteschlangenrückrufobjekt des Treibers mindestens eine der vorherigen Schnittstellen implementiert und die Unterstützung solcher Schnittstellen über die IUnknown-Schnittstelle angibt, auf die pCallbackInterface verweist.
Wenn der Treiber WdfIoQueueDispatchManual für DispatchType übergibt, um eine manuelle Warteschlange zu erstellen, kann CreateIoQueue S_OK nur zurückgeben, wenn das Warteschlangenrückrufobjekt des Treibers keine der vorherigen Rückrufschnittstellen implementiert oder angibt, die Unterstützung angibt. Weitere Informationen zu den Rückrufobjekten des Treibers finden Sie unter Erstellen von Rückrufobjekten.
Das Framework ruft auch QueryInterface auf der bereitgestellten IUnknown-Schnittstelle auf, um zu ermitteln, ob der Treiber eine der folgenden Schnittstellen unterstützt:
Das Framework ruft auch QueryInterface auf der bereitgestellten IUnknown-Schnittstelle auf, um zu ermitteln, ob der Treiber die IQueueCallbackStateChange-Schnittstelle unterstützt. Das Warteschlangenrückrufobjekt des Treibers kann optional die Unterstützung von IQueueCallbackStateChange nur für eine manuelle Warteschlange implementieren und angeben. Das Warteschlangenrückrufobjekt des Treibers darf nicht implementieren und die Unterstützung von IQueueCallbackStateChange für eine sequenzielle oder parallele Warteschlange angeben.
Beispiele
Ein Codebeispiel für die Verwendung der CreateIoQueue-Methode finden Sie unter IWDFDriver::CreateDevice.
Anforderungen
| Anforderung | Wert |
|---|---|
| Ende des Supports | In UMDF 2.0 und höher nicht verfügbar. |
| Zielplattform | Desktop |
| UMDF-Mindestversion | 1.5 |
| Kopfzeile | wudfddi.h (include Wudfddi.h) |
| DLL | WUDFx.dll |