Funzione TransmitFile (mswsock.h)
La funzione TransmitFile trasmette i dati dei file su un handle socket connesso. Questa funzione usa la gestione cache del sistema operativo per recuperare i dati del file e fornisce il trasferimento dei dati dei file ad alte prestazioni sui socket.
Sintassi
BOOL TransmitFile(
SOCKET hSocket,
HANDLE hFile,
DWORD nNumberOfBytesToWrite,
DWORD nNumberOfBytesPerSend,
LPOVERLAPPED lpOverlapped,
LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
DWORD dwReserved
);
Parametri
hSocket
Handle a un socket connesso. La funzione TransmitFile trasmetterà i dati del file su questo socket. Il socket specificato dal parametro hSocket deve essere un socket orientato alla connessione di tipo SOCK_STREAM, SOCK_SEQPACKET o SOCK_RDM.
hFile
Handle per il file aperto trasmesso dalla funzione TransmitFile . Poiché il sistema operativo legge i dati del file in sequenza, è possibile migliorare le prestazioni di memorizzazione nella cache aprendo l'handle con FILE_FLAG_SEQUENTIAL_SCAN.
Il parametro hFile è facoltativo. Se il parametro hFile è NULL, vengono trasmessi solo i dati nell'intestazione e/o nel buffer della coda. Qualsiasi azione aggiuntiva, ad esempio disconnessione o riutilizzo del socket, viene eseguita come specificato dal parametro dwFlags .
nNumberOfBytesToWrite
Numero di byte nel file da trasmettere. La funzione TransmitFile viene completata quando ha inviato il numero specificato di byte o quando si verifica un errore.
Impostare questo parametro su zero per trasmettere l'intero file.
nNumberOfBytesPerSend
Dimensioni, in byte, di ogni blocco di dati inviati in ogni operazione di invio. Questo parametro viene usato dal livello socket di Windows per determinare le dimensioni del blocco per le operazioni di invio. Per selezionare le dimensioni di invio predefinite, impostare questo parametro su zero.
Il parametro nNumberOfBytesPerSend è utile per i protocolli che hanno limitazioni sulle dimensioni delle singole richieste di invio.
lpOverlapped
Puntatore a una struttura OVERLAPPED . Se l'handle socket è stato aperto come sovrapposto, specificare questo parametro per ottenere un'operazione di I/O sovrapposta (asincrona). Per impostazione predefinita, gli handle socket vengono aperti come sovrapposti.
È possibile usare il parametro lpOverlapped per specificare un offset a 64 bit all'interno del file in cui avviare il trasferimento dei dati del file impostando il membro Offset e OffsetHigh della struttura OVERLAPPED. Se lpOverlapped è un puntatore NULL , la trasmissione dei dati inizia sempre all'offset di byte corrente nel file.
Quando lpOverlapped non è NULL, l'I/O sovrapposto potrebbe non terminare prima che TransmitFile venga restituito. In tal caso, la funzione TransmitFile restituisce FALSE e WSAGetLastError restituisce ERROR_IO_PENDING o WSA_IO_PENDING. Ciò consente al chiamante di continuare l'elaborazione mentre l'operazione di trasmissione dei file viene completata. Windows imposta l'evento specificato dal membro hEvent della struttura OVERLAPPED o dal socket specificato da hSocket, sullo stato segnalato al completamento della richiesta di trasmissione dei dati.
lpTransmitBuffers
Puntatore a una struttura di dati TRANSMIT_FILE_BUFFERS che contiene puntatori ai dati da inviare prima e dopo l'invio dei dati del file. Questo parametro deve essere impostato su un puntatore NULL se si desidera trasmettere solo i dati del file.
dwReserved
Set di flag usati per modificare il comportamento della chiamata di funzione TransmitFile . Il parametro dwFlags può contenere una combinazione delle opzioni seguenti definite nel file di intestazione Mswsock.h :
| Contrassegno | Significato |
|---|---|
|
Avviare una disconnessione a livello di trasporto dopo che tutti i dati dei file sono stati accodati per la trasmissione. |
|
Preparare l'handle socket da riutilizzare. Questo flag è valido solo se viene specificato TF_DISCONNECT.
Al termine della richiesta TransmitFile, l'handle del socket può essere passato alla chiamata di funzione usata in precedenza per stabilire la connessione, ad esempio AcceptEx o ConnectEx. Tale riutilizzo si escludono a vicenda; ad esempio, se la funzione AcceptEx è stata chiamata per il socket, il riutilizzo è consentito solo per le chiamate successive alla funzione AcceptEx e non consentite per una chiamata successiva a ConnectEx. Nota La trasmissione del file a livello di socket è soggetta al comportamento del trasporto sottostante. Ad esempio, un socket TCP può essere soggetto allo stato tcp TIME_WAIT, causando il ritardo della chiamata TransmitFile .
|
|
Indirizza il provider di servizi Windows Sockets all'uso del thread predefinito del sistema per elaborare le richieste di TrasmissioneFile lunghe. Il thread predefinito del sistema può essere modificato usando il parametro del Registro di sistema seguente come REG_DWORD: HKEY_LOCAL_MACHINE\Currentcontrolset\Servizi\AFD\Parametri\TransmitWorker |
|
Indirizza il provider di servizi Windows Sockets per l'uso dei thread di sistema per elaborare le richieste di TransmitFile lunghe. |
|
Indirizza il driver per usare le chiamate asincrone di procedure asincrone del kernel anziché i thread di lavoro per elaborare richieste di TrasmissioneFile lunghe. Le richieste Long TransmitFile vengono definite come richieste che richiedono più di una sola lettura dal file o da una cache; la richiesta dipende quindi dalle dimensioni del file e dalla lunghezza specificata del pacchetto di invio.
L'uso di TF_USE_KERNEL_APC può offrire vantaggi significativi sulle prestazioni. È tuttavia possibile (anche se improbabile), che il thread in cui viene avviato Il file di trasmissione del contesto viene usato per calcoli pesanti; questa situazione può impedire l'avvio delle API. Si noti che il driver in modalità kernel Winsock usa le normali API del kernel, che vengono avviate ogni volta che un thread si trova in uno stato di attesa, che differisce dalle API in modalità utente, che vengono avviate ogni volta che un thread si trova in uno stato di attesa avvisabile avviato in modalità utente. |
|
Completare immediatamente la richiesta TransmitFile , senza sospeso. Se questo flag viene specificato e TransmitFile ha esito positivo, i dati sono stati accettati dal sistema ma non necessariamente riconosciuti dalla fine remota. Non usare questa impostazione con i flag di TF_DISCONNECT e TF_REUSE_SOCKET.
Nota Se il file inviato non si trova nella cache del file system, la richiesta viene eseguita.
|
Valore restituito
Se la funzione TransmitFile ha esito positivo, il valore restituito è TRUE. In caso contrario, il valore restituito è FALSE. Per ottenere informazioni sull'errore estese, chiamare WSAGetLastError. Un codice di errore di WSA_IO_PENDING o ERROR_IO_PENDING indica che l'operazione sovrapposta è stata avviata correttamente e che il completamento verrà indicato in un secondo momento. Qualsiasi altro codice di errore indica che l'operazione sovrapposta non è stata avviata correttamente e non si verificherà alcuna indicazione di completamento. Le applicazioni devono gestire ERROR_IO_PENDING o WSA_IO_PENDING in questo caso.
| Codice restituito | Descrizione |
|---|---|
| Connessione interrotta dal software del computer host. Questo errore viene restituito se il circuito virtuale è stato terminato a causa di un timeout o di un altro errore. | |
| Connessione in corso interrotta forzatamente dall'host remoto. Questo errore viene restituito per un socket di flusso quando il circuito virtuale è stato reimpostato dal lato remoto. L'applicazione deve chiudere il socket che non è più utilizzabile. | |
| Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un argomento puntatore in una chiamata. Questo errore viene restituito se il parametro lpTransmitBuffers o lpOverlapped non è totalmente contenuto in una parte valida dello spazio indirizzi utente. | |
| Argomento fornito non valido. Questo errore viene restituito se il parametro hSocket ha specificato un socket di tipo SOCK_DGRAM o SOCK_RAW. Questo errore viene restituito se il parametro dwFlags ha il flag di TF_REUSE_SOCKET impostato, ma il flag TF_DISCONNECT non è stato impostato. Questo errore viene restituito anche se l'offset specificato nella struttura OVERLAPPED a cui punta lpOverlapped non si trova all'interno del file. Questo errore viene restituito anche se il parametro nNumberOfBytesToWrite è impostato su un valore maggiore di 2.147.483.646, il valore massimo per un intero a 32 bit meno 1. | |
| Un'operazione socket ha rilevato una rete morta. Questo errore viene restituito se il sottosistema di rete non è riuscito. | |
| La connessione è stata interrotta a causa dell'attività keep-alive che rileva un errore durante l'operazione in corso. | |
| Impossibile eseguire un'operazione su un socket perché il sistema non disponeva di spazio buffer sufficiente o perché una coda era piena. Questo errore viene restituito anche se il provider Windows Sockets segnala un deadlock del buffer. | |
| Richiesta di invio o ricezione dei dati non consentita perché il socket non è connesso. | |
| Un'operazione è stata tentata su un elemento che non è un socket. Questo errore viene restituito se il parametro hSocket non è un socket. | |
| Socket chiuso nella direzione specificata da una precedente chiamata di arresto. Richiesta di invio o ricezione dati annullata. Questo errore viene restituito se il socket è stato arrestato per l'invio. Non è possibile chiamare TransmitFile in un socket dopo che la funzione di arresto è stata chiamata sul socket con il parametro impostato su SD_SEND o SD_BOTH. | |
| L'applicazione non ha chiamato la funzione WSAStartup o WSAStartup non riuscita. Prima di usare la funzione TransmitFile, è necessario eseguire una chiamata WSAStartup riuscita. | |
| Un'operazione di I/O sovrapposta è in corso. Questo valore viene restituito se un'operazione di I/O sovrapposta è stata avviata correttamente e indica che il completamento verrà indicato in un secondo momento. | |
|
Operazione di I/O annullata per uscita da un thread o su richiesta di un'applicazione. Questo errore viene restituito se l'operazione sovrapposta è stata annullata a causa della chiusura del socket, l'esecuzione del comando "SIO_FLUSH" in WSAIoctl o il thread che ha avviato la richiesta sovrapposta è scaduta prima del completamento dell'operazione.
Nota Tutti gli I/O avviati da un determinato thread vengono annullati quando il thread viene chiuso. Per i socket sovrapposti, le operazioni asincrone in sospeso possono non riuscire se il thread viene chiuso prima del completamento delle operazioni asincrone. Per altre informazioni, vedere ExitThread.
|
Commenti
La funzione TransmitFile usa la gestione cache del sistema operativo per recuperare i dati del file e fornire il trasferimento dei dati dei file ad alte prestazioni sui socket.
La funzione TransmitFile supporta solo socket orientati alla connessione di tipo SOCK_STREAM, SOCK_SEQPACKET e SOCK_RDM. I socket di tipo SOCK_DGRAM e SOCK_RAW non sono supportati. La funzione TransmitPackets può essere usata con socket di tipo SOCK_DGRAM.
Il numero massimo di byte che possono essere trasmessi usando una singola chiamata alla funzione TransmitFile è pari a 2.147.483.646, il valore massimo per un intero a 32 bit meno 1. Il numero massimo di byte da inviare in una singola chiamata include tutti i dati inviati prima o dopo i dati del file puntati dal parametro lpTransmitBuffers e il valore specificato nel parametro nNumberOfBytesToWrite per la lunghezza dei dati del file da inviare. Se un'applicazione deve trasmettere un file maggiore di 2.147.483.646 byte, è possibile usare più chiamate alla funzione TransmitFile con ogni chiamata che trasferisce non più di 2.147.483.646 byte. L'impostazione del parametro nNumberOfBytesToWrite su zero per un file maggiore di 2.147.483.646 byte avrà esito negativo poiché in questo caso la funzione TransmitFile userà le dimensioni del file come valore per il numero di byte da trasmettere.
Le versioni workstation e client di Windows ottimizzano la funzione TransmitFile per l'utilizzo minimo della memoria e delle risorse limitando il numero di operazioni di trasmissione simultanee consentite nel sistema a un massimo di due. In Windows Vista, Windows XP, Windows 2000 Professional e Windows NT Workstation 3.51 e versioni successive vengono gestite contemporaneamente solo due richieste Di trasmissione in sospeso; la terza richiesta attenderà fino al completamento di una delle richieste precedenti.
Le versioni del server di Windows ottimizzano la funzione TransmitFile per prestazioni elevate. Nelle versioni del server non sono previsti limiti predefiniti sul numero di operazioni di trasmissione simultanee consentite nel sistema. Prevedere risultati migliori sulle prestazioni quando si usa TransmitFile nelle versioni server di Windows. Nelle versioni del server di Windows è possibile impostare un limite per il numero massimo di operazioni di trasmissione simultanee creando una voce del Registro di sistema e impostando un valore per la REG_DWORD seguente:
HKEY_LOCAL_MACHINE\Currentcontrolset\Servizi\AFD\Parametri\MaxActiveTransmitFileCount
Se la funzione TransmitFile viene chiamata con socket TCP (protocollo di IPPROTO_TCP) con i flag di TF_DISCONNECT e TF_REUSE_SOCKET specificati, la chiamata non verrà completata fino a quando non vengono soddisfatte le due condizioni seguenti.
- Tutti i dati di ricezione in sospeso inviati dal lato remoto (ricevuti prima di un FIN dal lato remoto) sul socket TCP sono stati letti.
- Il lato remoto ha chiuso la connessione (completata la chiusura della connessione TCP graziata).
Se la funzione TransmitFile viene chiamata con il parametro lpOverlapped impostato su NULL, l'operazione viene eseguita come I/O sincrona. La funzione non verrà completata finché il file non è stato inviato.
Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.
Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.
Note per QoS
La funzione TransmitFile consente l'impostazione di due flag, TF_DISCONNECT o TF_REUSE_SOCKET, che restituiscono il socket a uno stato "disconnesso, riutilizzabile" dopo la trasmissione del file. Questi flag non devono essere usati in un socket in cui è stata richiesta la qualità del servizio, poiché il provider di servizi può eliminare immediatamente qualsiasi qualità del servizio associato al socket prima del completamento del trasferimento del file. L'approccio migliore per un socket abilitato per QoS consiste nel chiamare semplicemente la funzione closesocket al termine del trasferimento dei file anziché basarsi su questi flag.Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 8.1, Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | mswsock.h (includere Mswsock.h) |
| Libreria | Mswsock.lib |
| DLL | Mswsock.dll |