Freigeben über


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
S_OK
Die E/A-Warteschlange wurde erfolgreich erstellt.
HRESULT_FROM_WIN32(ERROR_BAD_CONFIGURATION)
Die E/A-Warteschlange wird auf eine der folgenden Arten konfiguriert:
  • Der DispatchType-Parameter gibt eine nichtmanuelle Warteschlange an, und keine der im Abschnitt Hinweise angegebenen E/A-Warteschlangenrückrufschnittstellen wird über den Parameter pCallbackInterface unterstützt.
  • Der DispatchType-Parameter gibt eine manuelle Warteschlange an, und eine oder mehrere der im Abschnitt Hinweise angegebenen E/A-Warteschlangenrückrufschnittstellen werden über den pCallbackInterface-Parameter unterstützt.
Weitere Informationen zu diesen Konfigurationen finden Sie im Abschnitt Hinweise.
 

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:

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

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.

Hinweis Der Treiber kann nicht dasselbe Rückrufobjekt für eine manuelle Warteschlange verwenden, die der Treiber für eine sequenzielle oder parallele Warteschlange verwendet. Das heißt, wenn der Treiber in einem Aufruf von CreateIoQueue einen bestimmten Zeiger an eine IUnknown-Schnittstelle übergibt, um eine manuelle Warteschlange zu erstellen, kann der Treiber den identischen Zeiger nicht später in einem Aufruf von CreateIoQueue an IUnknown übergeben, um eine sequenzielle oder parallele Warteschlange zu erstellen.
 
Weitere Informationen zum Konfigurieren des Versandmodus finden Sie unter Konfigurieren des Versandmodus für eine E/A-Warteschlange.

Das Framework ruft auch QueryInterface auf der bereitgestellten IUnknown-Schnittstelle auf, um zu ermitteln, ob der Treiber eine der folgenden Schnittstellen unterstützt:

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

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

Weitere Informationen

IObjectCleanup

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IWDFDevice

IWDFIoQueue

WDF_IO_QUEUE_DISPATCH_TYPE