função WinUsb_ReadPipe (winusb.h)

Artigo
08/27/2023

A função WinUsb_ReadPipe lê dados do pipe especificado.

Sintaxe

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
);

Parâmetros

[in] InterfaceHandle

Um identificador opaco para a interface que contém o ponto de extremidade ao qual o pipe está associado.

Para ler dados do pipe associado a um ponto de extremidade na primeira interface, use o identificador retornado por WinUsb_Initialize. Para todas as outras interfaces, use o identificador para a interface de destino, recuperada por WinUsb_GetAssociatedInterface.

[in] PipeID

PipeID corresponde ao campo bEndpointAddress no descritor de ponto de extremidade. Para obter informações sobre o layout desse campo, consulte Tabela 9-13 em "Revisão de Especificação de Barramento Serial Universal 2.0" em Tecnologia USB. No campo bEndpointAddress , o Bit 7 indica a direção do ponto de extremidade: 0 para OUT; 1 para IN.

[out] Buffer

Um buffer alocado pelo chamador que recebe os dados lidos.

[in] BufferLength

O número máximo de bytes a serem lidos. Esse número deve ser menor ou igual ao tamanho, em bytes, de Buffer.

[out, optional] LengthTransferred

Um ponteiro para uma variável ULONG que recebe o número real de bytes que foram copiados para o Buffer. Para obter mais informações, consulte Comentários.

[in, optional] Overlapped

Um ponteiro opcional para uma estrutura OVERLAPPED usada para operações assíncronas. Se esse parâmetro for especificado, WinUsb_ReadPipe retornará imediatamente em vez de aguardar síncronamente para que a operação seja concluída antes de retornar. Um evento é sinalizado quando a operação é concluída.

Retornar valor

WinUsb_ReadPiperetornará TRUE se a operação for bem-sucedida. Caso contrário, essa função retornará FALSE e o chamador poderá recuperar o erro registrado chamando GetLastError.

GetLastError pode retornar o código de erro a seguir.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	O chamador passou NULL no parâmetro InterfaceHandle .
ERROR_IO_PENDING	Uma operação de E/S sobreposta está em andamento, mas não foi concluída. Se a operação sobreposta não puder ser concluída imediatamente, a função retornará FALSE e a função GetLastError retornará ERROR_IO_PENDING, indicando que a operação está sendo executada em segundo plano. Chame WinUsb_GetOverlappedResult para marcar o êxito ou a falha da operação.
ERROR_NOT_ENOUGH_MEMORY	Não há memória suficiente para executar a operação.
ERROR_SEM_TIMEOUT	A operação de leitura iniciada por WinUsb_ReadPipe na pilha USB atingiu o tempo limite antes que a operação pudesse ser concluída.

Comentários

Se os dados retornados pelo dispositivo forem maiores que um comprimento máximo de transferência, o WinUSB dividirá a solicitação em solicitações menores de comprimento máximo de transferência e os enviará serialmente. Se o comprimento de transferência não for um múltiplo do tamanho máximo do pacote do ponto de extremidade (recuperável por meio do membro MaximumPacketSize da estrutura WINUSB_PIPE_INFORMATION), o WinUSB aumentará o tamanho da transferência para o próximo múltiplo de MaximumPacketSize.

O tamanho do pacote USB não leva em conta a transferência de uma solicitação de leitura. Se o dispositivo responder com um pacote muito grande para o buffer do cliente, o comportamento da solicitação de leitura corresponderá ao tipo de política definida no pipe. Se o tipo de política do pipe for ALLOW_PARTIAL_READS, o WinUSB adicionará os dados restantes ao início da próxima transferência. Se ALLOW_PARTIAL_READS não estiver definido, a solicitação de leitura falhará. Para obter mais informações sobre tipos de política, consulte Funções do WinUSB para modificação de política de pipe.

Se um aplicativo passar NULL no parâmetro Overlapped (operação síncrona), o aplicativo deverá garantir que LengthTransferred não seja NULL, mesmo quando a operação de leitura não produzir dados de saída.

Se Sobreposto não for NULL (operação assíncrona), LengthTransferred poderá ser definido como NULL. Para uma operação sobreposta (e se LengthTransferred for um valor não NULL ), o valor recebido em LengthTransferred após WinUsb_ReadPipe retorna não terá sentido até que a operação sobreposta seja concluída. Para recuperar o número real de bytes lidos do pipe, chame WinUsb_GetOverlappedResult.

Quando nenhum dado está disponível no ponto de extremidade (o pipe está vazio), WinUsb_ReadPipe não retorna até que haja dados no pipe. Se ocorrer uma condição de erro ou o tempo limite especificado pelo aplicativo expirar, WinUsb_ReadPipe sempre retornará FALSE. Para determinar o motivo real desse valor retornado, sempre chame GetLastError. Por exemplo, nesses casos, o valor de erro GetLastError indica o motivo real:

Se o aplicativo tiver especificado um valor de tempo limite na política de pipe e esse tempo limite expirar, WinUsb_ReadPipe retornará FALSE e GetLastError retornará ERROR_SEM_TIMEOUT.
Se ocorrer uma condição de erro durante a leitura de dados do pipe, WinUsb_ReadPipe retornará FALSE e GetLastError retornará ERROR_GEN_FAILURE.