функция 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 может вернуть следующий код ошибки.

Код возврата Описание
ERROR_INVALID_HANDLE
 Вызывающий объект передал значение NULL в параметре InterfaceHandle .
ERROR_IO_PENDING
 Перекрываемая операция ввода-вывода выполняется, но не завершена. Если перекрывающаяся операция не может быть завершена немедленно, функция возвращает значение FALSE , а функция GetLastError возвращает ERROR_IO_PENDING, указывая, что операция выполняется в фоновом режиме. Вызовите WinUsb_GetOverlappedResult, чтобы проверка успешной или неудачной операции.
ERROR_NOT_ENOUGH_MEMORY
 Недостаточно памяти для выполнения операции.
ERROR_SEM_TIMEOUT
 Время ожидания операции чтения, инициированной 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

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

WinUSB

Функции WinUSB

WinUsb_Initialize