LPOVERLAPPED_COMPLETION_ROUTINE função de retorno de chamada (minwinbase.h)

Artigo
03/05/2024

Uma função de retorno de chamada definida pelo aplicativo usada com as funções ReadFileEx e WriteFileEx. Ele é chamado quando a operação assíncrona de entrada e saída (E/S) é concluída ou cancelada e o thread de chamada está em um estado alertável (usando a função SleepEx, MsgWaitForMultipleObjectsEx, WaitForSingleObjectEx ou WaitForMultipleObjectsEx com o parâmetro fAlertable definido como TRUE).

O tipo LPOVERLAPPED_COMPLETION_ROUTINE define um ponteiro para essa função de retorno de chamada. FileIOCompletionRoutine é um espaço reservado para o nome da função definida pelo aplicativo.

Sintaxe

LPOVERLAPPED_COMPLETION_ROUTINE LpoverlappedCompletionRoutine;

void LpoverlappedCompletionRoutine(
  [in]      DWORD dwErrorCode,
  [in]      DWORD dwNumberOfBytesTransfered,
  [in, out] LPOVERLAPPED lpOverlapped
)
{...}

Parâmetros

[in] dwErrorCode

O status de conclusão de E/S. Esse parâmetro pode ser um dos códigos de erro do sistema.

[in] dwNumberOfBytesTransfered

O número de bytes transferidos. Se ocorrer um erro, esse parâmetro será zero.

[in, out] lpOverlapped

Um ponteiro para a estrutura OVERLAPPED especificada pela função de E/S assíncrona.

O sistema não usa a estrutura OVERLAPPED depois que a rotina de conclusão é chamada, portanto, a rotina de conclusão pode desalocar a memória usada pela estrutura sobreposta.

Retornar valor

Nenhum

Comentários

O valor retornado de uma operação assíncrona será 0 (ERROR_SUCCESS) se a operação for concluída com êxito ou se a operação for concluída com um aviso. Para determinar se uma operação de E/S foi concluída com êxito, marcar que dwErrorCode é 0, chame GetOverlappedResult e chame GetLastError. Por exemplo, se o buffer não for grande o suficiente para receber todos os dados de uma chamada para ReadFileEx, dwErrorCode será definido como 0, GetOverlappedResult falhará e GetLastError retornará ERROR_MORE_DATA.

O retorno dessa função permite que outra rotina de conclusão de E/S pendente seja chamada. Todas as rotinas de conclusão em espera são chamadas antes que a espera do thread alertável seja concluída com um código de retorno de WAIT_IO_COMPLETION. O sistema pode chamar as rotinas de conclusão em espera em qualquer ordem. Eles podem ou não ser chamados na ordem em que as funções de E/S são concluídas.

Sempre que o sistema chama uma rotina de conclusão, ele usa parte da pilha do aplicativo. Se a rotina de conclusão fizer E/S assíncrona adicional e esperas alertáveis, a pilha poderá crescer.

Para obter mais informações, consulte Chamadas de procedimento assíncrono.

Exemplos

Para obter um código de exemplo, consulte Servidor de pipe nomeado usando rotinas de conclusão.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	minwinbase.h (inclua Windows.h)