Code de contrôle SIO_IDEAL_SEND_BACKLOG_CHANGE

Article
10/16/2023

Description

Le code de contrôle SIO_IDEAL_SEND_BACKLOG_CHANGE avertit une application lorsque la valeur ISB (Ideal Send Backlog) change pour la connexion.

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_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  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_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  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 de l’opération. Utilisez SIO_IDEAL_SEND_BACKLOG_CHANGE pour cette opération.

lpvInBuffer

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

cbInBuffer

Taille, en octets, de la mémoire tampon d’entrée. Ce paramètre n’est pas utilisé pour cette opération.

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 superposé et que le paramètre lpOverlapped n’est pas NULL, l’opération est effectuée en tant qu’opération qui se chevauche (asynchrone). Dans ce cas, le paramètre lpOverlapped doit pointer vers une structure WSAOVERLAPPED valide.

Pour les opérations superposées, la fonction WSAIoctl ou WSPIoctl retourne immédiatement et la méthode d’achèvement appropriée est signalée lorsque l’opération a été terminée. Sinon, la fonction n’est pas retournée tant que l’opération n’est pas terminée ou si une erreur se produit.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée lorsque l’opération a été 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 (et non le pointeur vers cette structure) jusqu’au retour de la fonction WPUQueueApc.

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étaillées sur l’erreur, 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 superposée 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é. Cette erreur est retournée si le paramètre cbOutBuffer n’est pas égal à zéro.
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOPROTOOPT	L’option de socket n’est pas prise en charge sur le protocole spécifié.
WSAENOTCONN	Le socket s n’est pas connecté.
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 l’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE n’est pas prise en charge par le fournisseur de transport. Cette erreur est également retournée lorsqu’une tentative d’utilisation de l’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE est effectuée sur un socket de datagramme.

Notes

L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE est prise en charge sur Windows Server 2008, Windows Vista avec Service Pack 1 (SP1) et les versions ultérieures du système d’exploitation.

Lors de l’envoi de données via une connexion TCP à l’aide de sockets Windows, il est important de conserver une quantité suffisante de données en suspens (envoyées, mais pas encore reconnues) dans TCP afin d’atteindre le débit le plus élevé. La valeur idéale pour la quantité de données en suspens afin d’obtenir le meilleur débit pour la connexion TCP est appelée taille idéale de backlog d’envoi (ideal send backlog, ou ISB). La valeur ISB est une fonction du produit de délai de bande passante de la connexion TCP et de la fenêtre de réception annoncée du destinataire (et en partie la quantité de congestion dans le réseau).

La valeur ISB par connexion est disponible à partir de l’implémentation du protocole TCP dans Windows Server 2008, Windows Vista avec SP1 et versions ultérieures du système d’exploitation. L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE peut être utilisée par une application pour obtenir une notification lorsque la valeur ISB change dynamiquement pour une connexion.

Sur Windows Server 2008, Windows Vista avec SP1 et les versions ultérieures du système d’exploitation, les IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE et SIO_IDEAL_SEND_BACKLOG_QUERY sont prises en charge sur les sockets orientés vers le flux qui sont dans un état connecté.

La plage de la valeur ISB pour une connexion TCP peut théoriquement varier de 0 à un maximum de 16 mégaoctets.

Consultez la page de référence de l’IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY pour une utilisation classique du mécanisme ISB pour obtenir un meilleur débit sur les connexions de produits à bande passante élevée.

L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE est autorisée uniquement sur un socket de flux qui est dans l’état connecté. Sinon, la fonction WSAIoctl ou WSPIoctl échoue avec WSAENOTCONN.

L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE n’utilise aucune mémoire tampon d’entrée ou de sortie et met en attente ou bloque jusqu’à ce qu’une modification ISB se produise sur la connexion sous-jacente. Lorsque cette IOCTL est terminée, une application Winsock peut utiliser l’IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY pour récupérer la nouvelle valeur ISB sur la connexion.

L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE ne prend pas en charge le mode non bloquant. Une application est autorisée à émettre cette IOCTL sur un socket non bloquant, mais l’IOCTL sera simplement bloquée ou en attente jusqu’à ce que la valeur de l’ISB change.

Si les paramètres lpOverlapped et lpCompletionRoutine sont NULL, le socket de cette fonction est traité comme un socket non superposé. Pour un socket non superposé, les paramètres lpOverlapped et lpCompletionRoutine sont ignorés, sauf que la fonction peut bloquer si le socket s est en mode blocage. Si le socket s est en mode non bloquant, cette fonction est toujours bloquée, car cette IOCTL particulière ne prend pas en charge le mode non bloquant.

Pour les sockets superposés, les opérations qui ne peuvent pas être terminées immédiatement seront lancées et l’achèvement sera indiqué ultérieurement.

Toute IOCTL peut bloquer indéfiniment, en fonction de l’implémentation du fournisseur de services. Si l’application ne peut pas tolérer le blocage dans un appel de fonction WSAIoctl ou WSPIoctl, les E/S superposées sont recommandées pour les IOCTL qui sont particulièrement susceptibles de bloquer.

L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE fournit une notification et est censée bloquer ou mettre en attente jusqu’à ce que la valeur ISB change. Elle serait donc généralement appelée de façon asynchrone avec le paramètre lpOverlapped défini sur une structure WSAOVERLAPPED valide.

L’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE peut échouer avec WSAEINTR ou WSA_OPERATION_ABORTED dans les cas suivants :

La connexion TCP est correctement déconnectée dans le sens d’envoi. Cela peut se produire à la suite d’un appel à la fonction d’arrêt avec le paramètre défini sur SD_SEND, un appel à la fonction DisconnectEx ou un appel à la fonction TransmitFile ou TransmitPackets avec le paramètre dwFlags défini sur TF_DISCONNECT ou TF_REUSE.
La connexion TCP a été réinitialisée ou abandonnée.
L’application émet une IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE lorsqu’il existe déjà une requête de notification mise en attente. Une seule requête de SIO_IDEAL_SEND_BACKLOG_CHANGE mise en attente est autorisée à la fois.
La requête est annulée par le Gestionnaire d’E/S.
Le socket est fermé.

Deux fonctions wrapper inline pour ces IOCTL sont définies dans le fichier d’en-tête Ws2tcpip.h. Il est recommandé d’utiliser ces fonctions inline au lieu d’utiliser directement les IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE et SIO_IDEAL_SEND_BACKLOG_QUERY.

La fonction wrapper inline pour l’IOCTL SIO_IDEAL_SEND_BACKLOG_CHANGE est la fonction idealsendbacklognotify.

La fonction wrapper inline pour l’IOCTL SIO_IDEAL_SEND_BACKLOG_QUERY est la fonction idealsendbacklogquery.