LPFN_TRANSMITPACKETS fonction de rappel (mswsock.h)

Article
03/04/2024

La fonction TransmitPackets transmet des données en mémoire ou des données de fichier via un socket connecté. La fonction TransmitPackets utilise le gestionnaire de cache du système d’exploitation pour récupérer les données de fichier, verrouillant la mémoire pendant le temps minimal nécessaire à la transmission et aboutissant à une transmission efficace et performante.

Note Cette fonction est une extension spécifique à Microsoft de la spécification des sockets Windows.

Syntaxe

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

BOOL LpfnTransmitpackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
)
{...}

Paramètres

hSocket

Handle du socket connecté à utiliser dans la transmission. Bien que le socket n’ait pas besoin d’être un circuit orienté connexion, la destination/l’homologue par défaut doit avoir été établie à l’aide de la fonction connect, WSAConnect, accept, WSAAccept, AcceptEx ou WSAJoinLeaf .

lpPacketArray

Tableau de type TRANSMIT_PACKETS_ELEMENT, décrivant les données à transmettre.

nElementCount

Nombre d’éléments dans lpPacketArray.

nSendSize

Taille, en octets, du bloc de données utilisé dans l’opération d’envoi . Définissez nSendSize sur zéro pour permettre à la couche sockets de sélectionner une taille d’envoi par défaut.

La définition de nSendSize sur 0xFFFFFFF permet à l’appelant de contrôler la taille et le contenu de chaque demande d’envoi , obtenue à l’aide de l’indicateur TP_ELEMENT_EOP dans le tableau TRANSMIT_PACKETS_ELEMENT pointé vers dans le paramètre lpPacketArray . Cette fonctionnalité est utile pour les protocoles de message qui imposent des limitations sur la taille des demandes d’envoi individuelles.

lpOverlapped

Pointeur vers une structure OVERLAPPED. Si le handle de socket spécifié dans le paramètre hSocket a été ouvert en tant que chevauchement, utilisez ce paramètre pour obtenir une opération d’E/S asynchrone (qui se chevauche). Les handles de socket sont ouverts comme étant superposés par défaut.

dwFlags

Ensemble d’indicateurs utilisés pour personnaliser le traitement de la fonction TransmitPackets . Le tableau suivant décrit l’utilisation du paramètre dwFlags .

Valeur	Signification
TF_DISCONNECT	Démarre une déconnexion au niveau du transport une fois que toutes les données de fichier ont été mises en file d’attente pour la transmission. S’applique uniquement aux sockets orientés connexion. La spécification de cet indicateur pour les sockets qui ne prennent pas en charge la sémantique de déconnexion (comme les sockets de datagramme) génère une erreur.
TF_REUSE_SOCKET	Prépare le handle de socket à réutiliser. Une fois la fonction TransmitPackets terminée, le handle de socket peut être passé à la fonction AcceptEx . Valide uniquement lorsqu’un socket orienté connexion et TF_DISCONNECT sont spécifiés. Note La transmission de paquets au niveau du socket est soumise au comportement du transport sous-jacent. Par exemple, un socket TCP peut être soumis à l’état de TIME_WAIT TCP, ce qui entraîne le retard de l’appel TransmitPackets .
TF_USE_DEFAULT_WORKER	Demande à Winsock d’utiliser le thread par défaut du système pour traiter de longues requêtes TransmitPackets . Les requêtes Long TransmitPackets sont définies comme des requêtes qui nécessitent plus d’une seule lecture à partir du fichier ou d’un cache ; la définition de la requête longue dépend donc de la taille du fichier et de la longueur spécifiée du paquet d’envoi. Le thread par défaut du système peut être ajusté à l’aide du paramètre de Registre suivant en tant que REG_DWORD :HKEY_LOCAL_MACHINE\ ParamètresAFD\\currentControlSet\ Services \TransmitWorker
TF_USE_SYSTEM_THREAD	Demande à Winsock d’utiliser des threads système pour traiter de longues requêtes TransmitPackets . Les requêtes Long TransmitPackets sont définies comme des requêtes qui nécessitent plus d’une seule lecture à partir du fichier ou d’un cache ; la définition de la requête longue dépend donc de la taille du fichier et de la longueur spécifiée du paquet d’envoi.
TF_USE_KERNEL_APC	Demande à Winsock d’utiliser des appels de procédure asynchrone (API) de noyau au lieu de threads de travail pour traiter les longues requêtes TransmitPackets . Les requêtes Long TransmitPackets sont définies comme des requêtes qui nécessitent plus d’une seule lecture à partir du fichier ou d’un cache ; la définition de la requête longue dépend donc de la taille du fichier et de la longueur spécifiée du paquet d’envoi. Pour plus d'informations, consultez la section Notes.

Valeur retournée

Si la fonction TransmitPackets réussit, la valeur de retour est TRUE. Sinon, la valeur renvoyée est FALSE. Pour obtenir des informations d’erreur étendues, appelez WSAGetLastError. Un code d’erreur de WSA_IO_PENDING ou ERROR_IO_PENDING indique que l’opération qui se chevauche a été lancée avec succès et que l’achèvement sera indiqué ultérieurement. Tout autre code d’erreur indique que l’opération qui se chevauche n’a pas été lancée avec succès et qu’aucune indication d’achèvement ne se produira. Dans ce cas, les applications doivent gérer ERROR_IO_PENDING ou WSA_IO_PENDING.

Code de retour	Description
WSAECONNABORTED	Une connexion établie a été abandonnée par un logiciel de votre ordinateur hôte. Cette erreur est retournée si le circuit virtuel a été arrêté en raison d’un délai d’attente ou d’une autre défaillance.
WSAECONNRESET	une connexion existante a dû être fermée par l’hôte distant. Cette erreur est retournée pour un socket de flux lorsque le circuit virtuel a été réinitialisé par le côté distant. L’application doit fermer le socket, car il n’est plus utilisable.
WSAEFAULT	Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un argument pointeur dans un appel. Cette erreur est retournée si le paramètre lpPacketArray ou lpOverlapped n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur.
WSAEINVAL	Argument non valide fourni. Cette erreur est retournée si le paramètre dwFlags a l’indicateur TF_REUSE_SOCKET défini, mais que l’indicateur TF_DISCONNECT n’a pas été défini. Cette erreur est également retournée si le décalage spécifié dans la structure OVERLAPPED pointée par lpOverlapped ne se trouve pas dans le fichier. Cette erreur est également retournée si le nombre total d’octets à transmettre est une valeur supérieure à 2 147 483 646, la valeur maximale d’un entier 32 bits moins 1.
WSAENETDOWN	Une opération de socket a rencontré un réseau mort. Cette erreur est retournée si le sous-système réseau a échoué.
WSAENETRESET	La connexion a été interrompue, car l'activité persistante a détecté un échec en cours d'opération. Cette erreur est retournée pour un socket de flux où la connexion a été interrompue en raison d’une activité de maintien en vie détectant une défaillance.
WSAENOBUFS	Impossible d’effectuer une opération sur un socket, car le système n’avait pas suffisamment d’espace de mémoire tampon ou car une file d’attente était pleine. Cette erreur est également retournée si le fournisseur Windows Sockets signale un blocage de mémoire tampon.
WSAENOTCONN	Une demande d’envoi ou de réception de données a été refusée, car le socket n’est pas connecté. Cette erreur est retournée pour un socket de flux.
WSAENOTSOCK	Une opération a été tentée sur un objet qui n’est pas un socket. Cette erreur est retournée si le paramètre hSocket n’est pas un socket.
WSAESHUTDOWN	Une demande d'envoi ou de réception de données n'a pas été autorisée car le socket avait déjà été éteint dans cette direction par un appel d'arrêt précédent. Cette erreur est retournée si un socket de flux a été arrêté pour l’envoi. Il n’est pas possible d’appeler TransmitFile sur un socket de flux après que la fonction d’arrêt a été appelée sur le socket avec le paramètre how défini sur SD_SEND ou SD_BOTH.
WSANOTINITIALISED	Soit l’application n’a pas appelé la fonction WSAStartup , soit WSAStartup a échoué. Un appel WSAStartup réussi doit se produire avant d’utiliser la fonction TransmitFile .
WSA_IO_PENDING	Une opération d’E/S qui se chevauche est en cours. Cette valeur est retournée si une opération d’E/S qui se chevauche a été lancée avec succès et indique que l’achèvement sera indiqué ultérieurement.
WSA_OPERATION_ABORTED	L'opération d'E/S a été abandonnée en raison de l'arrêt d'un thread ou de la requête d'une application. Cette erreur est retournée si l’opération qui a été chevauchée a été annulée en raison de la fermeture du socket, de l’exécution de la commande « SIO_FLUSH » dans WSAIoctl ou du thread qui a lancé la demande superposée a été arrêté avant la fin de l’opération. Note Toutes les E/S initiées par un thread donné sont annulées à la sortie de ce thread. Pour les sockets qui se chevauchent, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations asynchrones. Pour plus d’informations, consultez ExitThread.

Remarques

La fonction TransmitPackets est optimisée en fonction du système d’exploitation sur lequel elle est utilisée :

Sur les éditions de serveur Windows, la fonction TransmitPackets est optimisée pour des performances élevées.
Sur les éditions du client Windows, la fonction TransmitPackets est optimisée pour une utilisation minimale de la mémoire et des ressources.

Le nombre maximal d’octets pouvant être transmis à l’aide d’un seul appel à la fonction TransmitPackets est de 2 147 483 646, la valeur maximale d’un entier 32 bits moins 1. Si une application doit transmettre des données supérieures à 2 147 483 646 octets, plusieurs appels à la fonction TransmitPackets peuvent être utilisés, chaque appel ne transférant pas plus de 2 147 483 646 octets.

Note Le pointeur de fonction pour la fonction TransmitPackets doit être obtenu au moment de l’exécution en effectuant un appel à la fonction WSAIoctl avec le SIO_GET_EXTENSION_FUNCTION_POINTER opcode spécifié. La mémoire tampon d’entrée passée à la fonction WSAIoctl doit contenir WSAID_TRANSMITPACKETS, un identificateur global unique (GUID) dont la valeur identifie la fonction d’extension TransmitPackets . En cas de réussite, la sortie retournée par la fonction WSAIoctl contient un pointeur vers la fonction TransmitPackets . Le GUID WSAID_TRANSMITPACKETS est défini dans le fichier d’en-tête Mswsock.h .

Attendez-vous à de meilleurs résultats en matière de performances lors de l’utilisation de la fonction TransmitPackets sur Windows Server 2003.

Lorsque lpOverlapped n’a pas la valeur NULL, il se peut que les E/S qui se chevauchent ne se terminent pas avant le retour de la fonction TransmitPackets . Lorsque cela se produit, la fonction TransmitPackets retourne un échec et un appel à la fonction WSAGetLastError retourne ERROR_IO_PENDING, ce qui permet à l’appelant de continuer le traitement une fois la transmission terminée.

Note Toutes les E/S initiées par un thread donné sont annulées à la sortie de ce thread. Pour les sockets qui se chevauchent, les opérations asynchrones en attente peuvent échouer si le thread est fermé avant la fin des opérations. Pour plus d’informations, consultez ExitThread .

Lorsque la fonction TransmitPackets retourne TRUE ou renvoie FALSE et que WSAGetLastError retourne ERROR_IO_PENDING, Windows définit l’événement spécifié par le membre hEvent de la structure OVERLAPPED ou le socket spécifié par hSocket à l’état signalé et, une fois terminé, envoie une notification à tout port d’achèvement associé au socket. Utilisez GetOverlappedResult, WSAGetOverlappedResult ou GetQueuedCompletionStatus pour récupérer le status final et le nombre d’octets transmis.

TransmitPackets et les appels de procédure asynchrone (API)

L’utilisation de l’indicateur TF_USE_KERNEL_APC peut offrir des avantages significatifs en matière de performances. Si le thread à l’origine de l’appel de fonction TransmitPackets est utilisé pour des calculs lourds, il est possible, bien que peu probable, que des API soient empêchés de se lancer.

Note Il existe une différence entre les API de noyau et de mode utilisateur :

Les API du noyau démarrent lorsqu’un thread est en état d’attente.
Les API en mode utilisateur démarrent lorsqu’un thread est dans un état d’attente pouvant être alerté.

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1, Windows Vista [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	mswsock.h