Partager via


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.

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

 

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
TF_DISCONNECT
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.
TF_REUSE_SOCKET
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 .
 
TF_USE_DEFAULT_WORKER
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

TF_USE_SYSTEM_THREAD
Indique au fournisseur de services Windows Sockets d’utiliser des threads système pour traiter de longues requêtes TransmitFile .
TF_USE_KERNEL_APC
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.

TF_WRITE_BEHIND
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
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 lpTransmitBuffers 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 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.
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.
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é.
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 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.
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 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.

Note Le pointeur de fonction pour la fonction TransmitFile doit être obtenu au moment de l’exécution en appelant 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_TRANSMITFILE, un identificateur global unique (GUID) dont la valeur identifie la fonction d’extension TransmitFile . En cas de réussite, la sortie retournée par la fonction WSAIoctl contient un pointeur vers la fonction TransmitFile . Le GUID WSAID_TRANSMITFILE est défini dans le fichier d’en-tête Mswsock.h .
 
RemarqueTransmitFile n’est pas fonctionnel sur les transports qui effectuent leur propre mise en mémoire tampon. Les transports avec le jeu d’indicateurs TDI_SERVICE_INTERNAL_BUFFERING, par exemple ADSP, effectuent leur propre mise en mémoire tampon. Étant donné que TransmitFile obtient ses gains de performances en envoyant des données directement à partir du cache de fichiers. Les transports qui manquent d’espace tampon sur une connexion particulière ne sont pas gérés par TransmitFile et, en raison d’un manque d’espace tampon sur la connexion, TransmitFile retourne STATUS_DEVICE_NOT_READY.
 
La fonction TransmitFile a été principalement ajoutée à Winsock pour une utilisation par des applications serveur hautes performances (serveurs web et ftp, par exemple).

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

Voir aussi

ExitThread

OVERLAPPED

TRANSMIT_FILE_BUFFERS

TransmitPackets

WSASend

closesocket