Função WdfUsbTargetPipeFormatRequestForWrite (wdfusb.h)
[Aplica-se a KMDF e UMDF]
O método WdfUsbTargetPipeFormatRequestForWrite cria uma solicitação de gravação para um pipe de saída USB, mas não envia a solicitação.
Sintaxe
NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY WriteMemory,
[in, optional] PWDFMEMORY_OFFSET WriteOffset
);
Parâmetros
[in] Pipe
Um identificador para um objeto de pipe de estrutura que foi obtido chamando WdfUsbInterfaceGetConfiguredPipe.
[in] Request
Um identificador para um objeto de solicitação de estrutura. Para obter mais informações, consulte a seção Comentários a seguir.
[in, optional] WriteMemory
Um identificador para um objeto de memória de estrutura. Esse objeto representa um buffer que contém dados que serão enviados para o pipe. Para obter mais informações sobre esse buffer, consulte a seção Comentários a seguir.
[in, optional] WriteOffset
Um ponteiro para uma estrutura de WDFMEMORY_OFFSET alocada pelo chamador que fornece valores opcionais de deslocamento e comprimento de bytes. A estrutura usa esses valores para determinar o endereço inicial e o comprimento, dentro do buffer de gravação, para a transferência de dados. Se esse ponteiro for NULL, a transferência de dados começará no início do buffer e o tamanho da transferência será o tamanho do buffer.
Retornar valor
WdfUsbTargetPipeFormatRequestForWrite 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 |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
Memória insuficiente disponível. |
|
Um descritor de memória inválido foi especificado, o tipo do pipe não era válido, a direção de transferência era inválida ou a solicitação de E/S especificada já estava na fila para um destino de E/S. |
|
O deslocamento que o parâmetro Offset especificou era inválido. |
|
O IRP (pacote de solicitação de E/S) que o parâmetro Request representa não fornece estruturas de IO_STACK_LOCATION suficientes para permitir que o driver encaminhe a solicitação. |
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
Use WdfUsbTargetPipeFormatRequestForWrite, seguido por WdfRequestSend, para enviar solicitações de gravação de forma síncrona ou assíncrona. Como alternativa, use o método WdfUsbTargetPipeWriteSynchronously para enviar solicitações de gravação de forma síncrona.
O pipe especificado deve ser um pipe de saída e o tipo do pipe deve ser WdfUsbPipeTypeBulk ou WdfUsbPipeTypeInterrupt.
Você pode encaminhar uma solicitação de E/S recebida pelo driver em uma fila de E/S ou pode criar e enviar uma nova solicitação. Em ambos os casos, a estrutura requer um objeto de solicitação e algum espaço em buffer.
Para encaminhar uma solicitação de E/S que seu driver recebeu em uma fila de E/S:
- Especifique o identificador da solicitação recebida para o parâmetro Request do método WdfUsbTargetPipeFormatRequestForWrite.
-
Use o buffer de entrada da solicitação recebida para o parâmetro WriteMemory do método WdfUsbTargetPipeFormatRequestForWrite.
O driver deve chamar WdfRequestRetrieveInputMemory para obter um identificador para um objeto de memória de estrutura que representa o buffer de entrada da solicitação e usar esse identificador como o valor de WriteMemory.
Os drivers geralmente dividem as solicitações de E/S recebidas em solicitações menores que enviam para um destino de E/S, para que o driver possa criar novas solicitações.
Para criar uma nova solicitação de E/S:
-
Crie um novo objeto de solicitação e forneça seu identificador para o parâmetro Request do método WdfUsbTargetPipeFormatRequestForWrite.
Chame WdfRequestCreate para pré-alocar um ou mais objetos de solicitação. Você pode reutilizar esses objetos de solicitação chamando WdfRequestReuse. A função de retorno de chamada EvtDriverDeviceAdd do driver pode pré-alocar objetos de solicitação para um dispositivo.
-
Forneça espaço em buffer e forneça o identificador do buffer para o parâmetro WriteMemory do método WdfUsbTargetPipeFormatRequestForWrite.
Seu driver deve especificar esse espaço de buffer como um identificador WDFMEMORY para memória gerenciada por estrutura. O driver pode fazer um dos seguintes procedimentos:
- Chame WdfMemoryCreate ou WdfMemoryCreatePreallocated para criar um novo buffer de memória, se desejar que o driver passe um novo buffer para o destino de E/S.
- Chame WdfRequestRetrieveInputMemory para obter um identificador para o objeto de memória que representa o buffer de uma solicitação de E/S recebida, se você quiser que o driver passe o conteúdo desse buffer para o destino de E/S.
Várias chamadas para WdfUsbTargetPipeFormatRequestForWrite que usam a mesma solicitação não causam alocações de recursos adicionais. Portanto, para reduzir a chance de WdfRequestCreate retornar STATUS_INSUFFICIENT_RESOURCES, a função de retorno de chamada EvtDriverDeviceAdd do driver pode chamar WdfRequestCreate para pré-alocar um ou mais objetos de solicitação para um dispositivo. O driver pode reutilizar (chamar WdfRequestReuse), reformatar (chamar WdfUsbTargetPipeFormatRequestForWrite) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar um valor retornado STATUS_INSUFFICIENT_RESOURCES de uma chamada posterior para WdfRequestCreate. Todas as chamadas subsequentes para WdfUsbTargetPipeFormatRequestForWrite para o objeto de solicitação reutilizado retornarão STATUS_SUCCESS, se os valores de parâmetro não forem alterados. (Se o driver não chamar o mesmo método de formatação de solicitação a cada vez, recursos adicionais poderão ser alocados.)
Para obter informações sobre como obter informações de status após a conclusão de uma solicitação de E/S, consulte Obtendo informações de conclusão.
Para obter mais informações sobre o método WdfUsbTargetPipeFormatRequestForWrite e destinos de E/S USB, consulte Destinos de E/S USB.
Exemplos
O exemplo de código a seguir é do driver de exemplo kmdf_fx2 . Este exemplo é uma função de retorno de chamada EvtIoWrite que encaminha uma solicitação de gravação para um pipe USB. O exemplo chama WdfRequestRetrieveInputMemory para obter o buffer de entrada da solicitação e, em seguida, formata a solicitação de gravação para que a solicitação possa ser enviada para um pipe USB. Em seguida, o exemplo registra uma função de retorno de chamada CompletionRoutine . Por fim, ele envia a solicitação para o pipe USB.
VOID
OsrFxEvtIoWrite(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
NTSTATUS status;
WDFUSBPIPE pipe;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
status = STATUS_INVALID_PARAMETER;
goto Exit;
}
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkWritePipe;
status = WdfRequestRetrieveInputMemory(
Request,
&reqMemory
);
if (!NT_SUCCESS(status)){
goto Exit;
}
status = WdfUsbTargetPipeFormatRequestForWrite(
pipe,
Request,
reqMemory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
EvtRequestWriteCompletionRoutine,
pipe
);
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
WdfRequestCompleteWithInformation(
Request,
status,
0
);
}
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 | wdfusb.h (include Wdfusb.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade da DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |