функция 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

8-байтовый пакет установки типа WINUSB_SETUP_PACKET.

[out] Buffer

Выделенный вызывающим объектом буфер, содержащий передаваемые данные. Длина этого буфера не должна превышать 4 КБ.

[in] BufferLength

Число передаваемых байтов, не включая пакет установки. Это число должно быть меньше или равно размеру буфера (в байтах).

[out, optional] LengthTransferred

Указатель на переменную ULONG, получающую фактическое количество переданных байтов. Если приложение не ожидает передачи данных на этапе данных (BufferLength равно нулю), функция LengthTransferred может иметь значение NULL.

[in, optional] Overlapped

Необязательный указатель на структуру OVERLAPPED , которая используется для асинхронных операций. Если этот параметр указан, WinUsb_ControlTransfer немедленно возвращается, и событие получает сигнал по завершении операции. Если параметр Overlapped не указан, функция WinUsb_ControlTransfer передает данные синхронно.

Возвращаемое значение

WinUsb_ControlTransfer возвращает значение TRUE , если операция выполнена успешно. В противном случае эта подпрограмма возвращает значение FALSE, и вызывающий объект может получить зарегистрированную ошибку, вызвав Метод GetLastError.

GetLastError может возвращать один из следующих кодов ошибок.

Код возврата	Описание
ERROR_INVALID_HANDLE	Вызывающий объект передал значение NULL в параметре InterfaceHandle .
ERROR_NOT_ENOUGH_MEMORY	Указывает, что для выполнения операции недостаточно памяти.

Управляющий запрос всегда отправляется узлом в конечную точку по умолчанию USB-устройства, но получателем запроса может быть все устройство, интерфейс или конечная точка в выбранном альтернативном параметре. В вызове WinUsb_ControlTransfer приложение должно указать получателя с помощью двух параметров: InterfaceHandle и SetupPacket.

Если получателем запроса элемента управления является все устройство, первый интерфейс или любая конечная точка в этом интерфейсе, приложение должно использовать дескриптор, возвращаемый WinUsb_Initialize. Если получателем является любой другой интерфейс или его конечная точка, приложение должно получить дескриптор WinUSB, связанный с целевым интерфейсом, вызвав WinUsb_GetAssociatedInterface, а затем вызвать WinUsb_ControlTransfer , указав полученный дескриптор интерфейса.

Согласно разделу 9.3 официальной спецификации USB, маркер настройки передачи элемента управления содержит сведения о запросе. Для приложения WinUSB этот маркер установки описывается с помощью структуры WINUSB_SETUP_PACKET .

В токене установки поля bmRequestType и wIndex используются для указания получателя запроса. Эти поля соответствуют элементам RequestType и IndexWINUSB_SETUP_PACKET соответственно.

Два наименьших бита RequestType указывают получателя запроса. Получателем может быть устройство, интерфейс, конечная точка или другое (для запроса поставщика). В зависимости от получателя нижний байт индекса указывает на определяемый устройством индекс получателя. Значение Index зависит от типа запроса. Например, для стандартных запросов элементов управления значение равно 0 или указывает номер интерфейса или конечной точки. Для некоторых типов стандартных запросов, таких как запрос GET_DESCRIPTOR на получение дескриптора строки, значение Index указывает идентификатор языка.

Если получателем является устройство, приложение должно задать значения RequestType и Index . Два наименьших бита значения RequestType должны быть равны 0. Нижний байт значения Индекса зависит от типа запроса. InterfaceHandle должен быть дескриптором WinUSB, возвращаемым WinUsb_Initialize.

Если получателем запроса является интерфейс, приложение должно задать два младших бита RequestType для 0x01. Приложению не требуется задавать нижний байт индекса для любого типа запроса. Для стандартных запросов, запросов класса и поставщика Winusb.sys задает значение номера интерфейса целевого интерфейса. InterfaceHandle должен быть связан с целевым интерфейсом. Приложение может получить этот дескриптор, вызвав WinUsb_GetAssociatedInterface.

Если получателем является конечная точка, приложение должно задать два наименьших бита RequestType для 0x02 и более низкий байт индекса для адреса конечной точки. В этом случае InterfaceHandle связан с интерфейсом, содержащим конечную точку. Приложение может получить этот дескриптор, вызвав WinUsb_GetAssociatedInterface.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	winusb.h (включая Winusb.h)
Библиотека	Winusb.lib
DLL	Winusb.dll

См. также раздел