WdfUsbTargetDeviceFormatRequestForControlTransfer 함수(wdfusb.h)
[KMDF 및 UMDF에 적용]
WdfUsbTargetDeviceFormatRequestForControlTransfer 메서드는 USB 제어 전송 요청을 빌드하지만 요청을 보내지 않습니다.
구문
NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request,
[in] PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
[in, optional] WDFMEMORY TransferMemory,
[in, optional] PWDFMEMORY_OFFSET TransferOffset
);
매개 변수
[in] UsbDevice
WdfUsbTargetDeviceCreateWithParameters에 대한 이전 호출에서 가져온 USB 디바이스 개체에 대한 핸들입니다.
[in] Request
프레임워크 요청 개체에 대한 핸들입니다. 자세한 내용은 아래 설명 부분을 참조하십시오.
[in] SetupPacket
제어 전송을 설명하는 호출자가 할당한 WDF_USB_CONTROL_SETUP_PACKET 구조체에 대한 포인터입니다.
[in, optional] TransferMemory
디바이스별 명령에 따라 입력 또는 출력 버퍼를 설명하는 프레임워크 메모리 개체에 대한 핸들입니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.
[in, optional] TransferOffset
선택적 바이트 오프셋 및 길이 값을 제공하는 호출자가 할당한 WDFMEMORY_OFFSET 구조체에 대한 포인터입니다. 프레임워크는 이러한 값을 사용하여 TransferMemory 가 지정하는 버퍼 내에서 시작 주소와 길이를 결정합니다. 이 포인터가 NULL이면 프레임워크는 전체 버퍼를 사용합니다.
반환 값
WdfUsbTargetDeviceFormatRequestForControlTransfer 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
잘못된 매개 변수가 감지되었습니다. |
|
메모리가 부족했습니다. |
|
잘못된 메모리 설명자가 지정되었거나 지정된 I/O 요청이 이미 I/O 대상에 큐에 대기되었습니다. |
이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.
드라이버가 잘못된 개체 핸들을 제공하는 경우 버그 검사 발생합니다.
설명
WdfUsbTargetDeviceFormatRequestForControlTransfer와 WdfRequestSend를 사용하여 동기 또는 비동기적으로 USB 제어 전송 요청을 보냅니다. 또는 WdfUsbTargetDeviceSendControlTransferSynchronously 메서드를 사용하여 요청을 동기적으로 보냅니다.
드라이버가 I/O 큐에서 받은 I/O 요청을 전달하거나 새 요청을 만들고 보낼 수 있습니다. 두 경우 모두 프레임워크에는 요청 개체가 필요하며 컨트롤 전송 유형에 따라 일부 버퍼 공간이 필요할 수 있습니다.
드라이버가 I/O 큐에서 받은 I/O 요청을 전달하려면 다음을 수행합니다.
- WdfUsbTargetDeviceFormatRequestForControlTransfer 메서드의 Request 매개 변수에 대해 받은 요청의 핸들을 지정합니다.
-
TransferMemory 매개 변수에 대해 받은 요청의 입력 또는 출력 버퍼를 사용합니다.
드라이버는 WdfRequestRetrieveInputMemory 또는 WdfRequestRetrieveOutputMemory 를 호출하여 요청의 입력 또는 출력 버퍼를 나타내는 프레임워크 메모리 개체에 대한 핸들을 가져오고 해당 핸들을 TransferMemory의 값으로 사용해야 합니다.
-
새 요청 개체를 만들고 WdfUsbTargetDeviceFormatRequestForControlTransfer 메서드의 Request 매개 변수에 대한 핸들을 제공합니다.
WdfRequestCreate를 호출하여 하나 이상의 요청 개체를 미리 할당합니다. WdfRequestReuse를 호출하여 이러한 요청 개체를 다시 사용할 수 있습니다. 드라이버의 EvtDriverDeviceAdd 콜백 함수는 디바이스에 대한 요청 개체를 미리 할당할 수 있습니다.
-
버퍼 공간을 제공하고 WdfUsbTargetDeviceFormatRequestForControlTransfer 메서드의 TransferMemory 매개 변수에 대한 버퍼 핸들을 제공합니다.
드라이버는 이 버퍼 공간을 프레임워크 관리 메모리에 대한 WDFMEMORY 핸들로 지정해야 합니다. 드라이버는 다음 중 하나를 수행할 수 있습니다.
- 드라이버가 새 버퍼를 I/O 대상에 전달하도록 하려면 WdfMemoryCreate 또는 WdfMemoryCreatePreallocated 를 호출하여 새 메모리 버퍼를 만듭니다.
- 드라이버가 해당 버퍼의 내용을 I/O 대상에 전달하도록 하려면 WdfRequestRetrieveInputMemory 또는 WdfRequestRetrieveOutputMemory 를 호출하여 수신된 I/O 요청의 버퍼를 나타내는 메모리 개체에 대한 핸들을 가져옵니다.
동일한 요청을 사용하는 WdfUsbTargetDeviceFormatRequestForControlTransfer를 여러 차례 호출해도 추가 리소스 할당이 발생하지 않습니다. 따라서 WdfRequestCreate 가 STATUS_INSUFFICIENT_RESOURCES 반환할 가능성을 줄이기 위해 드라이버의 EvtDriverDeviceAdd 콜백 함수는 WdfRequestCreate 를 호출하여 디바이스에 대해 하나 이상의 요청 개체를 미리 할당할 수 있습니다. 이후에 드라이버는 WdfRequestReuse 호출, reformat(WdfUsbTargetDeviceFormatRequestForControlTransfer 호출), WdfRequestCreate에 대한 이후 호출에서 STATUS_INSUFFICIENT_RESOURCES 반환 값을 위험하지 않고 각 요청 개체를 다시 사용(WdfRequestSend 호출)할 수 있습니다. 다시 사용하는 요청 개체에 대한 WdfUsbTargetDeviceFormatRequestForControlTransfer 에 대한 모든 후속 호출은 매개 변수 값이 변경되지 않으면 STATUS_SUCCESS 반환합니다. 드라이버가 매번 동일한 요청 형식 메서드를 호출하지 않으면 추가 리소스가 할당될 수 있습니다.
프레임워크는 내부 URB에서 USBD_SHORT_TRANSFER_OK 플래그를 설정합니다. 이 플래그를 설정하면 데이터 전송의 마지막 패킷이 최대 패킷 크기보다 작을 수 있습니다.
I/O 요청이 완료된 후 상태 정보를 가져오는 방법에 대한 자세한 내용은 완료 정보 가져오기를 참조하세요.
WdfUsbTargetDeviceFormatRequestForControlTransfer 메서드 및 USB I/O 대상에 대한 자세한 내용은 USB I/O 대상을 참조하세요.
예제
다음 코드 예제에서는 요청 개체 및 메모리 개체를 만든 다음 "get 상태" 컨트롤 전송에 대 한 WDF_USB_CONTROL_SETUP_PACKET 구조를 초기화 합니다. 다음으로, 이 예제에서는 WdfUsbTargetDeviceFormatRequestForControlTransfer 를 호출하여 요청의 형식을 지정합니다. 그런 다음, 이 예제에서는 CompletionRoutine 콜백 함수를 설정하고 요청을 I/O 대상으로 보냅니다.
WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfRequestCreate(
&attributes,
WdfUsbTargetDeviceGetIoTarget(
UsbTargetDevice,
&request
)
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
&attributes,
NonPagedPool,
0,
sizeof(USHORT),
&memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
&packet,
BmRequestToDevice,
0
);
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
UsbTargetDevice,
request,
&packet,
memHandle,
NULL
);
if (!NT_SUCCESS(status)){
return status;
}
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL
);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | 유니버설 |
| 최소 KMDF 버전 | 1.0 |
| 최소 UMDF 버전 | 2.0 |
| 머리글 | wdfusb.h(Wdfusb.h 포함) |
| 라이브러리 | Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI 규정 준수 규칙 | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기