code de contrôle SIO_KEEPALIVE_VALS

Article
06/13/2023

Description

Le code de contrôle SIO_KEEPALIVE_VALS active ou désactive le paramètre par connexion de l’option tcp keep-alive qui spécifie le délai d’expiration et l’intervalle tcp keep-alive.

Pour effectuer cette opération, appelez la fonction WSAIoctl ou WSPIoctl avec les paramètres suivants.

int WSAIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,              // descriptor identifying a socket
  SIO_KEEPALIVE_VALS,                  // dwIoControlCode
  (LPVOID) lpvInBuffer,    // pointer to tcp_keepalive struct
  (DWORD) cbInBuffer,      // length of input buffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Paramètres

s

Descripteur identifiant un socket.

dwIoControlCode

Code de contrôle pour l’opération. Utilisez SIO_KEEPALIVE_VALS pour cette opération.

lpvInBuffer

Pointeur vers la mémoire tampon d’entrée. Ce paramètre doit pointer vers une structure tcp_keepalive .

cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée. Ce paramètre doit être supérieur ou égal à la taille de la structure tcp_keepalive pointée par le paramètre lpvInBuffer .

lpvOutBuffer

Pointeur vers la mémoire tampon de sortie. Ce paramètre n’est pas utilisé pour cette opération.

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie. Ce paramètre doit être défini sur zéro.

lpcbBytesReturned

Pointeur vers une variable qui reçoit la taille, en octets, des données stockées dans la mémoire tampon de sortie. Ce paramètre retourné pointe vers une valeur DWORD de zéro pour cette opération, car il n’y a pas de sortie.

lpvOverlapped

Pointeur vers une structure WSAOVERLAPPED .

Si le socket s a été créé sans l’attribut superposé, le paramètre lpOverlapped est ignoré.

Si s a été ouvert avec l’attribut qui se chevauche et que le paramètre lpOverlapped n’a pas la valeur NULL, l’opération est effectuée en tant qu’opération (asynchrone) qui se chevauche. Dans ce cas, le paramètre lpOverlapped doit pointer vers une structure WSAOVERLAPPED valide.

Pour les opérations qui se chevauchent, la fonction WSAIoctl ou WSPIoctl retourne immédiatement, et la méthode d’achèvement appropriée est signalée une fois l’opération terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou qu’une erreur se produit.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée (ignorée pour les sockets qui ne se chevauchent pas).

lpThreadId

Pointeur vers une structure WSATHREADID à utiliser par le fournisseur dans un appel ultérieur à WPUQueueApc. Le fournisseur doit stocker la structure WSATHREADID référencée (pas le pointeur vers le même) jusqu’à ce que la fonction WPUQueueApc soit retournée.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

lpErrno

Pointeur vers le code d’erreur.

Note Ce paramètre s’applique uniquement à la fonction WSPIoctl .

Valeur retournée

Si l’opération se termine correctement, la fonction WSAIoctl ou WSPIoctl retourne zéro.

Si l’opération échoue ou est en attente, la fonction WSAIoctl ou WSPIoctl retourne SOCKET_ERROR. Pour obtenir des informations d’erreur étendues, appelez WSAGetLastError.

Code d'erreur	Signification
WSA_IO_PENDING	Une opération superposée a été lancée avec succès et l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	Une opération qui se chevauche a été annulée en raison de la fermeture du socket ou de l’exécution de la commande IOCTL SIO_FLUSH .
WSAEFAULT	Le paramètre lpOverlapped ou lpCompletionRoutine n’est pas totalement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINPROGRESS	La fonction est appelée lorsqu’un rappel est en cours.
WSAEINTR	Une opération de blocage a été interrompue.
WSAEINVAL	Le paramètre dwIoControlCode n’est pas une commande valide, ou un paramètre d’entrée spécifié n’est pas acceptable, ou la commande n’est pas applicable au type de socket spécifié.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOPROTOOPT	L’option socket n’est pas prise en charge sur le protocole spécifié. Cette erreur est retournée pour un socket de datagramme.
WSAENOTSOCK	Le descripteur s n’est pas un socket.
WSAEOPNOTSUPP	La commande IOCTL spécifiée n’est pas prise en charge. Cette erreur est retournée si le SIO_KEEPALIVE_VALS IOCTL n’est pas pris en charge par le fournisseur de transport.

Notes

La SIO_KEEPALIVE_VALS IOCTL est prise en charge sur Windows 2000 et versions ultérieures du système d’exploitation.

Le code de contrôle SIO_KEEPALIVE_VALS active ou désactive le paramètre par connexion de l’option tcp keep-alive qui spécifie le délai d’expiration et l’intervalle tcp keep-alive utilisés pour les paquets tcp keep-alive. 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.)

Le paramètre lpvInBuffer doit pointer vers une structure tcp_keepalive définie dans le fichier d’en-tête Mstcpip.h . Cette structure est définie comme suit :

/* Argument structure for SIO_KEEPALIVE_VALS */
struct tcp_keepalive {
    u_long  onoff;
    u_long  keepalivetime;
    u_long  keepaliveinterval;
};

La valeur spécifiée dans le membre onoff détermine si tcp keep-alive est activé ou désactivé. Si le membre onoff est défini sur une valeur différente de zéro, tcp keep-alive est activé et les autres membres de la structure sont utilisés. Le membre keepalivetime spécifie le délai d’expiration, en millisecondes, sans activité jusqu’à l’envoi du premier paquet keep-alive. Le membre keepaliveinterval spécifie l’intervalle, en millisecondes, entre l’envoi des paquets keep-alive successifs si aucun accusé de réception n’est reçu.

L’option SO_KEEPALIVE, qui est l’une des options de socket SOL_SOCKET, peut également être utilisée pour activer ou désactiver le maintien de tcp sur une connexion, ainsi que pour interroger l’état actuel de cette option. Pour savoir si tcp keep-alive est activé sur un socket, la fonction getsockopt peut être appelée avec l’option SO_KEEPALIVE . Pour activer ou désactiver tcp keep-alive, la fonction setsockopt peut être appelée avec l’option SO_KEEPALIVE . Si tcp keep-alive est activé avec SO_KEEPALIVE, les paramètres TCP par défaut sont utilisés pour le délai d’expiration 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’expiration keep-alive est contrôlable via le paramètre de Registre KeepAliveTime qui prend une valeur en millisecondes. Si la clé n’est pas définie, le délai d’expiration par défaut est de 2 heures. La valeur par défaut à l’échelle du système de l’intervalle keep-alive est contrôlable via le paramètre de Registre KeepAliveInterval qui prend une valeur en millisecondes. Si la clé n’est pas définie, l’intervalle de conservation par défaut est de 1 seconde.

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 keep-alive 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.