WdfUsbTargetPipeReadSynchronousously 함수(wdfusb.h)
[KMDF 및 UMDF에 적용]
WdfUsbTargetPipeReadSynchronously 메서드는 읽기 요청을 빌드하고 지정된 USB 입력 파이프에 동기적으로 보냅니다.
통사론
NTSTATUS WdfUsbTargetPipeReadSynchronously(
[in] WDFUSBPIPE Pipe,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional] PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional] PULONG BytesRead
);
매개 변수
[in] Pipe
WdfUsbInterfaceGetConfiguredPipe호출하여 가져온 프레임워크 파이프 개체에 대한 핸들입니다.
[in, optional] Request
프레임워크 요청 개체에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL
[in, optional] RequestOptions
요청에 대한 옵션을 지정하는 호출자가 할당한 WDF_REQUEST_SEND_OPTIONS 구조체에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL
[in, optional] MemoryDescriptor
디바이스에서 데이터를 받을 버퍼를 설명하는 호출자 할당 WDF_MEMORY_DESCRIPTOR 구조체에 대한 포인터입니다. 드라이버가 WdfUsbTargetPipeSetNoMaximumPacketSizeCheck호출하지 않는 한 버퍼 크기는 파이프의 최대 패킷 크기의 배수여야 합니다. 이 버퍼에 대한 자세한 내용은 다음 주의 섹션을 참조하세요.
[out, optional] BytesRead
작업이 성공하면 읽은 바이트 수를 받는 위치에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL
반환 값
WdfUsbTargetPipeReadSynchronously 작업이 성공하면 I/O 대상의 완료 상태 값을 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
반환 코드 | 묘사 |
---|---|
|
RequestOptions 가리키는 WDF_REQUEST_SEND_OPTIONS 구조체의 크기가 잘못되었습니다. |
|
잘못된 매개 변수가 검색되었습니다. |
|
메모리가 부족했습니다. |
|
호출자의 IRQL이 PASSIVE_LEVEL 않았거나, 잘못된 메모리 설명자가 지정되었거나, 파이프의 형식이 잘못되었거나, 전송 방향이 잘못되었거나, 지정된 I/O 요청이 이미 I/O 대상에 큐에 대기되었습니다. |
|
버퍼 크기가 파이프의 최대 패킷 크기의 배수가 아닙니다. |
|
드라이버에서 제한 시간 값을 제공했으며 할당된 시간 내에 요청이 완료되지 않았습니다. |
|
Request 매개 변수가 나타내는 I/O 요청 패킷(IRP)은 드라이버가 요청을 전달할 수 있는 충분한 IO_STACK_LOCATION 구조를 제공하지 않습니다. |
이 메서드는다른
드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.
발언
WdfUsbTargetPipeReadSynchronously 메서드를 사용하여 읽기 요청을 동기적으로 보냅니다. 읽기 요청을 비동기적으로 보내려면 WdfUsbTargetPipeFormatRequestForRead사용하고 그 다음에 WdfRequestSend사용합니다.
WdfUsbTargetPipeReadSynchously 메서드는 요청이 완료될 때까지 반환되지 않습니다. 드라이버가 RequestOptions 매개 변수가 가리키는 WDF_REQUEST_SEND_OPTIONS 구조에서 시간 제한 값을 제공하지 않거나 오류가 검색되지 않는 한 반환되지 않습니다.
드라이버가 I/O 큐에서 받은 I/O 요청을 전달하거나 새 요청을 만들고 보낼 수 있습니다. 두 경우 모두 프레임워크에는 요청 개체와 일부 버퍼 공간이 필요합니다.
드라이버가 I/O 큐에서 받은 I/O 요청을 전달하려면 다음을 수행합니다.
- Request 매개 변수에 대해 수신된 요청의 핸들을 지정합니다.
-
수신된 요청의 출력 버퍼를 WdfUsbTargetPipeReadSynchronously 메서드의 MemoryDescriptor 매개 변수에 사용합니다.
드라이버는 WdfRequestRetrieveOutputMemory 호출하여 요청의 출력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 가져온 다음, 해당 핸들을 MemoryDescriptor가 가리키는 WDF_MEMORY_DESCRIPTOR 구조에 배치해야.
드라이버는 수신된 I/O 요청을 I/O 대상으로 보내는 더 작은 요청으로 나누는 경우가 많으므로 드라이버는 새 요청을 만들 수 있습니다.
새 I/O 요청을 만들려면 다음을 수행합니다.
-
WdfUsbTargetPipeReadSynchronously 메서드의 Request 매개 변수에 NULL 요청 핸들을 제공하거나 새 요청 개체를 만들고 해당 핸들을 제공합니다.
- NULL 요청 핸들을 제공하는 경우 프레임워크는 내부 요청 개체를 사용합니다. 이 기술은 사용하기는 간단하지만 드라이버는 요청을 취소할 수 없습니다.
- WdfRequestCreate 호출하여 하나 이상의 요청 개체를 만드는 경우 WdfRequestReuse호출하여 이러한 요청 개체를 다시 사용할 수 있습니다. 이 기술을 사용하면 드라이버의 EvtDriverDeviceAdd 콜백 함수가 디바이스에 대한 요청 개체를 미리 할당할 수 있습니다. 또한 필요한 경우 다른 드라이버 스레드가 WdfRequestCancelSentRequest 호출하여 요청을 취소할 수 있습니다.
드라이버가NULL이 아닌 또는 NULLRequest 매개 변수를 제공하는지 여부에 관계없이 드라이버에서NULLRequestOptions 매개 변수를 지정할 수 있습니다. 예를 들어 RequestOptions 매개 변수를 사용하여 제한 시간 값을 지정할 수 있습니다.
-
WdfUsbTargetPipeReadSynchronously 메서드의 MemoryDescriptor 매개 변수에 대한 버퍼 공간을 제공합니다.
드라이버는 이 버퍼 공간을 로컬로 할당된 버퍼, WDFMEMORY 핸들 또는 MDL로 지정할 수 있습니다. 가장 편리한 방법을 사용할 수 있습니다.
필요한 경우 프레임워크는 데이터 버퍼액세스하기 위해 I/O 대상의
메서드에 맞는 버퍼 설명을 변환합니다. 사용할 수 있는 기술은 다음과 같습니다.
-
로컬 버퍼 제공
WdfUsbTargetPipeReadSynchronously I/O 요청을 동기적으로 처리하므로 드라이버는 다음 코드 예제와 같이 호출 루틴에 로컬인 요청 버퍼를 만들 수 있습니다.
WDF_MEMORY_DESCRIPTOR memoryDescriptor; MY_BUFFER_TYPE myBuffer; WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor, (PVOID) &myBuffer, sizeof(myBuffer));
-
WDFMEMORY 핸들 제공
다음 코드 예제와 같이 WdfMemoryCreate 또는 WdfMemoryCreatePreallocated 호출하여 프레임워크 관리 메모리에 대한 핸들을 가져옵니다.
WDF_MEMORY_DESCRIPTOR memoryDescriptor; WDFMEMORY memoryHandle = NULL; status = WdfMemoryCreate(NULL, NonPagedPool, POOL_TAG, MY_BUFFER_SIZE, &memoryHandle, NULL); WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor, memoryHandle, NULL);
또는 드라이버가 해당 버퍼의 내용을 I/O 대상에 전달하도록 하려면 WdfRequestRetrieveOutputMemory 호출하여 수신된 I/O 요청의 출력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 가져올 수 있습니다. I/O 대상으로 보내는 WdfUsbTargetPipeReadSynchronously
새 요청이 삭제, 재사용 또는 다시 포맷될 때까지 드라이버는 수신된 I/O 요청을 완료하지 않아야 합니다. (WdfUsbTargetPipeReadSynchronously 메모리 개체의 참조 수를 증가합니다. 요청 개체를 삭제, 재사용 또는 다시 포맷하면 메모리 개체의 참조 수가 감소합니다.) -
MDL 제공
드라이버는 WdfRequestRetrieveOutputWdmmdl호출하여 수신된 I/O 요청과 연결된 MDL을 가져올 수 있습니다.
-
로컬 버퍼 제공
드라이버가 파이프에 대한 연속 판독기 구성한 경우 WdfUsbTargetPipeReadSynchronously 호출할 수 없습니다.
I/O 요청이 완료된 후 상태 정보를 가져오는 방법에 대한 자세한 내용은 완료 정보 가져오기
WdfUsbTargetPipeReadSynchronously 메서드 및 USB I/O 대상에 대한 자세한 내용은 USB I/O 대상참조하세요.
예제
다음 코드 예제에서는 프레임워크 메모리 개체를 만들고,
WDFMEMORY wdfMemory;
WDF_MEMORY_DESCRIPTOR readBufDesc;
ULONG BytesRead;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
readSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return ;
}
buffer = WdfMemoryGetBuffer(
wdfMemory,
NULL
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&readBufDesc,
buffer,
readSize
);
status = WdfUsbTargetPipeReadSynchronously(
Pipe,
NULL,
NULL,
&readBufDesc,
&BytesRead
);
요구 사항
요구 | 값 |
---|---|
대상 플랫폼 | 보편적 |
최소 KMDF 버전 | 1.0 |
최소 UMDF 버전 | 2.0 |
헤더 | wdfusb.h(Wdfusb.h 포함) |
라이브러리 | Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF) |
IRQL |
PASSIVE_LEVEL |
DDI 규정 준수 규칙 |
DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf), WriteReqs(kmdf) |