WdfUsbTargetPipeWriteSynchronously 함수(wdfusb.h)
[KMDF 및 UMDF에 적용]
WdfUsbTargetPipeWriteSynchronously 메서드는 쓰기 요청을 빌드하고 지정된 USB 출력 파이프에 동기적으로 보냅니다.
통사론
NTSTATUS WdfUsbTargetPipeWriteSynchronously(
[in] WDFUSBPIPE Pipe,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[in, optional] PWDF_MEMORY_DESCRIPTOR MemoryDescriptor,
[out, optional] PULONG BytesWritten
);
매개 변수
[in] Pipe
WdfUsbInterfaceGetConfiguredPipe호출하여 가져온 프레임워크 파이프 개체에 대한 핸들입니다.
[in, optional] Request
프레임워크 요청 개체에 대한 핸들입니다. 이 매개 변수는 선택 사항이며 NULL
[in, optional] RequestOptions
요청에 대한 옵션을 지정하는 호출자가 할당한 WDF_REQUEST_SEND_OPTIONS 구조체에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL
[in, optional] MemoryDescriptor
디바이스에 쓸 데이터를 포함하는 버퍼를 설명하는 호출자 할당 WDF_MEMORY_DESCRIPTOR 구조체에 대한 포인터입니다. 이 버퍼에 대한 자세한 내용은 다음 주의 섹션을 참조하세요.
[out, optional] BytesWritten
작업이 성공하면 기록된 바이트 수를 받는 위치에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL
반환 값
WdfUsbTargetPipeWriteSynchronously 작업이 성공하면 I/O 대상의 완료 상태 값을 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 묘사 |
|---|---|
|
RequestOptions 매개 변수가 가리키는 WDF_REQUEST_SEND_OPTIONS 구조체의 크기가 잘못되었습니다. |
|
잘못된 매개 변수가 검색되었습니다. |
|
메모리가 부족했습니다. |
|
호출자의 IRQL이 PASSIVE_LEVEL 않았거나, 잘못된 메모리 설명자가 지정되었거나, 파이프의 형식이 잘못되었거나, 전송 방향이 잘못되었거나, 지정된 I/O 요청이 이미 I/O 대상에 큐에 대기되었습니다. |
|
드라이버에서 제한 시간 값을 제공했으며 할당된 시간 내에 요청이 완료되지 않았습니다. |
|
Request 매개 변수가 나타내는 I/O 요청 패킷(IRP)은 드라이버가 요청을 전달할 수 있는 충분한 IO_STACK_LOCATION 구조를 제공하지 않습니다. |
이 메서드는다른
드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.
발언
WdfUsbTargetPipeWriteSynchronously 메서드를 사용하여 쓰기 요청을 동기적으로 보냅니다. 쓰기 요청을 비동기적으로 보내려면 WdfUsbTargetPipeFormatRequestForWrite사용하고 WdfRequestSend사용합니다.
지정된 파이프는 출력 파이프여야 하며 파이프의
WdfUsbTargetPipeWriteSynchously 메서드는 드라이버가 RequestOptions 매개 변수의 WDF_REQUEST_SEND_OPTIONS 구조에 시간 제한 값을 제공하지 않는 한 요청이 완료될 때까지 또는 오류가 검색되지 않는 한 반환되지 않습니다.
드라이버가 I/O 큐에서 받은 I/O 요청을 전달하거나 새 요청을 만들고 보낼 수 있습니다. 두 경우 모두 프레임워크에는 요청 개체와 일부 버퍼 공간이 필요합니다.
드라이버가 I/O 큐에서 받은 I/O 요청을 전달하려면 다음을 수행합니다.
- Request 매개 변수에 대해 수신된 요청의 핸들을 지정합니다.
-
MemoryDescriptor 매개 변수에 대해 수신된 요청의 입력 버퍼를 사용합니다.
드라이버는
WdfRequestRetrieveInputMemory 호출하여 요청의 입력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 가져온 다음 해당 핸들을WDF_MEMORY_DESCRIPTOR 구조에 배치해야 합니다.
드라이버는 수신된 I/O 요청을 I/O 대상으로 보내는 더 작은 요청으로 나누는 경우가 많으므로 드라이버는 새 요청을 만들 수 있습니다.
새 I/O 요청을 만들려면 다음을 수행합니다.
-
WdfUsbTargetPipeWriteSynchronously 메서드의 Request 매개 변수에 대한 NULL 요청 핸들을 제공하거나 새 요청 개체를 만들고 해당 핸들을 제공합니다.
- NULL 요청 핸들을 제공하는 경우 프레임워크는 내부 요청 개체를 사용합니다. 이 기술은 사용하기는 간단하지만 드라이버는 요청을 취소할 수 없습니다.
- WdfRequestCreate 호출하여 하나 이상의 요청 개체를 만드는 경우 WdfRequestReuse호출하여 이러한 요청 개체를 다시 사용할 수 있습니다. 이 기술을 사용하면 드라이버의 EvtDriverDeviceAdd 콜백 함수가 디바이스에 대한 요청 개체를 미리 할당할 수 있습니다. 또한 필요한 경우 다른 드라이버 스레드가 WdfRequestCancelSentRequest 호출하여 요청을 취소할 수 있습니다.
드라이버가NULL이 아닌 또는 NULLRequest 매개 변수를 제공하는지 여부에 관계없이 드라이버에서NULLRequestOptions 매개 변수를 지정할 수 있습니다. 예를 들어 RequestOptions 매개 변수를 사용하여 제한 시간 값을 지정할 수 있습니다.
-
WdfUsbTargetPipeWriteSynchronously 메서드의 MemoryDescriptor 매개 변수에 대한 버퍼 공간을 제공합니다.
드라이버는 이 버퍼 공간을 로컬로 할당된 버퍼, WDFMEMORY 핸들 또는 MDL로 지정할 수 있습니다. 가장 편리한 방법을 사용할 수 있습니다.
필요한 경우 프레임워크는 데이터 버퍼액세스하기 위해 I/O 대상의
메서드에 맞는 버퍼 설명을 변환합니다. 사용할 수 있는 기술은 다음과 같습니다.
-
로컬 버퍼 제공
WdfUsbTargetPipeWriteSynchronously 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);또는 드라이버가 WdfRequestRetrieveInputMemory 호출하여 수신된 I/O 요청의 입력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 가져올 수 있습니다( 드라이버가 해당 버퍼의 내용을 I/O 대상에 전달하려는 경우). I/O 대상에 WdfUsbTargetPipeWriteSynchronously
새 요청이 삭제, 재사용 또는 다시 포맷될 때까지 드라이버는 수신된 I/O 요청을 완료하지 않아야 합니다. (WdfUsbTargetPipeWriteSynchronously 메모리 개체의 참조 수를 증가합니다. 요청 개체를 삭제, 재사용 또는 다시 포맷하면 메모리 개체의 참조 수가 감소합니다.) -
MDL 제공
드라이버는 WdfRequestRetrieveInputWdmmdl호출하여 수신된 I/O 요청과 연결된 MDL을 가져올 수 있습니다.
-
로컬 버퍼 제공
WdfUsbTargetPipeWriteSynchronously 메서드 및 USB I/O 대상에 대한 자세한 내용은 USB I/O 대상참조하세요.
예제
다음 코드 예제에서는 메모리 개체를 만들고, 개체의 버퍼에 대한 포인터를 가져오고, 버퍼를 채우고, 버퍼를 입력으로 사용하여 WdfUsbTargetPipeWriteSynchronously
WDF_MEMORY_DESCRIPTOR writeBufDesc;
WDFMEMORY wdfMemory;
ULONG writeSize, bytesWritten;
size_t bufferSize;
NTSTATUS status;
writeSize = SMALL_BUF_LEN;
status = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
0,
writeSize,
&wdfMemory,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
writeBuffer = WdfMemoryGetBuffer(
wdfMemory,
&bufferSize
);
FillMyBuffer(
writeBuffer,
writeSize
);
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&writeBufDesc,
writeBuffer,
writeSize
);
status = WdfUsbTargetPipeWriteSynchronously(
pipeHandle,
NULL,
NULL,
&writeBufDesc,
&bytesWritten
);
요구 사항
| 요구 | 값 |
|---|---|
| 대상 플랫폼 | 보편적 |
| 최소 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), KmdfIrqlEx kmdf(kmdf), ReadReqs(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |