fonction d’arrêt (winsock2.h)

Article
08/27/2023

La fonction d’arrêt désactive les envois ou les réceptions sur un socket.

Syntaxe

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

Paramètres

[in] s

Descripteur identifiant un socket.

[in] how

Indicateur qui décrit les types d’opérations qui ne seront plus autorisés. Les valeurs possibles pour cet indicateur sont répertoriées dans le fichier d’en-tête Winsock2.h .

Valeur	Signification
SD_RECEIVE 0	Arrêtez les opérations de réception.
SD_SEND 1	Arrêtez les opérations d’envoi.
SD_BOTH 2	Arrêtez les opérations d’envoi et de réception.

Valeur retournée

Si aucune erreur ne se produit, l’arrêt retourne zéro. Sinon, une valeur de SOCKET_ERROR est retournée et un code d’erreur spécifique peut être récupéré en appelant WSAGetLastError.

Code d'erreur	Signification
WSAECONNABORTED	Le circuit virtuel a été interrompu en raison d'un délai d'attente ou d'un autre échec. L’application doit fermer le socket, car il n’est plus utilisable. Cette erreur s’applique uniquement à un socket orienté connexion.
WSAECONNRESET	Le circuit virtuel a été rétabli par la partie distante exécutant une fermeture brutale ou infructueuse. L’application doit fermer le socket, car il n’est plus utilisable. Cette erreur s’applique uniquement à un socket orienté connexion.
WSAEINPROGRESS	Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINVAL	Le paramètre how n’est pas valide ou n’est pas cohérent avec le type de socket. Par exemple, SD_SEND est utilisé avec un type de socket UNI_RECV.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOTCONN	Le socket n'est pas connecté. Cette erreur s’applique uniquement à un socket orienté connexion.
WSAENOTSOCK	Note Le descripteur n’est pas un socket.
WSANOTINITIALISED	Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction.

Remarques

La fonction d’arrêt est utilisée sur tous les types de sockets pour désactiver la réception, la transmission ou les deux.

Si le paramètre how est SD_RECEIVE, les appels suivants à la fonction recv sur le socket seront interdits. Cela n’a aucun effet sur les couches de protocole inférieures. Pour les sockets TCP, si des données sont toujours en file d’attente sur le socket en attente d’être reçues ou si des données arrivent par la suite, la connexion est réinitialisée, car les données ne peuvent pas être remises à l’utilisateur. Pour les sockets UDP, les datagrammes entrants sont acceptés et mis en file d’attente. En aucun cas, un paquet d’erreur ICMP ne sera généré.

Si le paramètre how est SD_SEND, les appels suivants à la fonction d’envoi sont interdits. Pour les sockets TCP, une fin est envoyée une fois que toutes les données ont été envoyées et reconnues par le récepteur.

Le fait de définir comment SD_BOTH désactive les envois et les réceptions, comme décrit ci-dessus.

La fonction d’arrêt ne ferme pas le socket. Les ressources attachées au socket ne seront pas libérées tant que closesocket n’est pas appelé.

Pour garantir que toutes les données sont envoyées et reçues sur un socket connecté avant sa fermeture, une application doit utiliser l’arrêt pour fermer la connexion avant d’appeler closesocket. Une méthode pour attendre la notification indiquant que le point de terminaison distant a envoyé toutes ses données et lancé une déconnexion normale utilise la fonction WSAEventSelect comme suit :

Appelez WSAEventSelect pour vous inscrire à FD_CLOSE notification.
Arrêt de l’appel avec how=SD_SEND.
Lorsque FD_CLOSE reçu, appelez la recv ou WSARecv jusqu’à ce que la fonction se termine avec succès et indique que zéro octet a été reçu. Si SOCKET_ERROR est retourné, la déconnexion normale n’est pas possible.
Appelez closesocket.

Une autre méthode pour attendre la notification indiquant que la terminaison distante a envoyé toutes ses données et lancé une déconnexion avec grâce utilise des appels de réception qui se chevauchent :

Arrêt de l’appel avec how=SD_SEND.
Appelez recv ou WSARecv jusqu’à ce que la fonction se termine avec succès et indique que zéro octet a été reçu. Si SOCKET_ERROR est retourné, la déconnexion normale n’est pas possible.
Appelez closesocket.

Note La fonction d’arrêt ne bloque pas, quel que soit le paramètre SO_LINGER sur le socket.

Pour plus d’informations, consultez la section sur l’arrêt avec grâce, les options Linger et la fermeture du socket.

Une fois la fonction d’arrêt appelée pour désactiver l’envoi, la réception ou les deux, il n’existe aucune méthode permettant de réactiver l’envoi ou la réception pour la connexion de socket existante.

Une application ne doit pas compter sur la possibilité de réutiliser un socket après son arrêt. En particulier, un fournisseur de sockets Windows n’est pas nécessaire pour prendre en charge l’utilisation de la connexion sur un socket qui a été arrêté.

Si une application souhaite réutiliser un socket, la fonction DisconnectEx doit être appelée avec le paramètre dwFlags défini sur TF_REUSE_SOCKET pour fermer une connexion sur un socket et préparer le handle de socket à réutiliser. Une fois la requête DisconnectEx terminée, le handle de socket peut être passé à la fonction AcceptEx ou ConnectEx .

Si une application souhaite réutiliser un socket, les fonctions TransmitFile ou TransmitPackets peuvent être appelées avec le paramètre dwFlags défini avec TF_DISCONNECT et TF_REUSE_SOCKET se déconnecter une fois que toutes les données ont été mises en file d’attente pour la transmission et préparer le handle de socket à réutiliser. Une fois la requête TransmitFile terminée, le handle de socket peut être passé à l’appel de fonction utilisé précédemment pour établir la connexion, par exemple AcceptEx ou ConnectEx. Une fois la fonction TransmitPackets terminée, le handle de socket peut être passé à la fonction AcceptEx .

Note La déconnexion au niveau du socket est soumise au comportement du transport sous-jacent. Par exemple, un socket TCP peut être soumis à l’état de TIME_WAIT TCP, ce qui entraîne le retard de l’appel DisconnectEx, TransmitFile ou TransmitPackets .

Note Lors de l’émission d’un appel Winsock bloquant tel que l’arrêt, Winsock peut avoir besoin d’attendre qu’un événement réseau se termine. Winsock effectue une attente alertable dans cette situation, qui peut être interrompue par un appel de procédure asynchrone (APC) planifié sur le même thread. L’émission d’un autre appel Winsock bloquant à l’intérieur d’un APC qui a interrompu un appel Winsock bloquant en cours sur le même thread entraîne un comportement non défini et ne doit jamais être tenté par les clients Winsock.

Remarques pour ATM

Il existe d’importants problèmes associés à la désactivation de la connexion lors de l’utilisation du mode de transfert asynchrone (ATM) et des sockets Windows 2. Pour plus d’informations sur ces considérations importantes, consultez la section intitulée Notes pour ATM dans la section Remarques de la référence de la fonction closesocket .

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise


Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winsock2.h (inclure Winsock2.h, Webhost.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll