Condividi tramite


Metodo IWDFDevice::CreateIoQueue (wudfddi.h)

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo CreateIoQueue configura la coda di I/O predefinita associata a un dispositivo o crea una coda di I/O secondaria per il dispositivo.

Sintassi

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

Parametri

[in, optional] pCallbackInterface

Puntatore all'interfaccia IUnknown usata dal framework per determinare le funzioni di callback degli eventi sottoscritte dal driver nella coda. Si tratta delle funzioni chiamate dal framework quando si verificano gli eventi pertinenti.

Per UMDF versioni 1.9 e successive, questo parametro è necessario per le code di I/O che usano il metodo di invio sequenziale o parallelo ed è facoltativo (può essere NULL) per le code di I/O che usano il metodo di invio manuale. Per le versioni di UMDF precedenti alla 1.9, questo parametro è necessario per tutti i metodi di invio.

[in] bDefaultQueue

Valore BOOL che specifica se configurare la coda di I/O predefinita o creare una coda di I/O secondaria per il dispositivo. TRUE indica di configurare la coda di I/O predefinita; FALSE indica di creare una coda di I/O secondaria.

[in] DispatchType

Valore tipizzato WDF_IO_QUEUE_DISPATCH_TYPE che identifica il modo in cui il driver deve ricevere richieste dalla coda di I/O.

[in] bPowerManaged

Valore BOOL che specifica se la coda di I/O è gestita dall'alimentazione. TRUE indica che il framework coordina automaticamente l'invio per la coda di I/O con Plug and Play (PnP) e lo stato di alimentazione del dispositivo; FALSE indica che l'invio coordinato non viene eseguito automaticamente.

[in] bAllowZeroLengthRequests

Valore BOOL che specifica se il framework inserisce le richieste di I/O di lunghezza zero direttamente nella coda di I/O per il driver da gestire. TRUE indica che il driver deve ricevere richieste di lettura e scrittura con buffer di lunghezza zero, ovvero il framework inserisce automaticamente questi tipi di richiesta direttamente nella coda di I/O per il driver. FALSE indica che il framework completa le richieste di I/O di lunghezza zero anziché inserirle nella coda di I/O.

[out] ppIoQueue

Puntatore a una variabile che riceve un puntatore all'interfaccia IWDFIoQueue per l'oggetto coda I/O appena creato o l'oggetto coda di I/O predefinito.

Valore restituito

CreateIoQueue restituisce uno dei valori seguenti:

Codice restituito Descrizione
S_OK
La coda di I/O è stata creata correttamente.
HRESULT_FROM_WIN32(ERROR_BAD_CONFIGURATION)
La coda di I/O è configurata in uno dei modi seguenti:
  • Il parametro DispatchType specifica una coda non gestita e nessuna delle interfacce di callback della coda di I/O specificate nella sezione Osservazioni è supportata tramite il parametro pCallbackInterface .
  • Il parametro DispatchType specifica una coda manuale e una o più interfacce di callback della coda di I/O specificate nella sezione Osservazioni sono supportate tramite il parametro pCallbackInterface .
Per altre informazioni su queste configurazioni, vedere la sezione Osservazioni.
 

CreateIoQueue potrebbe restituire anche altri valori HRESULT.

Commenti

L'interfaccia IUnknown fornita dal driver per il parametro pCallbackInterface può supportare diverse funzioni di callback della coda. Il framework chiama il metodo QueryInterface nell'interfaccia IUnknown fornita più volte per recuperare i metodi di interfaccia supportati dal driver. Quando le applicazioni eseguono azioni correlate ai metodi delle interfacce supportate (ad esempio, una richiesta di lettura di I/O), il framework chiama i metodi (ad esempio, il metodo IQueueCallbackRead::OnRead ) per notificare al driver. Il framework chiama QueryInterface per le interfacce seguenti:

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

Quando il driver passa WdfIoQueueDispatchSequential o WdfIoQueueDispatchParallel per il parametro DispatchType di CreateIoQueue per creare una coda non gestita, CreateIoQueue può restituire S_OK solo se l'oggetto di callback della coda del driver implementa almeno una delle interfacce precedenti e indica il supporto di tali interfacce tramite l'interfaccia IUnknown a cui punta pCallbackInterface .

Quando il driver passa WdfIoQueueDispatchManual per DispatchType per creare una coda manuale, CreateIoQueue può restituire S_OK solo se l'oggetto callback della coda del driver non implementa o indica il supporto di una qualsiasi delle interfacce di callback precedenti. Per altre informazioni sugli oggetti di callback del driver, vedere Creazione di oggetti di callback.

Nota Il driver non può usare lo stesso oggetto di callback per una coda manuale usata dal driver per una coda sequenziale o parallela. Ovvero, se il driver passa un puntatore specifico a un'interfaccia IUnknown in una chiamata a CreateIoQueue per creare una coda manuale, il driver non può passare successivamente il puntatore identico a IUnknown in una chiamata a CreateIoQueue per creare una coda sequenziale o parallela.
 
Per altre informazioni sulla configurazione della modalità di invio, vedere Configuring Dispatch Mode for an I/O Queue.For more information about configuring dispatch mode, see Configuring Dispatch Mode for an I/O Queue.

Il framework chiama anche QueryInterface nell'interfaccia IUnknown fornita per determinare se il driver supporta una delle interfacce seguenti:

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

Il framework chiama anche QueryInterface nell'interfaccia IUnknown fornita per determinare se il driver supporta l'interfaccia IQueueCallbackStateChange . L'oggetto callback della coda del driver può implementare e indicare facoltativamente il supporto di IQueueCallbackStateChange solo per una coda manuale. L'oggetto callback della coda del driver non deve implementare e indicare il supporto di IQueueCallbackStateChange per una coda sequenziale o parallela.

Esempio

Per un esempio di codice su come usare il metodo CreateIoQueue , vedere IWDFDriver::CreateDevice.

Requisiti

Requisito Valore
Fine del supporto Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione Desktop
Versione UMDF minima 1.5
Intestazione wudfddi.h (include Wudfddi.h)
DLL WUDFx.dll

Vedi anche

IObjectCleanup

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IWDFDevice

IWDFIoQueue

WDF_IO_QUEUE_DISPATCH_TYPE