Função WdfRequestRetrieveOutputMemory (wdfrequest.h)
[Aplica-se a KMDF e UMDF]
O método WdfRequestRetrieveOutputMemory recupera um identificador para um objeto de memória de estrutura que representa o buffer de saída de uma solicitação de E/S.
Sintaxe
NTSTATUS WdfRequestRetrieveOutputMemory(
[in] WDFREQUEST Request,
[out] WDFMEMORY *Memory
);
Parâmetros
[in] Request
Um identificador para um objeto de solicitação de estrutura.
[out] Memory
Um ponteiro para um local que recebe um identificador para um objeto de memória de estrutura.
Retornar valor
WdfRequestRetrieveOutputMemory retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método poderá retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro de entrada é inválido. |
|
O tipo de solicitação não é válido ou a solicitação não está usando e/S direta nem buffer. Para obter mais informações sobre métodos com suporte para acessar buffers de dados, consulte a seção Comentários a seguir. |
|
A solicitação já foi concluída. |
|
O comprimento do buffer de saída é zero. |
|
Não há memória suficiente. |
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 buffer de saída de uma solicitação recebe informações, como dados de um disco, que o driver fornece ao originador da solicitação. Seu driver pode chamar WdfRequestRetrieveOutputMemory para obter o buffer de saída para uma solicitação de leitura ou uma solicitação de controle de E/S do dispositivo, mas não para uma solicitação de gravação (porque as solicitações de gravação não fornecem dados de saída).
O método WdfRequestRetrieveOutputMemory recupera o buffer de saída para solicitações de E/S que usam o método de E/S armazenado em buffer ou o método de E/S direto para acessar buffers de dados. Se o código de controle de E/S da solicitação for IRP_MJ_INTERNAL_DEVICE_CONTROL ou se a solicitação veio de outro driver no modo kernel, WdfRequestRetrieveOutputMemory também oferecerá suporte a solicitações de E/S que não usam E/S nem buffer.
Se WdfRequestRetrieveOutputMemory retornar STATUS_SUCCESS, o driver receberá um identificador para um objeto de memória de estrutura que representa o buffer de saída. Para acessar o buffer, o driver deve chamar WdfMemoryGetBuffer.
O driver pode acessar o objeto de memória da estrutura recuperada até concluir a solicitação de E/S que o parâmetro Request representa.
Em vez de chamar WdfRequestRetrieveOutputMemory, o driver pode chamar WdfRequestRetrieveOutputBuffer, que recupera o endereço e o comprimento do buffer.
Para obter mais informações sobre WdfRequestRetrieveOutputMemory, consulte Acessando buffers de dados em drivers de Framework-Based.
Exemplos
O exemplo de código a seguir mostra como uma função de retorno de chamada EvtIoRead pode obter um identificador para o objeto de memória da estrutura que representa o buffer de saída de uma solicitação de leitura. Em seguida, o exemplo formata e envia a solicitação de leitura para um destino de E/S USB.
VOID
MyEvtIoRead(
IN WDFQUEUE Queue,
IN WDFREQUEST Request,
IN size_t Length
)
{
WDFUSBPIPE pipe;
NTSTATUS status;
WDFMEMORY reqMemory;
PDEVICE_CONTEXT pDeviceContext;
//
// The driver previously stored a pipe handle in
// the device object's context space.
//
pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
pipe = pDeviceContext->BulkReadPipe;
//
// Get output memory.
//
status = WdfRequestRetrieveOutputMemory(
Request,
&reqMemory
);
if(!NT_SUCCESS(status)){
goto Exit;
}
//
// Format the request.
//
status = WdfUsbTargetPipeFormatRequestForRead(
pipe,
Request,
reqMemory,
NULL
);
if (!NT_SUCCESS(status)) {
goto Exit;
}
WdfRequestSetCompletionRoutine(
Request,
EvtRequestReadCompletionRoutine,
pipe
);
//
// Send the request.
//
if (WdfRequestSend(
Request,
WdfUsbTargetPipeGetIoTarget(pipe),
WDF_NO_SEND_OPTIONS
) == FALSE) {
status = WdfRequestGetStatus(Request);
goto Exit;
}
Exit:
//
// Complete the request now if an error occurred.
//
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 | wdfrequest.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade de DDI | DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MemAfterReqCompletedIntIoctl(kmdf), MemAfterReqCompletedIntIoctlA(kmdf), MemAfterReqCompletedIoctl(kmdf), MemAfterReqCompletedIoctlA(kmdf), MemAfterReqCompletedRead(kmdf), MemAfterReqCompletedReadA(kmdf), MemAfterReqCompletedWrite(kmdf), OutputBufferAPI(kmdf) |