option de socket SO_KEEPALIVE
L’option de socket SO_KEEPALIVE est conçue pour permettre à une application d’activer des paquets keep-alive pour une connexion de socket.
Pour interroger la status de cette option de socket, appelez la fonction getsockopt. Pour définir cette option, appelez la fonction setsockopt avec les paramètres suivants.
Valeur d’option de socket
La constante qui représente cette option de socket est 0x0008.
Syntaxe
int setsockopt(
(SOCKET) s, // descriptor identifying a socket
(int) SOL_SOCKET, // level
(int) SO_KEEPALIVE, // optname
(char *) optval, // input buffer,
(int) optlen // size of input buffer
);
Paramètres
-
s [in]
-
Descripteur identifiant le socket.
-
level [in]
-
Niveau auquel l’option est définie. Utilisez SOL_SOCKET pour cette opération.
-
optname [in]
-
Option de socket pour laquelle la valeur doit être définie. Utilisez SO_KEEPALIVE pour cette opération.
-
optval [out]
-
Pointeur vers la mémoire tampon contenant la valeur de l’option à définir. Ce paramètre doit pointer vers la mémoire tampon égale ou supérieure à la taille d’une valeur DWORD .
Cette valeur est traitée comme une valeur booléenne avec 0 utilisé pour indiquer FALSE (désactivé) et une valeur différente de zéro pour indiquer TRUE (activé).
-
optlen [in]
-
Taille, en octets, de la mémoire tampon optval . Cette taille doit être égale ou supérieure à la taille d’une valeur DWORD .
Valeur de retour
Si l’opération se termine correctement, setsockopt retourne zéro.
Si l’opération échoue, 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 |
|---|---|
| Un appel WSAStartup réussi doit se produire avant d’utiliser cette fonction. |
|
| Le sous-système réseau a échoué. |
|
| L’un des paramètres optval ou optlen pointe vers la mémoire qui n’est pas dans une partie valide de l’espace d’adressage utilisateur. Cette erreur est également retournée si la valeur pointée vers le paramètre optlen est inférieure à la taille d’une valeur DWORD . |
|
| Un appel bloquant Windows Sockets 1.1 est en cours ou le fournisseur de services traite toujours une fonction de rappel. |
|
| Le paramètre de niveau est inconnu ou non valide. Sur Windows Vista et versions ultérieures, cette erreur est également retournée si le socket était dans un état de transition. |
|
| L’option est inconnue ou non prise en charge par la famille de protocoles indiquée. Cette erreur est retournée si le descripteur de socket passé dans le paramètre s était pour un socket de datagramme. |
|
| Le descripteur n’est pas un socket. |
Notes
La fonction getsockopt appelée avec l’option de socket SO_KEEPALIVE permet à une application de récupérer l’état actuel de l’option keepalive, bien qu’il ne s’agisse pas d’une fonctionnalité normalement utilisée. Si une application doit activer les paquets keepalive sur un socket, elle appelle simplement la fonction setsockopt pour activer l’option.
La fonction setsockopt appelée avec l’option de socket SO_KEEPALIVE permet à une application d’activer des paquets keep-alive pour une connexion de socket. L’option SO_KEEPALIVE pour un socket est désactivée (définie sur FALSE) par défaut.
Lorsque cette option de socket est activée, la pile TCP envoie des paquets keep-alive quand aucun paquet de données ou d’accusé de réception n’a été reçu pour la connexion dans un intervalle. Pour plus d’informations sur l’option keep-alive, consultez la section 4.2.3.6 sur la configuration requise pour les hôtes Internet : couches de communication spécifiées dans la RFC 1122 disponible sur le site web de l’IETF. (Cette ressource ne peut être disponible qu’en anglais.)
L’option de socket SO_KEEPALIVE est valide uniquement pour les protocoles qui prennent en charge la notion de keep-alive (protocoles orientés connexion). Pour TCP, le délai d’expiration de conservation par défaut est de 2 heures et l’intervalle de conservation est de 1 seconde. Le nombre par défaut de sondes keep-alive varie en fonction de la version de Windows.
Le code de contrôle SIO_KEEPALIVE_VALS peut être utilisé pour activer ou désactiver keep-alive et ajuster le délai d’attente et l’intervalle pour une seule connexion. Si la fonctionnalité keep-alive est activée avec SO_KEEPALIVE, les paramètres TCP par défaut sont utilisés pour le délai d’attente et l’intervalle de conservation, sauf si ces valeurs ont été modifiées à l’aide de SIO_KEEPALIVE_VALS.
La valeur par défaut à l’échelle du système du délai d’attente de conservation est contrôlable via le paramètre de Registre KeepAliveTime , qui prend une valeur en millisecondes. La valeur par défaut à l’échelle du système de l’intervalle de conservation est contrôlable via le paramètre de Registre KeepAliveInterval , qui prend une valeur en millisecondes.
Sur Windows Vista et versions ultérieures, le nombre de sondes keep-alive (retransmissions de données) est défini sur 10 et ne peut pas être modifié.
Sur Windows Server 2003, Windows XP et Windows 2000, le paramètre par défaut pour le nombre de sondes de maintien en vie est 5. Le nombre de sondes keep-alive est contrôlable via les paramètres de Registre TcpMaxDataRetransmissions et PPTPTcpMaxDataRetransmissions . Le nombre de sondes keep-alive est défini sur la plus grande des deux valeurs de clé de Registre. Si ce nombre est 0, les sondes keep-alive ne sont pas envoyées. Si ce nombre est supérieur à 255, il est ajusté à 255.
Sur Windows Vista et versions ultérieures, l’option de socket SO_KEEPALIVE peut uniquement être définie à l’aide de la fonction setsockopt lorsque le socket est dans un état connu et non dans un état de transition. Pour TCP, l’option de socket SO_KEEPALIVE doit être définie avant que la fonction de connexion (connect, ConnectEx, WSAConnect, WSAConnectByList ou WSAConnectByName) soit appelée, soit une fois la demande de connexion terminée. Si la fonction de connexion a été appelée de manière asynchrone, cela nécessite d’attendre l’achèvement de la connexion avant d’essayer de définir l’option de socket SO_KEEPALIVE . Si une application tente de définir l’option de socket SO_KEEPALIVE lorsqu’une demande de connexion est toujours en cours, la fonction setsockopt échoue et retourne WSAEINVAL.
Sur Windows Server 2003, Windows XP et Windows 2000, l’option de socket SO_KEEPALIVE peut être définie à l’aide de la fonction setsockopt lorsque le socket est un état transitoire (une demande de connexion est toujours en cours) ainsi qu’un état connu.
Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge |
Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge |
Windows 2000 Server [applications de bureau uniquement] |
| En-tête |
|