função WinUsb_WritePipe (winusb.h)

Artigo
03/13/2024

A função WinUsb_WritePipe grava dados em um pipe.

Sintaxe

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

Parâmetros

[in] InterfaceHandle

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

Para gravar em um 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 da Especificação do Barramento Serial Universal 2.0" em Tecnologia USB. No campo bEndpointAddress , Bit 7 indica a direção do ponto de extremidade: 0 para OUT; 1 para IN.

[in] Buffer

Um buffer alocado pelo chamador que contém os dados a serem gravados.

[in] BufferLength

O número de bytes a serem gravados. 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 gravados no pipe. Para obter mais informações, consulte Comentários.

[in, optional] Overlapped

Um ponteiro opcional para uma estrutura OVERLAPPED, que é usada para operações assíncronas. Se esse parâmetro for especificado, WinUsb_WritePipe retornará imediatamente e o evento será sinalizado quando a operação for concluída.

Retornar valor

WinUsb_WritePipe retornará 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	Indica que 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	Indica que não há memória suficiente para executar a operação.
ERROR_SEM_TIMEOUT	A operação de gravação iniciada por WinUsb_WritePipe na pilha USB atingiu o tempo limite antes que a operação pudesse ser concluída.

Comentários

Para criar uma solicitação de gravação, o aplicativo deve alocar um buffer, preenchê-lo com os dados que deseja gravar no dispositivo e enviar o buffer para o controlador host chamando WinUsb_WritePipe.

As seguintes restrições se aplicam ao tamanho do buffer se RAW_IO estiver definido:

O tamanho do buffer deve ser um múltiplo do tamanho máximo do pacote do ponto de extremidade.
O comprimento deve ser menor ou igual ao valor de MAXIMUM_TRANSFER_SIZE recuperado por WinUsb_GetPipePolicy.

Não haverá restrições sobre o tamanho do buffer se RAW_IO não estiver definido como o tipo de política do pipe. Se o tamanho do buffer for maior que o comprimento máximo de transferência relatado por MAXIMUM_TRANSFER_SIZE, o WinUSB dividirá a solicitação em solicitações menores e as enviará serialmente para o controlador host.

Uma solicitação de gravação que contém dados de comprimento zero é encaminhada para baixo na pilha USB.

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

Se Overlapped 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_WritePipe retorna não terá sentido até que a operação sobreposta seja concluída. Para recuperar o número real de bytes retornados, chame WinUsb_GetOverlappedResult.