Função WSACancelAsyncRequest (winsock2.h)

Artigo
08/27/2023

A função WSACancelAsyncRequest cancela uma operação assíncrona incompleta.

Sintaxe

int WSAAPI WSACancelAsyncRequest(
  [in] HANDLE hAsyncTaskHandle
);

Parâmetros

[in] hAsyncTaskHandle

Identificador que especifica a operação assíncrona a ser cancelada.

Retornar valor

O valor retornado por WSACancelAsyncRequest será zero se a operação tiver sido cancelada com êxito. Caso contrário, o valor SOCKET_ERROR será retornado e um número de erro específico poderá ser recuperado chamando WSAGetLastError.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSAEINVAL	Indica que o identificador de tarefa assíncrona especificado era inválido.
WSAEINPROGRESS	Uma chamada de bloqueio do Windows Sockets 1.1 está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEALREADY	A rotina assíncrona que está sendo cancelada já foi concluída.

Nota Não está claro se o aplicativo pode distinguir útilmente entre WSAEINVAL e WSAEALREADY, pois em ambos os casos o erro indica que não há nenhuma operação assíncrona em andamento com o identificador indicado. (Exceção trivial: zero é sempre um identificador de tarefa assíncrona inválido.) A especificação windows sockets não prescreve como um provedor de Windows Sockets compatível deve distinguir entre os dois casos. Para obter a portabilidade máxima, um aplicativo do Windows Sockets deve tratar os dois erros como equivalentes.

Comentários

A função WSACancelAsyncRequest é usada para cancelar uma operação assíncrona iniciada por uma das funções WSAAsyncGetXByY , como WSAAsyncGetHostByName. A operação a ser cancelada é identificada pelo parâmetro hAsyncTaskHandle , que deve ser definido como o identificador de tarefa assíncrona, conforme retornado pela função WSAAsyncGetXByY iniciada.

Uma tentativa de cancelar uma operação WSAAsyncGetXByY assíncrona existente pode falhar com um código de erro WSAEALREADY por dois motivos. Primeiro, a operação original já foi concluída e o aplicativo lidou com a mensagem resultante. Em segundo lugar, a operação original já foi concluída, mas a mensagem resultante ainda está aguardando na fila da janela do aplicativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winsock2.h (inclua Winsock2.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll