Função WdfIoQueueCreate (wdfio.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfIoQueueCreate cria e configura uma fila de E/S para um dispositivo especificado.

Sintaxe

NTSTATUS WdfIoQueueCreate(
  [in]            WDFDEVICE              Device,
  [in]            PWDF_IO_QUEUE_CONFIG   Config,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES QueueAttributes,
  [out, optional] WDFQUEUE               *Queue
);

Parâmetros

[in] Device

Um identificador para o objeto de dispositivo de estrutura ao qual a fila será associada.

[in] Config

Um ponteiro para uma estrutura de WDF_IO_QUEUE_CONFIG alocada pelo chamador.

[in, optional] QueueAttributes

Um ponteiro para uma estrutura de WDF_OBJECT_ATTRIBUTES alocada pelo chamador que especifica atributos de objeto para o novo objeto. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Queue

Um ponteiro para um local que recebe um identificador para um objeto de fila de estrutura.

Retornar valor

WdfIoQueueCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Um parâmetro de entrada é inválido.
STATUS_INFO_LENGTH_MISMATCH	O tamanho da estrutura WDF_IO_QUEUE_CONFIG está incorreto.
STATUS_POWER_STATE_INVALID	A estrutura está executando uma operação de gerenciamento de energia.
STATUS_INSUFFICIENT_RESOURCES	A quantidade de memória disponível é muito baixa.
STATUS_WDF_NO_CALLBACK	A estrutura WDF_IO_QUEUE_CONFIG não especifica nenhum manipulador de solicitação e o método de expedição não é WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	O driver está tentando criar uma fila padrão enquanto uma fila padrão já existe para o dispositivo ou ocorreu um erro interno.

Esse método também pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Cada chamada para WdfIoQueueCreate cria uma fila de E/S para um dispositivo. Seu driver pode criar várias filas de E/S para cada dispositivo.

Os parâmetros Config e QueueAttributes especificam a configuração da fila e os atributos de objeto.

Por padrão, o objeto de dispositivo de estrutura especificado pelo parâmetro Device torna-se o objeto pai do novo objeto de fila de estrutura. Se o driver especificar um objeto pai no membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES, o objeto pai poderá ser um objeto de dispositivo de estrutura ou qualquer objeto cuja cadeia de pais leva a um objeto de dispositivo de estrutura. A estrutura excluirá o objeto de fila quando excluir o objeto pai.

Se o driver fornecer funções de retorno de chamada EvtCleanupCallback ou EvtDestroyCallback para o objeto de fila da estrutura, a estrutura chamará essas funções de retorno de chamada em IRQL = PASSIVE_LEVEL.

Para obter mais informações sobre WdfIoQueueCreate, consulte Criando filas de E/S.

Exemplos

O exemplo de código a seguir é a seção de uma função de retorno de chamada EvtDriverDeviceAdd que cria a fila de E/S padrão de um dispositivo. O exemplo inicializa uma estrutura WDF_IO_QUEUE_CONFIG e chama WdfIoQueueCreate.

NTSTATUS
MyEvtDriverDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_IO_QUEUE_CONFIG  ioQueueConfig;
    WDFQUEUE  hQueue;
...
    WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(
                                           &ioQueueConfig,
                                           WdfIoQueueDispatchSequential
                                           );

    ioQueueConfig.EvtIoDefault = MyEvtIoDefault;

    status = WdfIoQueueCreate(
                              device,
                              &ioQueueConfig,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &hQueue
                              );
    if (!NT_SUCCESS (status)) {
        return status;
    }
...
}

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfio.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Regras de conformidade da DDI	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)