WinUsb_WritePipe 함수(winusb.h)

아티클
03/04/2024

WinUsb_WritePipe 함수는 파이프에 데이터를 씁니다.

구문

BOOL WinUsb_WritePipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [in]            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입니다.

[in] Buffer

쓸 데이터를 포함하는 호출자가 할당한 버퍼입니다.

[in] BufferLength

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

[out, optional] LengthTransferred

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

[in, optional] Overlapped

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

반환 값

WinUsb_WritePipe 작업이 성공하면 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_WritePipe 시작한 쓰기 작업이 작업이 완료되기 전에 시간이 초과되었습니다.

설명

쓰기 요청을 만들려면 애플리케이션이 버퍼를 할당하고, 디바이스에 쓸 데이터로 채우고, WinUsb_WritePipe 호출하여 호스트 컨트롤러에 버퍼를 보내야 합니다.

RAW_IO 설정된 경우 버퍼 크기에 다음 제한이 적용됩니다.

버퍼 길이는 최대 엔드포인트 패킷 크기의 배수여야 합니다.
길이는 WinUsb_GetPipePolicy 검색한 MAXIMUM_TRANSFER_SIZE 값보다 작거나 같아야 합니다.

RAW_IO 파이프의 정책 유형으로 설정되지 않은 경우 버퍼 크기에 제한이 없습니다. 버퍼의 크기가 MAXIMUM_TRANSFER_SIZE 보고한 최대 전송 길이보다 큰 경우 WinUSB는 요청을 더 작은 요청으로 나누고 호스트 컨트롤러에 직렬로 제출합니다.

길이가 0인 데이터를 포함하는 쓰기 요청은 USB 스택 아래로 전달됩니다.

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

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