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. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. 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 Dispatching-Methode, verwenden und optional (kann NULL-) für E/A-Warteschlangen sein, die die manuelle Verteilermethode verwenden. Für UMDF-Versionen vor 1.9 ist dieser Parameter für alle Verteilermethoden 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, dass die Standard-E/A-Warteschlange konfiguriert wird; FALSE- gibt an, dass eine sekundäre E/A-Warteschlange erstellt wird.
[in] DispatchType
Ein WDF_IO_QUEUE_DISPATCH_TYPE-typed-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 Verteilerfunktion für die E/A-Warteschlange automatisch mit Plug and Play (PnP) und dem Leistungszustand des Geräts koordiniert; FALSCH- gibt keine automatisch koordinierte Verteilerung an.
[in] bAllowZeroLengthRequests
Ein BOOL-Wert, der angibt, ob das Framework E/A-Anforderungen der Länge null direkt in der E/A-Warteschlange platziert, damit der Treiber verarbeitet werden kann. TRUE- gibt an, dass der Treiber Lese- und Schreibanforderungen empfangen soll, die über Puffer der Länge null verfügen, d. h., das Framework fügt diese Anforderungstypen automatisch direkt in die E/A-Warteschlange für den Treiber ein. FALSE gibt an, dass das Framework leere E/A-Anforderungen abschließt, anstatt sie in die E/A-Warteschlange einzufügen.
[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 ist auf eine der folgenden Arten konfiguriert:
|
CreateIoQueue- können auch andere HRESULT-Werte zurückgeben.
Bemerkungen
Die IUnknown Schnittstelle, die der Treiber für die 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 auf (z. B. die IQueueCallbackRead::OnRead-Methode), 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 parameter DispatchType von CreateIoQueue, um eine nichtmanuale Warteschlange zu erstellen, CreateIoQueue- kann S_OK nur zurückgeben, wenn das Rückrufobjekt des Treibers mindestens eine der vorherigen Schnittstellen implementiert und die Unterstützung solcher Schnittstellen über die IUnknown Schnittstelle angibt, auf die pCallbackInterface pCallbackInterface verweist.
Wenn der Treiber WdfIoQueueDispatchManual für DispatchType zum Erstellen einer manuellen Warteschlange übergibt, kann CreateIoQueue- nur S_OK zurückgeben, wenn das Warteschlangenrückrufobjekt des Treibers keines der vorherigen Rückrufschnittstellen implementiert oder 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 festzustellen, ob der Treiber eine der folgenden Schnittstellen unterstützt:
Das Framework ruft auch QueryInterface- für die bereitgestellte IUnknown--Schnittstelle auf, um festzustellen, ob der Treiber die IQueueCallbackStateChange--Schnittstelle unterstützt. Das Rückrufobjekt der Treiberwarteschlange kann optional implementieren und angeben, dass IQueueCallbackStateChange nur für eine manuelle Warteschlange unterstützt wird. Das Rückrufobjekt der Treiberwarteschlange darf nicht implementiert werden und gibt die Unterstützung von IQueueCallbackStateChange für eine sequenzielle oder parallele Warteschlange an.
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 |
| Mindest-UMDF-Version | 1.5 |
| Header- | wudfddi.h (include Wudfddi.h) |
| DLL- | WUDFx.dll |