WinUsb_ControlTransfer 함수(winusb.h)

아티클
08/27/2023

WinUsb_ControlTransfer 함수는 기본 제어 엔드포인트를 통해 제어 데이터를 전송합니다.

구문

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

매개 변수

[in] InterfaceHandle

선택한 구성의 인터페이스에 대한 불투명 핸들입니다.

컨트롤 요청의 수신자를 전체 디바이스 또는 첫 번째 인터페이스로 지정하려면 WinUsb_Initialize 반환된 핸들을 사용합니다. 다른 모든 인터페이스의 경우 WinUsb_GetAssociatedInterface 호출하여 대상 인터페이스에 대한 핸들을 가져온 다음, 가져온 인터페이스 핸들을 지정하여 WinUsb_ControlTransfer 호출합니다.

[in] SetupPacket

WINUSB_SETUP_PACKET 형식의 8 바이트 설정 패킷입니다.

[out] Buffer

전송할 데이터를 포함하는 호출자가 할당한 버퍼입니다. 이 버퍼의 길이는 4KB를 초과하면 안됩니다.

[in] BufferLength

설정 패킷을 포함하지 않고 전송할 바이트 수입니다. 이 숫자는 버퍼의 크기(바이트)보다 작거나 같아야 합니다.

[out, optional] LengthTransferred

전송된 실제 바이트 수를 수신하는 ULONG 변수에 대한 포인터입니다. 애플리케이션에서 데이터 단계(BufferLength 가 0임) 중에 데이터가 전송될 것으로 예상하지 않는 경우 LengthTransferred 는 NULL일 수 있습니다.

[in, optional] Overlapped

비동기 작업에 사용되는 OVERLAPPED 구조체에 대한 선택적 포인터입니다. 이 매개 변수를 지정하면 WinUsb_ControlTransfer 즉시 반환되고 작업이 완료되면 이벤트가 신호를 보냅니다. Overlapped가 제공되지 않으면 WinUsb_ControlTransfer 함수는 데이터를 동기적으로 전송합니다.

반환 값

WinUsb_ControlTransfer 작업이 성공하면 TRUE 를 반환합니다. 그렇지 않으면 이 루틴은 FALSE를 반환하고 호출자는 GetLastError를 호출하여 기록된 오류를 검색할 수 있습니다.

GetLastError 는 다음 오류 코드 중 하나를 반환할 수 있습니다.

반환 코드	설명
ERROR_INVALID_HANDLE	호출자가 InterfaceHandle 매개 변수에서 NULL을 전달했습니다.
ERROR_NOT_ENOUGH_MEMORY	작업을 수행할 메모리가 부족했음을 나타냅니다.

설명

제어 요청은 항상 호스트에서 USB 디바이스의 기본 엔드포인트로 전송되지만 요청 수신자는 선택한 대체 설정의 전체 디바이스, 인터페이스 또는 엔드포인트일 수 있습니다. WinUsb_ControlTransfer 호출에서 애플리케이션은 InterfaceHandle 및 SetupPacket이라는 두 매개 변수를 통해 받는 사람을 나타내야 합니다.

제어 요청의 수신자가 전체 디바이스, 첫 번째 인터페이스 또는 해당 인터페이스의 엔드포인트인 경우 애플리케이션은 WinUsb_Initialize 반환된 핸들을 사용해야 합니다. 받는 사람이 다른 인터페이스 또는 해당 엔드포인트인 경우 애플리케이션은 WinUsb_GetAssociatedInterface 호출하여 대상 인터페이스와 연결된 WinUSB 핸들을 가져온 다음, 가져온 인터페이스 핸들을 지정하여 WinUsb_ControlTransfer 호출해야 합니다.

공식 USB 사양의 섹션 9.3에 따라 제어 전송의 설정 토큰에는 요청에 대한 정보가 포함됩니다. WinUSB 애플리케이션의 경우 해당 설정 토큰은 WINUSB_SETUP_PACKET 구조를 사용하여 설명합니다.

설정 토큰 내에서 bmRequestType 및 wIndex 필드는 요청 수신자를 나타내는 데 사용됩니다. 이러한 필드는 각각 WINUSB_SETUP_PACKETRequestType 및 Index 멤버에 해당합니다.

RequestType의 가장 낮은 두 비트는 요청의 수신자를 나타냅니다. 받는 사람은 디바이스, 인터페이스, 엔드포인트 또는 기타(공급업체 요청용)일 수 있습니다. 받는 사람에 따라 인덱 스의 하위 바이트는 받는 사람의 디바이스 정의 인덱스입니다. Index 값은 요청 유형에 따라 달라집니다. 예를 들어 표준 제어 요청의 경우 값은 0이거나 인터페이스 또는 엔드포인트 번호를 나타냅니다. 문자열 설명자를 가져오기 위한 GET_DESCRIPTOR 요청과 같은 특정 유형의 표준 요청의 경우 Index 값은 언어 ID를 나타냅니다.

받는 사람이 디바이스인 경우 애플리케이션은 RequestType 및 Index 값을 설정해야 합니다. RequestType 값의 가장 낮은 두 비트는 0이어야 합니다. 인덱스 값의 하위 바이트는 요청 유형에 따라 달라집니다. InterfaceHandle은 WinUsb_Initialize 반환된 WinUSB 핸들이어야 합니다.

요청 수신자가 인터페이스인 경우 애플리케이션은 가장 낮은 두 비트의 RequestType 을 0x01 설정해야 합니다. 애플리케이션은 모든 유형의 요청에 대해 인덱 스의 하위 바이트를 설정할 필요가 없습니다. 표준, 클래스 및 공급업체 요청의 경우 Winusb.sys 값을 대상 인터페이스의 인터페이스 번호로 설정합니다. InterfaceHandle은 대상 인터페이스와 연결되어야 합니다. 애플리케이션은 WinUsb_GetAssociatedInterface 호출하여 해당 핸들을 가져올 수 있습니다.

받는 사람이 엔드포인트인 경우 애플리케이션은 가장 낮은 두 비트의 RequestType 을 0x02, 인덱스의 하위 바이트를 엔드포인트 주소로 설정해야 합니다. 이 경우 InterfaceHandle 은 엔드포인트를 포함하는 인터페이스와 연결됩니다. 애플리케이션은 WinUsb_GetAssociatedInterface 호출하여 해당 핸들을 가져올 수 있습니다.