функция WinUsb_ControlTransfer (winusb.h)
Функция 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 может возвращать один из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Вызывающий объект передал значение NULL в параметре InterfaceHandle . |
|
Указывает, что для выполнения операции недостаточно памяти. |
Комментарии
Управляющий запрос всегда отправляется узлом в конечную точку по умолчанию 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 |