Função shutdown (winsock2.h)

Artigo
08/27/2023

A função de desligamento desabilita envios ou recebimentos em um soquete.

Sintaxe

int WSAAPI shutdown(
  [in] SOCKET s,
  [in] int    how
);

Parâmetros

[in] s

Um descritor que identifica um soquete.

[in] how

Um sinalizador que descreve quais tipos de operação não serão mais permitidos. Os valores possíveis para esse sinalizador são listados no arquivo de cabeçalho Winsock2.h .

Valor	Significado
SD_RECEIVE 0	Operações de recebimento de desligamento.
SD_SEND 1	Operações de envio de desligamento.
SD_BOTH 2	Desligar as operações de envio e recebimento.

Valor retornado

Se nenhum erro ocorrer, o desligamento retornará zero. Caso contrário, um valor de SOCKET_ERROR é retornado e um código de erro específico pode ser recuperado chamando WSAGetLastError.

Código do erro	Significado
WSAECONNABORTED	O circuito virtual foi encerrado por causa do tempo limite ou outra falha. O aplicativo deve fechar o soquete porque ele não pode ser mais usado. Esse erro se aplica apenas a um soquete orientado à conexão.
WSAECONNRESET	O circuito virtual foi redefinido pelo lado remoto executando um fechamento forçado ou por anulação. O aplicativo deve fechar o soquete porque ele não pode ser mais usado. Esse erro se aplica apenas a um soquete orientado à conexão.
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.
WSAEINVAL	O parâmetro how não é válido ou não é consistente com o tipo de soquete. Por exemplo, SD_SEND é usado com um tipo de soquete UNI_RECV.
WSAENETDOWN	O subsistema de rede falhou.
WSAENOTCONN	O soquete não está conectado. Esse erro se aplica apenas a um soquete orientado à conexão.
WSAENOTSOCK	Nota O descritor não é um soquete.
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.

Comentários

A função de desligamento é usada em todos os tipos de soquetes para desabilitar a recepção, a transmissão ou ambos.

Se o parâmetro how for SD_RECEIVE, as chamadas subsequentes para a função recv no soquete não serão permitidas. Isso não tem efeito nas camadas de protocolo inferiores. Para soquetes TCP, se ainda houver dados enfileirados no soquete aguardando para serem recebidos ou os dados chegarem posteriormente, a conexão será redefinida, pois os dados não poderão ser entregues ao usuário. Para soquetes UDP, os datagramas de entrada são aceitos e enfileirados. Em nenhum caso será gerado um pacote de erro ICMP.

Se o parâmetro how for SD_SEND, as chamadas subsequentes para a função de envio não serão permitidas. Para soquetes TCP, um FIN será enviado depois que todos os dados forem enviados e confirmados pelo receptor.

Definir como SD_BOTH desabilita os envios e os recebimentos, conforme descrito acima.

A função de desligamento não fecha o soquete. Todos os recursos anexados ao soquete não serão liberados até que closesocket seja invocado.

Para garantir que todos os dados sejam enviados e recebidos em um soquete conectado antes de serem fechados, um aplicativo deve usar o desligamento para fechar a conexão antes de chamar closesocket. Um método para aguardar a notificação de que o extremidade remoto enviou todos os seus dados e iniciou uma desconexão normal usa a função WSAEventSelect da seguinte maneira:

Chame WSAEventSelect para se registrar para FD_CLOSE notificação.
Chamar desligamento com how=SD_SEND.
Quando FD_CLOSE recebido, chame o recv ou WSARecv até que a função seja concluída com êxito e indique que zero bytes foram recebidos. Se SOCKET_ERROR for retornado, a desconexão normal não será possível.
Chame closesocket.

Outro método para aguardar a notificação de que o extremidade remoto enviou todos os seus dados e iniciou uma desconexão normal usa chamadas de recebimento sobrepostas:

Chamar desligamento com how=SD_SEND.
Chame recv ou WSARecv até que a função seja concluída com êxito e indique que zero bytes foram recebidos. Se SOCKET_ERROR for retornado, a desconexão normal não será possível.
Chame closesocket.

Nota A função de desligamento não bloqueia independentemente da configuração de SO_LINGER no soquete.

Para obter mais informações, consulte a seção sobre Desligamento Normal, Opções Persistentes e Fechamento de Soquete.

Depois que a função de desligamento é chamada para desabilitar o envio, o recebimento ou ambos, não há nenhum método para reabilitar o envio ou o recebimento da conexão de soquete existente.

Um aplicativo não deve depender de ser capaz de reutilizar um soquete depois de ser desligado. Em particular, um provedor do Windows Sockets não é necessário para dar suporte ao uso da conexão em um soquete que foi desligado.

Se um aplicativo quiser reutilizar um soquete, a função DisconnectEx deverá ser chamada com o parâmetro dwFlags definido como TF_REUSE_SOCKET para fechar uma conexão em um soquete e preparar o identificador de soquete para ser reutilizado. Quando a solicitação DisconnectEx for concluída, o identificador de soquete poderá ser passado para a função AcceptEx ou ConnectEx .

Se um aplicativo quiser reutilizar um soquete, as funções TransmitFile ou TransmitPackets poderão ser chamadas com o parâmetro dwFlags definido com TF_DISCONNECT e TF_REUSE_SOCKET desconectar depois que todos os dados forem enfileirados para transmissão e preparar o identificador de soquete a ser reutilizado. Quando a solicitação TransmitFile for concluída, o identificador de soquete poderá ser passado para a chamada de função usada anteriormente para estabelecer a conexão, como AcceptEx ou ConnectEx. Quando a função TransmitPackets for concluída, o identificador de soquete poderá ser passado para a função AcceptEx .

Nota A desconexão no nível do soquete está sujeita ao comportamento do transporte subjacente. Por exemplo, um soquete TCP pode estar sujeito ao estado de TIME_WAIT TCP, fazendo com que a chamada DisconnectEx, TransmitFile ou TransmitPackets seja atrasada.

Nota Ao emitir uma chamada winsock de bloqueio, como desligamento, winsock pode precisar esperar por um evento de rede antes que a chamada possa ser concluída. O Winsock executa uma espera alertável nessa situação, que pode ser interrompida por uma APC (chamada de procedimento assíncrona) agendada no mesmo thread. Emitir outra chamada winsock de bloqueio dentro de um APC que interrompeu uma chamada Winsock de bloqueio contínuo no mesmo thread levará a um comportamento indefinido e nunca deve ser tentado pelos clientes winsock.

Anotações para caixa eletrônico

Há problemas importantes associados ao teardown de conexão ao usar o ATM (Modo de Transferência Assíncrona) e o Windows Sockets 2. Para obter mais informações sobre essas considerações importantes, consulte a seção intitulada Notas para CAIXA ELETRÔNICO na seção Comentários da referência da função closesocket .

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posterior.

Requisitos


Cliente mínimo com suporte	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winsock2.h (inclua Winsock2.h, Webhost.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll