função WinUsb_GetOverlappedResult (winusb.h)

Artigo
08/27/2023

A função WinUsb_GetOverlappedResult recupera os resultados de uma operação sobreposta no arquivo especificado.

Sintaxe

BOOL WinUsb_GetOverlappedResult(
  [in]  WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]  LPOVERLAPPED            lpOverlapped,
  [out] LPDWORD                 lpNumberOfBytesTransferred,
  [in]  BOOL                    bWait
);

Parâmetros

[in] InterfaceHandle

Um identificador opaco para a primeira interface no dispositivo, que é retornado por WinUsb_Initialize.

[in] lpOverlapped

Um ponteiro para uma estrutura OVERLAPPED que foi especificada quando a operação sobreposta foi iniciada.

[out] lpNumberOfBytesTransferred

Um ponteiro para uma variável que recebe o número de bytes que foram realmente transferidos por uma operação de leitura ou gravação.

[in] bWait

Se esse parâmetro for TRUE, a função não retornará até que a operação seja concluída. Se esse parâmetro for FALSE e a operação ainda estiver pendente, a função retornará FALSE e a função GetLastError retornará ERROR_IO_INCOMPLETE.

Retornar valor

Se a função for bem-sucedida, o valor retornado será qualquer número diferente de zero. Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Essa função é como a rotina de API do Win32, GetOverlappedResult, com uma diferença, em vez de passar um identificador de arquivo retornado de CreateFile, o chamador passa um identificador de interface retornado de WinUsb_Initialize. O chamador pode usar qualquer rotina de API, se o identificador apropriado for passado. A função WinUsb_GetOverlappedResult extrai o identificador de arquivo do identificador de interface e chama GetOverlappedResult.

Os resultados relatados pela função WinUsb_GetOverlappedResult são aqueles da última operação sobreposta do identificador especificado à qual a estrutura OVERLAPPED especificada foi fornecida e para a qual os resultados da operação estavam pendentes. Uma operação pendente é indicada quando a função que iniciou a operação retorna FALSE e a rotina GetLastError retorna ERROR_IO_PENDING. Quando uma operação de E/S está pendente, a função que iniciou a operação redefine o membro hEvent da estrutura OVERLAPPED para o estado não atribuído. Em seguida, quando a operação pendente for concluída, o sistema definirá o objeto de evento como o estado sinalizado.

O chamador pode especificar que um objeto de evento é redefinido manualmente na estrutura OVERLAPPED . Se um objeto de evento de redefinição automática for usado, o identificador de evento não deverá ser especificado em nenhuma outra operação de espera no intervalo entre iniciar a operação sobreposta e a chamada para WinUsb_GetOverlappedResult. Por exemplo, o objeto de evento às vezes é especificado em uma das rotinas de espera para aguardar a conclusão da operação. Quando a rotina de espera retorna, o sistema define o estado de um evento de redefinição automática como não atribuído e uma chamada sucessiva para WinUsb_GetOverlappedResult com o parâmetro bWait definido como TRUE faz com que a função seja bloqueada indefinidamente.

Se o parâmetro bWait for TRUE, WinUsb_GetOverlappedResult determinará se a operação pendente foi concluída aguardando o objeto de evento estar no estado sinalizado.

Se o membro hEvent da estrutura OVERLAPPED for NULL, o sistema usará o estado do identificador de arquivo para sinalizar quando a operação tiver sido concluída. Não use identificadores de arquivo para essa finalidade. É melhor usar um objeto de evento devido à confusão que pode ocorrer quando várias operações sobrepostas simultâneas são executadas no mesmo arquivo. Nessa situação, você não pode saber qual operação fez com que o estado do objeto fosse sinalizado.