Fonction TransmitFile (mswsock.h)
La fonction TransmitFile transmet les données de fichier via un handle de socket connecté. Cette fonction utilise le gestionnaire de cache du système d’exploitation pour récupérer les données de fichier et fournit un transfert de données de fichier hautes performances sur des sockets.
Syntaxe
BOOL TransmitFile(
SOCKET hSocket,
HANDLE hFile,
DWORD nNumberOfBytesToWrite,
DWORD nNumberOfBytesPerSend,
LPOVERLAPPED lpOverlapped,
LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
DWORD dwReserved
);
Paramètres
hSocket
Handle à un socket connecté. La fonction TransmitFile transmet les données de fichier sur ce socket. Le socket spécifié par le paramètre hSocket doit être un socket orienté connexion de type SOCK_STREAM, SOCK_SEQPACKET ou SOCK_RDM.
hFile
Handle du fichier ouvert transmis par la fonction TransmitFile . Étant donné que le système d’exploitation lit les données de fichier de manière séquentielle, vous pouvez améliorer les performances de mise en cache en ouvrant le handle avec FILE_FLAG_SEQUENTIAL_SCAN.
Le paramètre hFile est facultatif. Si le paramètre hFile a la valeur NULL, seules les données de l’en-tête et/ou de la mémoire tampon de queue sont transmises. Toute action supplémentaire, telle que la déconnexion ou la réutilisation du socket, est effectuée comme spécifié par le paramètre dwFlags .
nNumberOfBytesToWrite
Nombre d’octets dans le fichier à transmettre. La fonction TransmitFile se termine lorsqu’elle a envoyé le nombre d’octets spécifié ou lorsqu’une erreur se produit, selon ce qui se produit en premier.
Définissez ce paramètre sur zéro afin de transmettre l’intégralité du fichier.
nNumberOfBytesPerSend
Taille, en octets, de chaque bloc de données envoyé dans chaque opération d’envoi. Ce paramètre est utilisé par la couche sockets de Windows pour déterminer la taille de bloc pour les opérations d’envoi. Pour sélectionner la taille d’envoi par défaut, définissez ce paramètre sur zéro.
Le paramètre nNumberOfBytesPerSend est utile pour les protocoles qui ont des limitations sur la taille des demandes d’envoi individuelles.
lpOverlapped
Pointeur vers une structure OVERLAPPED. Si le handle de socket a été ouvert en tant que chevauchement, spécifiez ce paramètre afin d’obtenir une opération d’E/S qui se chevauche (asynchrone). Par défaut, les handles de socket sont ouverts en tant que chevauchement.
Vous pouvez utiliser le paramètre lpOverlapped pour spécifier un décalage 64 bits dans le fichier à partir duquel démarrer le transfert de données de fichier en définissant le membre Offset et OffsetHigh de la structure CHEVAUCHEMENT . Si lpOverlapped est un pointeur NULL , la transmission des données commence toujours au décalage d’octet actuel dans le fichier.
Lorsque l’objet 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 TransmitFile . Dans ce cas, la fonction TransmitFile retourne FALSE et WSAGetLastError retourne ERROR_IO_PENDING ou WSA_IO_PENDING. Cela permet à l’appelant de continuer le traitement pendant que l’opération de transmission de fichier se termine. 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é à la fin de la demande de transmission de données.
lpTransmitBuffers
Pointeur vers une structure de données TRANSMIT_FILE_BUFFERS qui contient des pointeurs vers des données à envoyer avant et après l’envoi des données de fichier. Ce paramètre doit être défini sur un pointeur NULL si vous souhaitez transmettre uniquement les données du fichier.
dwReserved
Ensemble d’indicateurs utilisés pour modifier le comportement de l’appel de fonction TransmitFile . Le paramètre dwFlags peut contenir une combinaison des options suivantes définies dans le fichier d’en-tête Mswsock.h :
| Indicateur | Signification |
|---|---|
|
Démarrez une déconnexion de niveau transport lorsque toutes les données de fichiers sont mises en file d'attente en vue de leur transmission. |
|
Préparez le handle de socket à réutiliser. Cet indicateur n’est valide que si TF_DISCONNECT est également spécifié.
Une fois la requête TransmitFile terminée, le handle de socket peut être passé à l’appel de fonction utilisé précédemment pour établir la connexion, par exemple AcceptEx ou ConnectEx. Cette réutilisation s’exclut mutuellement ; par exemple, si la fonction AcceptEx a été appelée pour le socket, la réutilisation est autorisée uniquement pour les appels ultérieurs à la fonction AcceptEx , et non pour un appel ultérieur à ConnectEx. Note La transmission du fichier 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 TransmitFile .
|
|
Indique au fournisseur de services Windows Sockets d’utiliser le thread par défaut du système pour traiter de longues requêtes TransmitFile . Le thread système par défaut peut être ajusté à l’aide du paramètre de Registre suivant comme REG_DWORD : HKEY_LOCAL_MACHINE\Currentcontrolset\Services\AFD\Paramètres\TransmitWorker |
|
Indique au fournisseur de services Windows Sockets d’utiliser des threads système pour traiter de longues requêtes TransmitFile . |
|
Indique au pilote d’utiliser des appels de procédure asynchrone du noyau (API) au lieu de threads de travail pour traiter de longues requêtes TransmitFile . Les requêtes Long TransmitFile sont définies comme des requêtes qui nécessitent plus d’une seule lecture à partir du fichier ou d’un cache ; la demande dépend donc de la taille du fichier et de la longueur spécifiée du paquet d’envoi.
L’utilisation de TF_USE_KERNEL_APC peut offrir des avantages significatifs en matière de performances. Il est possible (bien que peu probable), cependant, que le thread dans lequel le contexte TransmitFile est lancé soit utilisé pour des calculs lourds ; cette situation peut empêcher le lancement des API. Notez que le pilote en mode noyau Winsock utilise des API de noyau normaux, qui se lancent chaque fois qu’un thread est dans un état d’attente, ce qui diffère des API en mode utilisateur, qui se lancent chaque fois qu’un thread est dans un état d’attente pouvant être alerté lancé en mode utilisateur. |
|
Terminez la demande TransmitFile immédiatement, sans être en attente. Si cet indicateur est spécifié et que TransmitFile réussit, les données ont été acceptées par le système, mais pas nécessairement reconnues par l’extrémité distante. N’utilisez pas ce paramètre avec les indicateurs TF_DISCONNECT et TF_REUSE_SOCKET.
Note Si le fichier envoyé n’est pas dans le cache du système de fichiers, la demande est suspendu.
|
Valeur retournée
Si la fonction TransmitFile 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 |
|---|---|
| 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. | |
| 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. | |
| 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 lpTransmitBuffers ou lpOverlapped n’est pas entièrement contenu dans une partie valide de l’espace d’adressage utilisateur. | |
| Argument non valide fourni. Cette erreur est retournée si le paramètre hSocket a spécifié un socket de type SOCK_DGRAM ou SOCK_RAW. 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 paramètre nNumberOfBytesToWrite a une valeur supérieure à 2 147 483 646, la valeur maximale d’un entier 32 bits moins 1. | |
| 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é. | |
| La connexion a été interrompue, car l'activité persistante a détecté un échec en cours d'opération. | |
| 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. | |
| Une demande d’envoi ou de réception de données a été refusée, car le socket n’est pas connecté. | |
| 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. | |
| 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 le socket a été arrêté pour l’envoi. Il n’est pas possible d’appeler TransmitFile sur un socket une fois 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. | |
| 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 . | |
| 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. | |
|
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 TransmitFile utilise le gestionnaire de cache du système d’exploitation pour récupérer les données de fichier et fournir un transfert de données de fichier hautes performances sur des sockets.
La fonction TransmitFile prend uniquement en charge les sockets orientés connexion de type SOCK_STREAM, SOCK_SEQPACKET et SOCK_RDM. Les sockets de type SOCK_DGRAM et SOCK_RAW ne sont pas pris en charge. La fonction TransmitPackets peut être utilisée avec des sockets de type SOCK_DGRAM.
Le nombre maximal d’octets pouvant être transmis à l’aide d’un seul appel à la fonction TransmitFile est 2 147 483 646, la valeur maximale d’un entier 32 bits moins 1. Le nombre maximal d’octets à envoyer dans un seul appel inclut toutes les données envoyées avant ou après les données de fichier pointées par le paramètre lpTransmitBuffers plus la valeur spécifiée dans le paramètre nNumberOfBytesToWrite pour la longueur des données de fichier à envoyer. Si une application doit transmettre un fichier supérieur à 2 147 483 646 octets, plusieurs appels à la fonction TransmitFile peuvent être utilisés, chaque appel ne transférant pas plus de 2 147 483 646 octets. La définition du paramètre nNumberOfBytesToWrite sur zéro pour un fichier supérieur à 2 147 483 646 octets échoue également, car dans ce cas, la fonction TransmitFile utilise la taille du fichier comme valeur du nombre d’octets à transmettre.
Les versions de station de travail et cliente de Windows optimisent la fonction TransmitFile pour une utilisation minimale de la mémoire et des ressources en limitant à deux le nombre d’opérations TransmitFile simultanées autorisées sur le système. Sur Windows Vista, Windows XP, Windows 2000 Professionnel et Windows NT Workstation 3.51 et versions ultérieures, seules deux demandes TransmitFile en suspens sont traitées simultanément ; la troisième demande attend que l’une des demandes précédentes soit terminée.
Les versions serveur de Windows optimisent la fonction TransmitFile pour des performances élevées. Sur les versions de serveur, aucune limite par défaut n’est appliquée au nombre d’opérations TransmitFile simultanées autorisées sur le système. Attendez-vous à de meilleurs résultats en matière de performances lors de l’utilisation de TransmitFile sur les versions serveur de Windows. Sur les versions serveur de Windows, il est possible de définir une limite sur le nombre maximal d’opérations TransmitFile simultanées en créant une entrée de Registre et en définissant une valeur pour les REG_DWORD suivantes :
HKEY_LOCAL_MACHINE\Currentcontrolset\Services\AFD\Paramètres\MaxActiveTransmitFileCount
Si la fonction TransmitFile est appelée avec le socket TCP (protocole de IPPROTO_TCP) avec les indicateurs TF_DISCONNECT et TF_REUSE_SOCKET spécifiés, l’appel ne se termine pas tant que les deux conditions suivantes ne sont pas remplies.
- Toutes les données de réception en attente envoyées par le côté distant (reçues avant une FIN du côté distant) sur le socket TCP ont été lues.
- Le côté distant a fermé la connexion (fin de la fermeture de la connexion TCP).
Si la fonction TransmitFile est appelée avec le paramètre lpOverlapped défini sur NULL, l’opération est exécutée en tant qu’E/S synchrones. La fonction ne se termine pas tant que le fichier n’a pas été envoyé.
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.
Remarques relatives à QoS
La fonction TransmitFile permet de définir deux indicateurs, TF_DISCONNECT ou TF_REUSE_SOCKET, qui retournent le socket à un état « déconnecté, réutilisable » après la transmission du fichier. Ces indicateurs ne doivent pas être utilisés sur un socket où la qualité de service a été demandée, car le fournisseur de services peut supprimer immédiatement toute qualité de service associée au socket avant la fin du transfert de fichiers. La meilleure approche pour un socket prenant en charge QoS consiste simplement à appeler la fonction closesocket une fois le transfert de fichier terminé, plutôt que de s’appuyer sur ces indicateurs.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 (inclure Mswsock.h) |
| Bibliothèque | Mswsock.lib |
| DLL | Mswsock.dll |