Função WdfRequestForwardToIoQueue (wdfrequest.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfRequestForwardToIoQueue enfileira uma solicitação de E/S para uma das filas de E/S do driver de chamada.

Sintaxe

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

Parâmetros

[in] Request

Um identificador para um objeto de solicitação de estrutura.

[in] DestinationQueue

Um identificador para um objeto de fila de estrutura.

Retornar valor

WdfRequestForwardToIoQueue 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_DEVICE_REQUEST	Esse valor será retornado se ocorrer um dos seguintes procedimentos: O driver não obteve a solicitação de uma fila de E/S. As filas de origem e destino são as mesmas. As filas de origem e destino não pertencem ao mesmo dispositivo. O driver não é o proprietário da solicitação. A solicitação é cancelável.
STATUS_WDF_BUSY	A fila de destino não está aceitando novas solicitações.

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

O driver deve possuir a solicitação de E/S e deve ter obtido a solicitação de uma de suas filas de E/S.

As filas de origem e destino não podem ser as mesmas. Em outras palavras, o driver não pode chamar WdfRequestForwardToIoQueue para retornar uma solicitação para a fila da qual ele veio. Para redirecionar uma solicitação para a mesma fila, use WdfRequestRequeue.

As filas de origem e de destino devem pertencer ao mesmo dispositivo.

A solicitação não deve ser cancelável. Se o driver tiver chamado WdfRequestMarkCancelable ou WdfRequestMarkCancelableEx para tornar a solicitação cancelável, ele deverá chamar WdfRequestUnmarkCancelable antes de chamar WdfRequestForwardToIoQueue.

Depois que o driver chama WdfRequestForwardToIoQueue, o driver não possui a solicitação requeued até que a estrutura entregue a solicitação da nova fila para o driver. Enquanto a solicitação está na nova fila, a estrutura é proprietária da solicitação e pode cancelá-la sem notificar o driver.

Antes que WdfRequestForwardToIoQueue retorne, os seguintes eventos podem ocorrer:

Se a fila de destino estiver vazia, a estrutura poderá entregar a solicitação de E/S requeuida a um dos manipuladores de solicitação da fila de destino.
Se o método de expedição da fila de origem for sequencial ou paralelo, a estrutura poderá fornecer outra solicitação a um dos manipuladores de solicitação da fila de origem.

Para obter mais informações sobre WdfRequestForwardToIoQueue, consulte Requeuing I/O Requests and Managing I/O Queues.

Exemplos

O exemplo de código a seguir é uma função de retorno de chamada EvtIoDeviceControl do driver de exemplo PCIDRV . Se uma solicitação recebida contiver um código de controle de E/S de IOCTL_NDISPROT_INDICATE_STATUS, o driver chamará WdfRequestForwardToIoQueue para mover a solicitação para uma fila de E/S diferente.

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

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	wdfrequest.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade da DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)