fonction shutdown (winsock.h)

Article
08/27/2023

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

Syntaxe

int 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êter les opérations de réception.
SD_SEND 1	Arrêter 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 Windows Sockets 1.1 bloquant 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 ne sont pas autorisés. Cela n’a aucun effet sur les couches de protocole inférieures. Pour les sockets TCP, si des données sont toujours mises en file d’attente sur le socket en attente d’être reçues, ou si les 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 ne sont pas autorisés. 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.

La définition de SD_BOTH désactive à la fois 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 sont 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 la terminaison distante 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 d’appel avec how=SD_SEND.
Lorsque FD_CLOSE reçu, appelez recv ou WSARecv jusqu’à ce que la fonction se termine correctement 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 normale utilise des appels de réception qui se chevauchent :

Arrêt d’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 se bloque pas, quel que soit le paramètre SO_LINGER sur le socket.

Pour plus d’informations, consultez la section sur l’arrêt normal, les options persistantes et la fermeture de socket.

Une fois que la fonction d’arrêt est 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 s’appuyer sur la possibilité de réutiliser un socket après son arrêt. En particulier, un fournisseur Windows Sockets n’est pas nécessaire pour prendre en charge l’utilisation de se connecter 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 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 précédemment utilisé pour établir la connexion, tel que 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 qu’un arrêt, Winsock peut avoir besoin d’attendre un événement réseau avant que l’appel puisse se terminer. Winsock effectue une attente pouvant être alertée 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 interrompt 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 relatives au guichet automatique

Des problèmes importants sont associés à la désactivation de la connexion lors de l’utilisation du mode de transfert asynchrone (ATM) et de Windows Sockets 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 Windows Phone Store sur 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

Condition requise	Valeur
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	winsock.h (inclure Winsock2.h, Webhost.h)
Bibliothèque	Ws2_32.lib
DLL	Ws2_32.dll