функция WinUsb_ReadPipe (winusb.h)
Функция WinUsb_ReadPipe считывает данные из указанного канала.
Синтаксис
BOOL WinUsb_ReadPipe(
[in] WINUSB_INTERFACE_HANDLE InterfaceHandle,
[in] UCHAR PipeID,
[out] PUCHAR Buffer,
[in] ULONG BufferLength,
[out, optional] PULONG LengthTransferred,
[in, optional] LPOVERLAPPED Overlapped
);
Параметры
[in] InterfaceHandle
Непрозрачный дескриптор для интерфейса, содержащего конечную точку, с которой связан канал.
Чтобы считывать данные из канала, связанного с конечной точкой в первом интерфейсе, используйте дескриптор, возвращенный WinUsb_Initialize. Для всех остальных интерфейсов используйте дескриптор целевого интерфейса, полученный WinUsb_GetAssociatedInterface.
[in] PipeID
PipeID соответствует полю bEndpointAddress в дескрипторе конечной точки. Сведения о макете этого поля см. в таблице 9-13 статьи "Спецификация универсальной серийной шины 2.0" статьи USB Technology. В поле bEndpointAddress бит 7 указывает направление конечной точки: 0 для out; 1 для IN.
[out] Buffer
Выделенный вызывающим объектом буфер, который получает считываемые данные.
[in] BufferLength
Максимальное число байтов, предназначенных для чтения. Это число должно быть меньше или равно размеру буфера в байтах.
[out, optional] LengthTransferred
Указатель на переменную ULONG, которая получает фактическое количество байтов, скопированных в buffer. Дополнительные сведения см. в подразделе "Примечания".
[in, optional] Overlapped
Необязательный указатель на структуру OVERLAPPED, используемую для асинхронных операций. Если этот параметр указан, WinUsb_ReadPipe возвращает немедленно, а не синхронно дожидаясь завершения операции перед возвратом. По завершении операции подается сигнал о событии.
Возвращаемое значение
WinUsb_ReadPipe возвращает значение TRUE , если операция выполнена успешно. В противном случае эта функция возвращает значение FALSE, и вызывающий объект может получить зарегистрированную ошибку, вызвав Метод GetLastError.
GetLastError может вернуть следующий код ошибки.
| Код возврата | Описание |
|---|---|
|
Вызывающий объект передал значение NULL в параметре InterfaceHandle . |
|
Перекрываемая операция ввода-вывода выполняется, но не завершена. Если перекрывающаяся операция не может быть завершена немедленно, функция возвращает значение FALSE , а функция GetLastError возвращает ERROR_IO_PENDING, указывая, что операция выполняется в фоновом режиме. Вызовите WinUsb_GetOverlappedResult, чтобы проверка успешной или неудачной операции. |
|
Недостаточно памяти для выполнения операции. |
|
Время ожидания операции чтения, инициированной WinUsb_ReadPipe в стеке USB, истекло до завершения операции. |
Комментарии
Если данные, возвращаемые устройством, превышают максимальную длину передачи, WinUSB делит запрос на меньшие запросы максимальной длины передачи и отправляет их последовательно. Если длина передачи не кратна максимальному размеру пакета конечной точки (извлекаемого через член MaximumPacketSize структуры WINUSB_PIPE_INFORMATION), WinUSB увеличивает размер передачи до следующего, кратного MaximumPacketSize.
Размер ПАКЕТА USB не учитывается при передаче для запроса на чтение. Если устройство отвечает пакетом, слишком большим для буфера клиента, поведение запроса на чтение соответствует типу политики, заданной в канале. Если тип политики для канала ALLOW_PARTIAL_READS, WinUSB добавляет оставшиеся данные в начало следующей передачи. Если ALLOW_PARTIAL_READS не задан, запрос на чтение завершается ошибкой. Дополнительные сведения о типах политик см. в разделе Функции WinUSB для изменения политики канала.
Если приложение передает значение NULL в параметре Overlapped (синхронная операция), приложение должно убедиться, что значение LengthTransferred не равно NULL, даже если операция чтения не создает выходных данных.
Если значение Overlapped не равно NULL (асинхронная операция), параметру LengthTransferred можно присвоить значение NULL. Для перекрывающейся операции (и если LengthTransferred имеет значение, отличное от NULL ), значение, полученное в LengthTransferred после возврата WinUsb_ReadPipe , не имеет смысла до тех пор, пока перекрывающаяся операция не будет завершена. Чтобы получить фактическое количество байтов, считанных из канала, вызовите WinUsb_GetOverlappedResult.
Если в конечной точке нет данных (канал пуст), WinUsb_ReadPipe не возвращается до тех пор, пока в канале нет данных. Если возникает ошибка или истекает время ожидания, указанное приложением, WinUsb_ReadPipe всегда возвращает значение FALSE. Чтобы определить фактическую причину этого возвращаемого значения, всегда вызывайте Метод GetLastError. Например, в таких случаях значение ошибки GetLastError указывает фактическую причину:
- Если приложение указало значение времени ожидания в политике канала и истекает, WinUsb_ReadPipe возвращает значение FALSE, а GetLastError — ERROR_SEM_TIMEOUT.
- Если при чтении данных из канала возникает ошибка, WinUsb_ReadPipe возвращает значение FALSE, а GetLastError — ERROR_GEN_FAILURE.
Требования
| Требование | Значение |
|---|---|
| Целевая платформа | Универсальное |
| Верхняя часть | winusb.h (включая Winusb.h) |
| Библиотека | Winusb.lib |
| DLL | Winusb.dll |