Função WSACancelAsyncRequest (winsock.h)

Artigo
03/13/2024

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

Sintaxe

int 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íncrono especificado era inválido.
WSAEINPROGRESS	Uma chamada do Windows Sockets 1.1 de bloqueio 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íncrono inválido.) A especificação do Windows Sockets não prescreve como um provedor de Soquetes do Windows 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íncrono conforme retornado pela função WSAAsyncGetXByY inicial.

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	winsock.h (inclua Winsock2.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll