WinUsb_ReadPipe 함수(winusb.h)

아티클
08/27/2023

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 필드에 해당합니다. 이 필드의 레이아웃에 대한 자세한 내용은 USB 기술의 "유니버설 직렬 버스 사양 수정 버전 2.0"의 표 9-13을 참조하세요. bEndpointAddress 필드에서 비트 7은 엔드포인트의 방향을 나타냅니다. OUT의 경우 0, IN의 경우 1입니다.

[out] Buffer

읽은 데이터를 수신하는 호출자가 할당한 버퍼입니다.

[in] BufferLength

읽을 최대 바이트 수입니다. 이 숫자는 버퍼의 크기(바이트)보다 작거나 같아야 합니다.

[out, optional] LengthTransferred

Buffer에 복사된 실제 바이트 수를 수신하는 ULONG 변수에 대한 포인터입니다. 자세한 내용은 설명 부분을 참조하세요.

[in, optional] Overlapped

비동기 작업에 사용되는 OVERLAPPED 구조체에 대한 선택적 포인터입니다. 이 매개 변수를 지정하면 WinUsb_ReadPipe 반환하기 전에 작업이 완료될 때까지 동기적으로 기다리지 않고 즉시 반환됩니다. 작업이 완료되면 이벤트가 신호를 보냅니다.

반환 값

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

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

반환 코드	설명
ERROR_INVALID_HANDLE	호출자가 InterfaceHandle 매개 변수에서 NULL을 전달했습니다.
ERROR_IO_PENDING	겹치는 I/O 작업이 진행 중이지만 완료되지 않았습니다. 겹치는 작업을 즉시 완료할 수 없는 경우 함수는 FALSE 를 반환하고 GetLastError 함수는 백그라운드에서 작업이 실행 중임을 나타내는 ERROR_IO_PENDING 반환합니다. WinUsb_GetOverlappedResult 호출하여 작업의 성공 또는 실패를 검사.
ERROR_NOT_ENOUGH_MEMORY	작업을 수행할 메모리가 부족합니다.
ERROR_SEM_TIMEOUT	USB 스택의 WinUsb_ReadPipe 시작한 읽기 작업이 작업을 완료하기 전에 시간이 초과되었습니다.

설명

디바이스에서 반환된 데이터가 최대 전송 길이보다 큰 경우 WinUSB는 요청을 최대 전송 길이의 더 작은 요청으로 나누고 직렬로 제출합니다. 전송 길이가 엔드포인트의 최대 패킷 크기( WINUSB_PIPE_INFORMATION 구조체의 MaximumPacketSize 멤버를 통해 검색 가능)의 배수가 아닌 경우 WinUSB는 전송 크기를 MaximumPacketSize의 다음 배수로 증가합니다.

USB 패킷 크기는 읽기 요청에 대한 전송에 영향을 주지 않습니다. 디바이스가 클라이언트 버퍼에 대해 너무 큰 패킷으로 응답하는 경우 읽기 요청의 동작은 파이프에 설정된 정책 유형에 해당합니다. 파이프에 대한 정책 형식이 ALLOW_PARTIAL_READS 경우 WinUSB는 나머지 데이터를 다음 전송의 시작 부분에 추가합니다. ALLOW_PARTIAL_READS 설정되지 않으면 읽기 요청이 실패합니다. 정책 유형에 대한 자세한 내용은 파이프 정책 수정을 위한 WinUSB 함수를 참조하세요.

애플리케이션이 Overlapped 매개 변수(동기 작업)에서 NULL을 전달하는 경우 읽기 작업에서 출력 데이터가 생성되지 않는 경우에도 LengthTransferred가 NULL이 아닌지 확인해야 합니다.

Overlapped가 NULL(비동기 작업)이 아닌 경우 LengthTransferred를NULL로 설정할 수 있습니다. 겹치는 작업의 경우(LengthTransferred가 NULL이 아닌 값인 경우) WinUsb_ReadPipe 반환 후 LengthTransferred에서 받은 값은 겹치는 작업이 완료될 때까지 의미가 없습니다. 파이프에서 읽은 실제 바이트 수를 검색하려면 WinUsb_GetOverlappedResult 호출합니다.

엔드포인트에서 사용할 수 있는 데이터가 없는 경우(파이프가 비어 있음) 파이프에 데이터가 있을 때까지 WinUsb_ReadPipe 반환되지 않습니다. 오류 조건이 발생하거나 애플리케이션에서 지정한 시간 제한이 만료되면 WinUsb_ReadPipe 항상 FALSE를 반환합니다. 해당 반환 값의 실제 이유를 확인하려면 항상 GetLastError를 호출합니다. 예를 들어 이러한 경우 GetLastError 오류 값은 실제 이유를 나타냅니다.

애플리케이션이 파이프 정책에서 시간 제한 값을 지정하고 시간 제한이 만료되면 WinUsb_ReadPipe FALSE를 반환하고 GetLastError는 ERROR_SEM_TIMEOUT 반환합니다.
파이프에서 데이터를 읽는 동안 오류 조건이 발생하면 WinUsb_ReadPipe FALSE를 반환하고 GetLastError는 ERROR_GEN_FAILURE 반환합니다.