Función WdfIoQueueCreate (wdfio.h)

Artículo
02/29/2024

[Se aplica a KMDF y UMDF]

El método WdfIoQueueCreate crea y configura una cola de E/S para un dispositivo especificado.

Sintaxis

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

Identificador del objeto de dispositivo de marco al que se asociará la cola.

[in] Config

Puntero a una estructura de WDF_IO_QUEUE_CONFIG asignada por el autor de la llamada.

[in, optional] QueueAttributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES asignada por el autor de la llamada que especifica los atributos de objeto para el nuevo objeto. Este parámetro es opcional y puede ser WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Queue

Puntero a una ubicación que recibe un identificador de un objeto de cola de marco.

Valor devuelto

WdfIoQueueCreate devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	Un parámetro de entrada no es válido.
STATUS_INFO_LENGTH_MISMATCH	El tamaño de la estructura WDF_IO_QUEUE_CONFIG es incorrecto.
STATUS_POWER_STATE_INVALID	El marco está realizando una operación de administración de energía.
STATUS_INSUFFICIENT_RESOURCES	La cantidad de memoria disponible es demasiado baja.
STATUS_WDF_NO_CALLBACK	La estructura WDF_IO_QUEUE_CONFIG no especifica ningún controlador de solicitudes y el método de distribución no es WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	El controlador está intentando crear una cola predeterminada mientras ya existe una cola predeterminada para el dispositivo o se produjo un error interno.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Cada llamada a WdfIoQueueCreate crea una cola de E/S para un dispositivo. El controlador puede crear varias colas de E/S para cada dispositivo.

Los parámetros Config y QueueAttributes especifican los atributos de objeto y configuración de la cola.

De forma predeterminada, el objeto de dispositivo de marco que especifica el parámetro Device se convierte en el objeto primario del nuevo objeto de cola de marco. Si el controlador especifica un objeto primario en el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES, el objeto primario puede ser un objeto de dispositivo de marco o cualquier objeto cuya cadena de elementos primarios conduce a un objeto de dispositivo de marco. El marco eliminará el objeto queue cuando elimine el objeto primario.

Si el controlador proporciona funciones de devolución de llamada EvtCleanupCallback o EvtDestroyCallback para el objeto de cola de marco, el marco llama a estas funciones de devolución de llamada en IRQL = PASSIVE_LEVEL.

Para obtener más información sobre WdfIoQueueCreate, vea Creating I/O Queues.

Ejemplos

El siguiente ejemplo de código es la sección de una función de devolución de llamada EvtDriverDeviceAdd que crea la cola de E/S predeterminada de un dispositivo. En el ejemplo se inicializa una estructura de WDF_IO_QUEUE_CONFIG y, a continuación, se llama a 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfio.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Reglas de cumplimiento de DDI	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)