IWDFDevice::CreateIoQueue 方法 (wudfddi.h)

[警告: UMDF 2 是最新版的 UMDF,並取代 UMDF 1。 所有新的 UMDF 驅動程式都應該使用 UMDF 2 來撰寫。 未將新功能新增至 UMDF 1,且較新版本的 WINDOWS 10上不支援 UMDF 1。 通用 Windows 驅動程式必須使用 UMDF 2。 如需詳細資訊,請參閱使用 UMDF 消費者入門。]

CreateIoQueue方法會設定與裝置相關聯的預設 I/O 佇列,或為裝置建立次要 I/O 佇列。

語法

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
);

參數

[in, optional] pCallbackInterface

架構用來判斷驅動程式在佇列上訂閱的事件回呼函式的 IUnknown 介面指標。 這些是架構在發生相關事件時所呼叫的函式。

針對 UMDF 1.9 版和更新版本,使用循序或平行分派方法的 I/O 佇列需要此參數而且對於使用手動分派方法的 I/O 佇列而言,這是選擇性 (可為 Null) 。 對於 1.9 之前的 UMDF 版本,所有分派方法都需要此參數。

[in] bDefaultQueue

BOOL 值,指定是否要設定預設 I/O 佇列,或為裝置建立次要 I/O 佇列。 TRUE 表示設定預設 I/O 佇列; FALSE 表示要建立次要 I/O 佇列。

[in] DispatchType

WDF_IO_QUEUE_DISPATCH_TYPE型別值,可識別驅動程式如何從 I/O 佇列接收要求。

[in] bPowerManaged

BOOL 值,指定 I/O 佇列是否受電源管理。 TRUE表示架構會自動協調 I/O 佇列的分派,隨插即用 (PnP) 和裝置的電源狀態;FALSE表示不會自動協調分派。

[in] bAllowZeroLengthRequests

BOOL 值,指定架構是否直接在 I/O 佇列中放置零長度 I/O 要求,以便驅動程式處理。 TRUE 表示驅動程式應該接收長度為零的緩衝區的讀取和寫入要求,也就是說,架構會自動將這些要求類型直接放在驅動程式的 I/O 佇列中。 FALSE 表示架構完成零長度的 I/O 要求,而不是將它們放在 I/O 佇列中。

[out] ppIoQueue

變數的指標,會接收新建立 I/O 佇列物件或預設 I/O 佇列物件的 IWDFIoQueue 介面指標。

傳回值

CreateIoQueue 會傳回下列其中一個值:

傳回碼 描述
S_OK
已成功建立 I/O 佇列。
HRESULT_FROM_WIN32 (ERROR_BAD_CONFIGURATION)
I/O 佇列是以下列其中一種方式設定:
  • DispatchType參數會指定非受控佇列,而且「備註」區段中所指定的 I/O 佇列回呼介面都不支援pCallbackInterface參數。
  • DispatchType參數會透過pCallbackInterface參數支援手動佇列,以及一節中指定的一或多個 I/O 佇列回呼介面。
如需這些設定的詳細資訊,請參閱一節。
 

CreateIoQueue 也可能傳回其他 HRESULT 值。

備註

驅動程式為pCallbackInterface參數提供的IUnknown介面可以支援數個佇列回呼函式。 架構會在提供的IUnknown介面上多次呼叫QueryInterface方法,以擷取驅動程式支援的介面方法。 當應用程式執行與支援介面方法相關的動作時, (例如 I/O 讀取要求) ,架構會呼叫方法 (,例如 IQueueCallbackRead::OnRead 方法) 來通知驅動程式。 架構會針對下列介面呼叫 QueryInterface

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

當驅動程式針對CreateIoQueueDispatchType參數傳遞WdfIoQueueDispatchSequeueDispatchSequentialWdfIoQueueDispatchParallel來建立非受控佇列時,只有在驅動程式的佇列回呼物件至少實作上述其中一個介面時,CreateIoQueue才能傳回S_OK,並指出透過pCallbackInterface指向的IUnknown介面支援這類介面。

當驅動程式傳遞 WdfIoQueueDispatchManual for DispatchType 來建立手動佇列時,只有在驅動程式的佇列回呼物件未實作或指出任何上述回呼介面的支援時, CreateIoQueue 才能傳回S_OK。 如需驅動程式回呼物件的詳細資訊,請參閱 建立回呼物件

注意 驅動程式不能針對驅動程式用於循序或平行佇列的手動佇列使用相同的回呼物件。 也就是說,如果驅動程式將特定指標傳遞至呼叫 CreateIoQueue以建立手動佇列的IUnknown介面,則驅動程式稍後無法在呼叫CreateIoQueue中將相同的指標傳遞至IUnknown,以建立循序或平行佇列。
 
如需設定分派模式的詳細資訊,請參閱 設定 I/O 佇列的分派模式

架構也會在提供的IUnknown介面上呼叫QueryInterface,以判斷驅動程式是否支援下列任何介面:

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

架構也會在提供的IUnknown介面上呼叫QueryInterface,以判斷驅動程式是否支援IQueueCallbackStateChange介面。 驅動程式的佇列回呼物件可以選擇性地實作並指出只有手動佇列支援 IQueueCallbackStateChange 。 驅動程式的佇列回呼物件不得實作,並指出循序或平行佇列的 IQueueCallbackStateChange 支援。

範例

如需如何使用 CreateIoQueue 方法的程式碼範例,請參閱 IWDFDriver::CreateDevice

必要條件

   
結束支援 UMDF 2.0 和更新版本中無法使用。
目標平臺 桌面
最低 UMDF 版本 1.5
標頭 wudfddi.h (包括 Wudfddi.h)
DLL WUDFx.dll

另請參閱

IObjectCleanup

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IWDFDevice

IWDFIoQueue

WDF_IO_QUEUE_DISPATCH_TYPE