code de contrôle SIO_IDEAL_SEND_BACKLOG_QUERY

Article
06/13/2023

Description

Le code de contrôle SIO_IDEAL_SEND_BACKLOG_QUERY récupère la valeur isb (Send Backlog) idéale pour la connexion sous-jacente.

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_QUERY, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  (LPVOID) lpvOutBuffer,         // output buffer
  (DWORD) cbOutBuffer,       // 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_QUERY 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 doit pointer vers un type de données ULONG si les paramètres lpOverlapped et lpCompletionRoutine sont NULL.

cbOutBuffer

Taille, en octets, de la mémoire tampon de sortie. Ce paramètre doit avoir au moins la taille d’un type de données ULONG .

lpcbBytesReturned

Pointeur vers une variable qui reçoit la taille, en octets, des données stockées dans la mémoire tampon de sortie.

Si la mémoire tampon de sortie est trop petite, l’appel échoue, WSAGetLastError retourne WSAEINVAL et le paramètre lpcbBytesReturned pointe vers une valeur DWORD de zéro.

Si lpOverlapped a la valeur NULL, la valeur DWORD indiquée par le paramètre lpcbBytesReturned qui est retourné lors d’un appel réussi ne peut pas être égale à zéro.

Si le paramètre lpOverlapped n’est pas NULL pour les sockets qui se chevauchent, les opérations qui ne peuvent pas être effectuées immédiatement sont lancées et l’achèvement sera indiqué ultérieurement. La valeur DWORD indiquée par le paramètre lpcbBytesReturned retourné peut être égale à zéro, car la taille des données stockées ne peut pas être déterminée tant que l’opération qui se chevauche n’est pas terminée. Le status d’achèvement final peut être récupéré lorsque la méthode d’achèvement appropriée est signalée lorsque l’opération est terminée.

lpvOverlapped

Pointeur vers une structure WSAOVERLAPPED .

Si le socket s a été créé sans l’attribut qui se chevauche, 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 qui se chevauche (asynchrone). 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 lorsque l’opération est terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou qu’une erreur ne se produit pas.

lpCompletionRoutine

Type : _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Pointeur vers la routine d’achèvement appelée une fois l’opération terminée (ignoré pour les sockets non superposés).

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 qui se chevauche 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 lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped ou lpCompletionRoutine n’est pas entièrement 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 est inférieur à la taille d’un type de données ULONG .
WSAENETDOWN	Le sous-système réseau a échoué.
WSAENOPROTOOPT	L’option 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 le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL n’est pas pris en charge par le fournisseur de transport. Cette erreur est également retournée lorsqu’une tentative d’utilisation du SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL est effectuée sur un socket de datagramme.

Notes

Le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL est pris 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 attente (envoyées mais non encore reconnues) dans TCP afin d’obtenir le débit le plus élevé. La valeur idéale pour la quantité de données en attente pour obtenir le meilleur débit pour la connexion TCP est appelée taille de backlog d’envoi idéale (ISB). La valeur ISB est fonction du produit de délai de bande passante de la connexion TCP et de la fenêtre de réception annoncée du récepteur (et en partie de 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 les versions ultérieures du système d’exploitation. Le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL peut être utilisé 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 versions ultérieures du système d’exploitation, les SIO_IDEAL_SEND_BACKLOG_CHANGE et les SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL sont pris en charge sur les sockets orientés 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.

L’utilisation classique des SIO_IDEAL_SEND_BACKLOG_CHANGE et SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL est basée sur la méthode d’envoi utilisée par les applications. Deux cas courants sont abordés.

Les applications qui exécutent une requête d’envoi bloquante ou non bloquante à la fois s’appuient généralement sur la mise en mémoire tampon d’envoi interne par Winsock pour obtenir un débit décent. La limite de mémoire tampon d’envoi pour une connexion donnée est contrôlée par l’option de socket SO_SNDBUF . Pour la méthode d’envoi bloquante et non bloquante, la limite de mémoire tampon d’envoi détermine la quantité de données restantes en attente dans TCP. Si la valeur ISB de la connexion est supérieure à la limite de mémoire tampon d’envoi, le débit obtenu sur la connexion n’est pas optimal. Pour obtenir un meilleur débit, les applications peuvent définir la limite de mémoire tampon d’envoi en fonction du résultat de la requête ISB lorsque des notifications de modification ISB se produisent sur la connexion.

Pour les applications qui utilisent la méthode d’envoi superposée avec plusieurs demandes d’envoi en attente, la quantité de données restantes en attente dans TCP est déterminée par la limite de mémoire tampon d’envoi dans Winsock et la quantité totale de données contenues dans les demandes d’envoi en suspens qui se chevauchent. Dans ce cas, les applications doivent utiliser la valeur ISB pour déterminer le nombre de demandes d’envoi en attente qu’elles doivent conserver et la taille des données pour chaque demande d’envoi. Dans l’idéal, l’application doit essayer de conserver l’équation suivante satisfaite :

ISB value == send buffer limit + (number of simultaneous overlapped send requests * data length per send request)

Notez que l’utilisation des IOCTL ISB sur les sockets TCP ci-dessus peut entraîner une utilisation accrue de la mémoire en échange d’un débit accru sur les connexions avec un produit à délai de bande passante élevé. L’implémentation TCP dans Windows limite les valeurs ISB en fonction de l’utilisation globale de la mémoire système.

Le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL est autorisé uniquement sur un socket de flux qui est à l’état connecté. Sinon, la fonction WSAIoctl ou WSPIoctl échoue avec WSAENOTCONN.

Tout 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 qui se chevauchent sont recommandées pour les IOCTL qui sont particulièrement susceptibles de se bloquer.

Le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL n’est pas susceptible de bloquer, il est donc normalement appelé de manière synchrone avec les paramètres lpOverlapped et lpCompletionRoutine définis sur NULL.

Le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL 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 dont le paramètre est défini sur SD_SEND, d’un appel à la fonction DisconnectEx ou d’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. La demande est annulée par le Gestionnaire d’E/S.

Deux fonctions de 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 SIO_IDEAL_SEND_BACKLOG_CHANGE et SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL.

La fonction wrapper inline pour le SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL est la fonction idealsendbacklognotify .

La fonction wrapper inline pour le SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL est la fonction idealsendbacklogquery .

La mise en mémoire tampon d’envoi dynamique pour TCP a été ajoutée sur Windows 7 et Windows Server 2008 R2. Par défaut, la mise en mémoire tampon d’envoi dynamique pour TCP est activée, sauf si une application définit l’option de socket SO_SNDBUF sur le socket de flux.

L’utilisation de netsh est la méthode recommandée pour interroger ou définir la mise en mémoire tampon d’envoi dynamique pour TCP.

La valeur actuelle de la mise en mémoire tampon d’envoi dynamique pour TCP peut être récupérée à l’aide de la commande suivante :

netsh winsock show autotuning

La mise en mémoire tampon d’envoi dynamique pour TCP peut être désactivée à l’aide de la commande suivante :

netsh winsock set autotuning off

La mise en mémoire tampon d’envoi dynamique pour TCP peut être activée à l’aide de la commande suivante :

netsh winsock set autotuning on

Bien qu’il soit déconseillé, la mise en mémoire tampon d’envoi dynamique peut être désactivée à partir d’une application en définissant la valeur de Registre suivante sur zéro :

HKEY_LOCAL_MACHINE\SYSTEM\Current Control Set\Services\AFD\Parameters\DynamicSendBufferDisable

Lors de la modification de la valeur de la mise en mémoire tampon d’envoi dynamique à l’aide de NetSh.exe ou de la modification de la valeur du Registre, l’ordinateur doit être redémarré pour que la modification prenne effet.

Avec la mise en mémoire tampon d’envoi dynamique sur Windows 7 et Windows Server 2008 R2, l’utilisation des SIO_IDEAL_SEND_BACKLOG_CHANGE et SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL n’est nécessaire que dans des circonstances particulières.