Método IWDFDevice::CreateIoQueue (wudfddi.h)

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método CreateIoQueue configura a fila de E/S padrão associada a um dispositivo ou cria uma fila de E/S secundária para o dispositivo.

Sintaxe

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

Parâmetros

[in, optional] pCallbackInterface

Um ponteiro para a interface IUnknown que a estrutura usa para determinar as funções de retorno de chamada de evento que o driver assina na fila. Essas são as funções que a estrutura chama quando os eventos relevantes ocorrem.

Para as versões 1.9 e posteriores do UMDF, esse parâmetro é necessário para filas de E/S que usam o método de expedição sequencial ou paralela e é opcional (pode ser NULL) para filas de E/S que usam o método de expedição manual. Para versões umdf anteriores à 1.9, esse parâmetro é necessário para todos os métodos de expedição.

[in] bDefaultQueue

Um valor BOOL que especifica se a fila de E/S padrão deve ser configurada ou criar uma fila de E/S secundária para o dispositivo. TRUE indica configurar a fila de E/S padrão; FALSE indica criar uma fila de E/S secundária.

[in] DispatchType

Um valor tipo WDF_IO_QUEUE_DISPATCH_TYPE que identifica como o driver deve receber solicitações da fila de E/S.

[in] bPowerManaged

Um valor BOOL que especifica se a fila de E/S é gerenciada por energia. TRUE indica que a estrutura coordena automaticamente o envio para a fila de E/S com Plug and Play (PnP) e o estado de energia do dispositivo; FALSE indica que não há expedição coordenada automaticamente.

[in] bAllowZeroLengthRequests

Um valor BOOL que especifica se a estrutura coloca solicitações de E/S de comprimento zero diretamente na fila de E/S para o driver manipular. TRUE indica que o driver deve receber solicitações de leitura e gravação que têm buffers de comprimento zero– ou seja, a estrutura coloca automaticamente esses tipos de solicitação diretamente na fila de E/S do driver. FALSE indica que a estrutura conclui solicitações de E/S de comprimento zero em vez de colocá-las na fila de E/S.

[out] ppIoQueue

Um ponteiro para uma variável que recebe um ponteiro para a interface IWDFIoQueue para o objeto de fila de E/S recém-criado ou o objeto de fila de E/S padrão.

Valor retornado

CreateIoQueue retorna um dos seguintes valores:

Código de retorno Descrição
S_OK
A fila de E/S foi criada com êxito.
HRESULT_FROM_WIN32(ERROR_BAD_CONFIGURATION)
A fila de E/S é configurada de uma das seguintes maneiras:
  • O parâmetro DispatchType especifica uma fila nãomanual e nenhuma das interfaces de retorno de chamada de fila de E/S especificadas na seção Comentários têm suporte por meio do parâmetro pCallbackInterface .
  • O parâmetro DispatchType especifica uma fila manual e uma ou mais interfaces de retorno de chamada da fila de E/S especificadas na seção Comentários têm suporte por meio do parâmetro pCallbackInterface .
Para obter mais informações sobre essas configurações, consulte a seção Comentários.
 

CreateIoQueue também pode retornar outros valores HRESULT.

Comentários

A interface IUnknown fornecida pelo driver para o parâmetro pCallbackInterface pode dar suporte a várias funções de retorno de chamada de fila. A estrutura chama o método QueryInterface na interface IUnknown fornecida várias vezes para recuperar os métodos de interface compatíveis com o driver. Quando os aplicativos executam ações relacionadas aos métodos das interfaces com suporte (como uma solicitação de leitura de E/S), a estrutura chama os métodos (como o método IQueueCallbackRead::OnRead ) para notificar o driver. A estrutura chama QueryInterface para as seguintes interfaces:

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackRead

IQueueCallbackWrite

Quando o driver passa wdfIoQueueDispatchSequential ou WdfIoQueueDispatchParallel para o parâmetro DispatchType de CreateIoQueue para criar uma fila nãomanual, CreateIoQueue só poderá retornar S_OK se o objeto de retorno de chamada da fila do driver implementar pelo menos uma das interfaces anteriores e indicar o suporte dessas interfaces por meio da interface IUnknown para a qual pCallbackInterface aponta.

Quando o driver passa WdfIoQueueDispatchManual para DispatchType para criar uma fila manual, CreateIoQueue só poderá retornar S_OK se o objeto de retorno de chamada da fila do driver não implementar ou indicar suporte a nenhuma das interfaces de retorno de chamada anteriores. Para obter mais informações sobre os objetos de retorno de chamada do driver, consulte Criando objetos de retorno de chamada.

Nota O driver não pode usar o mesmo objeto de retorno de chamada para uma fila manual que o driver usa para uma fila sequencial ou paralela. Ou seja, se o driver passar um ponteiro específico para uma interface IUnknown em uma chamada para CreateIoQueue para criar uma fila manual, o driver não poderá passar o ponteiro idêntico para IUnknown em uma chamada para CreateIoQueue para criar uma fila sequencial ou paralela.
 
Para obter mais informações sobre como configurar o modo de expedição, consulte Configurando o Modo de Expedição para uma Fila de E/S.

A estrutura também chama QueryInterface na interface IUnknown fornecida para determinar se o driver dá suporte a qualquer uma das seguintes interfaces:

IObjectCleanup

IQueueCallbackIoResume

IQueueCallbackIoStop

A estrutura também chama QueryInterface na interface IUnknown fornecida para determinar se o driver dá suporte à interface IQueueCallbackStateChange . Opcionalmente, o objeto de retorno de chamada da fila do driver pode implementar e indicar o suporte de IQueueCallbackStateChange somente para uma fila manual. O objeto de retorno de chamada da fila do driver não deve implementar e indicar o suporte de IQueueCallbackStateChange para uma fila sequencial ou paralela.

Exemplos

Para obter um exemplo de código de como usar o método CreateIoQueue , consulte IWDFDriver::CreateDevice.

Requisitos

   
Fim do suporte Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino Desktop
Versão mínima do UMDF 1.5
Cabeçalho wudfddi.h (include Wudfddi.h)
DLL WUDFx.dll

Confira também

IObjectCleanup

IQueueCallbackCreate

IQueueCallbackDefaultIoHandler

IQueueCallbackDeviceIoControl

IQueueCallbackIoResume

IQueueCallbackIoStop

IQueueCallbackRead

IQueueCallbackStateChange

IQueueCallbackWrite

IWDFDevice

IWDFIoQueue

WDF_IO_QUEUE_DISPATCH_TYPE