WdfRequestRetrieveOutputMemory 함수(wdfrequest.h)
[KMDF 및 UMDF에 적용]
WdfRequestRetrieveOutputMemory 메서드는 I/O 요청의 출력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 검색합니다.
구문
NTSTATUS WdfRequestRetrieveOutputMemory(
[in] WDFREQUEST Request,
[out] WDFMEMORY *Memory
);
매개 변수
[in] Request
프레임워크 요청 개체에 대한 핸들입니다.
[out] Memory
프레임워크 메모리 개체에 대한 핸들을 수신하는 위치에 대한 포인터입니다.
반환 값
WdfRequestRetrieveOutputMemory 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
입력 매개 변수가 잘못되었습니다. |
|
요청 유형이 잘못되었거나 요청이 버퍼링되거나 직접 I/O를 사용하지 않습니다. 데이터 버퍼에 액세스하기 위해 지원되는 방법에 대한 자세한 내용은 다음 설명 섹션을 참조하세요. |
|
요청이 이미 완료되었습니다. |
|
출력 버퍼의 길이는 0입니다. |
|
메모리가 부족합니다. |
이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.
드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.
설명
요청의 출력 버퍼는 드라이버가 요청의 발신자에게 제공하는 디스크의 데이터와 같은 정보를 수신합니다. 드라이버는 WdfRequestRetrieveOutputMemory 를 호출하여 읽기 요청 또는 디바이스 I/O 컨트롤 요청에 대한 출력 버퍼를 가져올 수 있지만 쓰기 요청은 출력 데이터를 제공하지 않기 때문에 쓰기 요청에 대해서는 가져올 수 없습니다.
WdfRequestRetrieveOutputMemory 메서드는 버퍼링된 I/O 메서드 또는 직접 I/O 메서드를 사용하여 데이터 버퍼에 액세스하는 I/O 요청에 대한 출력 버퍼를 검색합니다. 요청의 I/O 제어 코드가 IRP_MJ_INTERNAL_DEVICE_CONTROL 경우 또는 요청이 다른 커널 모드 드라이버에서 온 경우 WdfRequestRetrieveOutputMemory 는 버퍼링되거나 직접 I/O를 사용하지 않는 I/O 요청도 지원합니다.
WdfRequestRetrieveOutputMemory가 STATUS_SUCCESS 반환하는 경우 드라이버는 출력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 받습니다. 버퍼에 액세스하려면 드라이버가 WdfMemoryGetBuffer를 호출해야 합니다.
드라이버는 Request 매개 변수가 나타내는 I/O 요청을 완료할 때까지 검색된 프레임워크 메모리 개체에 액세스할 수 있습니다.
드라이버는 WdfRequestRetrieveOutputMemory를 호출하는 대신 버퍼의 주소와 길이를 검색하는 WdfRequestRetrieveOutputBuffer를 호출할 수 있습니다.
WdfRequestRetrieveOutputMemory에 대한 자세한 내용은 Framework-Based 드라이버에서 데이터 버퍼 액세스를 참조하세요.
예제
다음 코드 예제에서는 EvtIoRead 콜백 함수가 읽기 요청의 출력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 가져오는 방법을 보여 줍니다. 그런 다음, 이 예제에서는 USB I/O 대상에 읽기 요청을 포맷하고 보냅니다.
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;
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | 유니버설 |
| 최소 KMDF 버전 | 1.0 |
| 최소 UMDF 버전 | 2.0 |
| 머리글 | wdfrequest.h(Wdf.h 포함) |
| 라이브러리 | Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| 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) |