Fonction de rappel LPWSPSETSOCKOPT (ws2spi.h)

Article
08/28/2023

La fonction LPWSPSetSockOpt définit une option de socket.

Syntaxe

LPWSPSETSOCKOPT Lpwspsetsockopt;

int Lpwspsetsockopt(
  [in]  SOCKET s,
  [in]  int level,
  [in]  int optname,
  [in]  const char *optval,
  [in]  int optlen,
  [out] LPINT lpErrno
)
{...}

Paramètres

[in] s

Descripteur qui identifie un socket.

[in] level

Niveau auquel l’option est définie ; les niveaux pris en charge incluent SOL_SOCKET. Pour plus d’informations, consultez Annexes Winsock.

[in] optname

Option de socket pour laquelle la valeur doit être définie.

[in] optval

Pointeur vers la mémoire tampon dans laquelle la valeur de l’option demandée est fournie.

[in] optlen

Taille, en octets, de la mémoire tampon optval .

[out] lpErrno

Pointeur vers le code d’erreur.

Valeur retournée

Si aucune erreur ne se produit, LPWSPSetSockOpt retourne zéro. Sinon, la valeur SOCKET_ERROR est retournée et un code d’erreur spécifique est disponible dans lpErrno.

Code d'erreur	Signification
WSAENETDOWN	Le sous-système réseau a échoué.
WSAEFAULT	L’optval n’est pas dans une partie valide de l’espace d’adressage du processus ou le paramètre optlen est trop petit.
WSAEINPROGRESS	La fonction est appelée lorsqu’un rappel est en cours.
WSAEINPROGRESS	Le blocage de l’appel Windows Sockets est en cours ou le fournisseur de services traite toujours une fonction de rappel.
WSAEINVAL	Le niveau n’est pas valide ou les informations dans optval ne sont pas valides.
WSAENETRESET	La connexion a été interrompue, car l'activité persistante a détecté un échec en cours d'opération.
WSAENOPROTOOPT	L’option est inconnue ou non prise en charge pour le fournisseur spécifié.
WSAENOTCONN	La connexion a été réinitialisée lorsque SO_KEEPALIVE est défini.
WSAENOTSOCK	Le descripteur n’est pas un socket.

Remarques

La fonction LPWSPSetSockOpt définit la valeur actuelle d’une option de socket associée à un socket de n’importe quel type, dans n’importe quel état. Bien que les options puissent exister à plusieurs niveaux de protocole, elles sont toujours présentes au niveau supérieur du socket. Les options affectent les opérations de socket, par exemple si des messages de diffusion peuvent être envoyés sur le socket.

Il existe deux types d’options de socket : les options booléennes qui activent ou désactivent une fonctionnalité ou un comportement, et les options qui nécessitent une valeur ou une structure entière. Pour activer une option booléenne, optval pointe vers un entier différent de zéro. Pour désactiver l’option, optval pointe vers un entier égal à zéro. Le paramètre optlen doit être égal à sizeof (int) pour les options booléennes. Pour les autres options, optval pointe vers un entier ou une structure qui contient la valeur souhaitée pour l’option, et optlen est la longueur de l’entier ou de la structure.

Pour plus d’informations sur les options de socket, consultez Options de socket.

level = SOL_SOCKET

Valeur	Type	Signification
SO_BROADCAST	BOOL	Active la transmission et la réception des messages de diffusion sur le socket.
SO_DEBUG	BOOL	Enregistre les informations de débogage.
SO_DONTLINGER	BOOL	Réservé.
SO_DONTROUTE	BOOL	Routage désactivé : envoyer directement à une interface. La définition de cette option de socket réussit, mais est ignorée sur les sockets AF_INET ; échoue sur AF_INET6 sockets avec WSAENOPROTOOPT . Cette option n’est pas prise en charge sur les sockets ATM (génère une erreur).
SO_GROUP_PRIORITY	int	Réservé.
SO_KEEPALIVE	BOOL	Envoie des keep-alives. Non pris en charge sur les sockets ATM (génère une erreur).
SO_LINGER	struct linger	Reste à la fermeture si des données non contenues sont présentes.
SO_OOBINLINE	BOOL	Reçoit des données OOB dans le flux de données normal.
SO_RCVBUF	int	Spécifie la quantité totale d'espace de la mémoire tampon réservée aux réceptions par socket. Cela n’est pas lié à SO_MAX_MSG_SIZE et ne correspond pas nécessairement à la taille de la fenêtre de réception TCP.
SO_REUSEADDR	BOOL	Autorise la liaison du socket à une adresse déjà utilisée. (Voir Bind.) Non applicable sur les sockets ATM.
SO_SNDBUF	int	Spécifie la quantité totale d'espace de la mémoire tampon réservée aux envois par socket. Cela n’est pas lié à SO_MAX_MSG_SIZE et ne correspond pas nécessairement à la taille d’une fenêtre d’envoi TCP.
PVD_CONFIG	Dépendant du fournisseur de services	Cet objet stocke les informations de configuration du fournisseur de services associé aux sockets. Le format exact de cette structure de données est spécifique au fournisseur de services.

L’appel de LPWSPGetSockopt avec une option non prise en charge entraîne un code d’erreur WSAENOPROTOOPT retourné dans lpErrno.

SO_DEBUG

Les fournisseurs de services Windows Sockets sont encouragés, mais pas obligatoires, à fournir des informations de débogage de sortie si l’option SO_DEBUG est définie par un client SPI Windows Sockets. Le mécanisme permettant de générer les informations de débogage et le format dépassent le cadre de cette spécification.

SO_GROUP_PRIORITY

Réservé.

SO_KEEPALIVE

Un client SPI Windows Sockets peut demander à un fournisseur TCP/IP d’activer l’utilisation de paquets keep-alive sur les connexions TCP en activant l’option de socket SO_KEEPALIVE . Un fournisseur Windows Sockets n’a pas besoin de prendre en charge l’utilisation de keep-alives : si c’est le cas, la sémantique précise est spécifique à l’implémentation, mais doit être conforme à la section 4.2.3.6 de la RFC 1122 : Configuration requise pour les hôtes Internet — Couches de communication. (Cette ressource ne peut être disponible qu’en anglais.) Si une connexion est supprimée à la suite d’une opération keep-alive, le code d’erreur WSAENETRESET est retourné à tous les appels en cours sur le socket, et tous les appels suivants échouent avec WSAENOTCONN .

SO_LINGER

SO_LINGER contrôle l’action effectuée lorsque des données non entrées sont mises en file d’attente sur un socket et qu’un LPWSPCloseSocket est effectué. Consultez LPWSPCloseSocket pour obtenir une description de la façon dont les paramètres de SO_LINGER affectent la sémantique de LPWSPCloseSocket. Le client SPI Windows Sockets définit le comportement souhaité en créant une structure LINGER , pointée par le paramètre optval , avec les éléments suivants.

struct linger {
  u_short l_onoff;
  u_short l_linger;
}

Pour activer SO_LINGER, un client SPI Windows Sockets doit définir l_onoff sur une valeur différente de zéro, définir l_linger sur zéro ou le délai d’attente souhaité, en secondes, et appeler LPWSPSetSockOpt. Pour activer SO_DONTLINGER, c’est-à-dire désactiver SO_LINGER, l_onoff doit être défini sur zéro et LPWSPSetSockOpt doit être appelé. N’oubliez pas que l’activation de SO_LINGER avec un délai d’attente différent de zéro sur un socket non bloquant n’est pas recommandée. Pour plus d’informations, consultez LPWSPCloseSocket.

L’activation de SO_LINGER désactive également SO_DONTLINGER, et vice versa. N’oubliez pas que si SO_DONTLINGER est désactivé (autrement dit, SO_LINGER est activé), aucune valeur de délai d’attente n’est spécifiée. Dans ce cas, le délai d’attente utilisé dépend de l’implémentation. Si un délai d’attente précédent a été établi pour un socket (en activant SO_LINGER), cette valeur de délai d’attente doit être rétablie par le fournisseur de services.

SO_REUSEADDR

Par défaut, un socket ne peut pas être lié (pour plus d’informations, consultez LPWSPBind) à une adresse locale déjà utilisée. Toutefois, à l’occasion, il peut être souhaitable de réutiliser une adresse de cette façon. Étant donné que chaque connexion est identifiée de manière unique par la combinaison d’adresses locales et distantes, il n’y a aucun problème avec le fait d’avoir deux sockets liés à la même adresse locale tant que les adresses distantes sont différentes. Pour informer le fournisseur Windows Sockets qu’un LPWSPBind sur un socket doit être autorisé à être lié à une adresse locale déjà utilisée par un autre socket, le client SPI Windows Sockets doit définir l’option de socket SO_REUSEADDR pour le socket avant d’émettre le LPWSPBind. N’oubliez pas que l’option n’est interprétée qu’au moment de LPWSPBind : il est donc inutile, mais inoffensif, de définir l’option sur un socket qui ne doit pas être lié à une adresse existante, et la définition ou la réinitialisation de l’option après le LPWSPBind n’a aucun effet sur ce socket ou sur tout autre socket.

SO_SNDBUF

Lorsqu’une implémentation Windows Sockets prend en charge les options SO_RCVBUF et SO_SNDBUF , un client SPI Windows Sockets peut demander différentes tailles de mémoire tampon (plus ou moins grande). L’appel peut réussir même si le fournisseur de services n’a pas mis à disposition la totalité du montant demandé. Un client SPI Windows Sockets doit appeler LPWSPGetSockopt avec la même option pour vérifier la taille de mémoire tampon réellement fournie.

PVD_CONFIG

Cet objet stocke les informations de configuration du fournisseur de services associé aux sockets. Le format exact de cette structure de données est spécifique au fournisseur de services.

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	ws2spi.h