Funzione TransmitFile (winsock.h)

Articolo
08/27/2023

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.

Nota Questa funzione è un'estensione specifica di Microsoft per la specifica Windows Sockets.

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
TF_DISCONNECT	Avviare una disconnessione a livello di trasporto dopo che tutti i dati dei file sono stati accodati per la trasmissione.
TF_REUSE_SOCKET	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 .
TF_USE_DEFAULT_WORKER	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
TF_USE_SYSTEM_THREAD	Indirizza il provider di servizi Windows Sockets per l'uso dei thread di sistema per elaborare le richieste di TransmitFile lunghe.
TF_USE_KERNEL_APC	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.
TF_WRITE_BEHIND	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
WSAECONNABORTED	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.
WSAECONNRESET	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.
WSAEFAULT	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.
WSAEINVAL	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.
WSAENETDOWN	Un'operazione socket ha rilevato una rete morta. Questo errore viene restituito se il sottosistema di rete non è riuscito.
WSAENETRESET	La connessione è stata interrotta a causa dell'attività keep-alive che rileva un errore durante l'operazione in corso.
WSAENOBUFS	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.
WSAENOTCONN	Richiesta di invio o ricezione dei dati non consentita perché il socket non è connesso.
WSAENOTSOCK	È stata tentata un'operazione su un elemento che non è un socket. Questo errore viene restituito se il parametro hSocket non è un socket.
WSAESHUTDOWN	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 su un socket dopo che la funzione di arresto è stata chiamata sul socket con il parametro impostato su SD_SEND o SD_BOTH.
WSANOTINITIALISED	L'applicazione non ha chiamato la funzione WSAStartup o WSAStartup non è riuscita. Prima di usare la funzione TransmitFile, è necessario che venga eseguita una chiamata WSAStartup riuscita.
WSA_IO_PENDING	È in corso un'operazione di I/O sovrapposta. 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.
WSA_OPERATION_ABORTED	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, dell'esecuzione del comando "SIO_FLUSH" in WSAIoctl o del thread che ha avviato la richiesta sovrapposta è stata chiusa prima del completamento dell'operazione. Nota Tutte le operazioni di I/O avviate da un determinato thread vengono annullate quando il thread viene chiuso. Per i socket sovrapposti, le operazioni asincrone in sospeso possono avere esito negativo se il thread viene chiuso prima del completamento delle operazioni asincrone. Per altre informazioni, vedere ExitThread.

Commenti

La funzione TransmitFile usa il gestore cache del sistema operativo per recuperare i dati del file e fornire il trasferimento dei dati dei file a prestazioni elevate tramite 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 è possibile trasmettere usando una singola chiamata alla funzione TransmitFile è 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 a cui punta il parametro lpTransmitBuffers più il valore specificato nel parametro nNumberOfBytesToWrite per la lunghezza dei dati di file da inviare. Se un'applicazione deve trasmettere un file di dimensioni superiori a 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 perché in questo caso la funzione TransmitFile userà le dimensioni del file come valore per il numero di byte da trasmettere.

Nota Il puntatore di funzione per la funzione TransmitFile deve essere ottenuto in fase di esecuzione effettuando una chiamata alla funzione WSAIoctl con il codice operativo SIO_GET_EXTENSION_FUNCTION_POINTER specificato. Il buffer di input passato alla funzione WSAIoctl deve contenere WSAID_TRANSMITFILE, un GUID (Global Unique Identifier) il cui valore identifica la funzione di estensione TransmitFile . In caso di esito positivo, l'output restituito dalla funzione WSAIoctl contiene un puntatore alla funzione TransmitFile . Il GUID WSAID_TRANSMITFILE è definito nel file di intestazione Mswsock.h .

NotaTransmitFile non è funzionale sui trasporti che eseguono il proprio buffering. I trasporti con il flag TDI_SERVICE_INTERNAL_BUFFERING impostato, ad esempio ADSP, eseguono il proprio buffering. Poiché TransmitFile ottiene i miglioramenti delle prestazioni inviando i dati direttamente dalla cache dei file. I trasporti che esauriscono lo spazio del buffer in una determinata connessione non vengono gestiti da TransmitFile e, in seguito all'esaurimento dello spazio del buffer nella connessione, TransmitFile restituisce STATUS_DEVICE_NOT_READY.

La funzione TransmitFile è stata aggiunta principalmente a Winsock per l'uso da parte di applicazioni server ad alte prestazioni ,ad esempio server Web e ftp.

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 TransmitFile 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 TransmitFile in sospeso; la terza richiesta attenderà il completamento di una delle richieste precedenti.

Le versioni server di Windows ottimizzano la funzione TransmitFile per prestazioni elevate. Nelle versioni del server non sono previsti limiti predefiniti per il numero di operazioni TransmitFile simultanee consentite nel sistema. Quando si usa TransmitFile nelle versioni server di Windows, è previsto un miglioramento delle prestazioni. Nelle versioni server di Windows è possibile impostare un limite per il numero massimo di operazioni TransmitFile simultanee creando una voce del Registro di sistema e impostando un valore per il REG_DWORD seguente:

HKEY_LOCAL_MACHINE\Currentcontrolset\Servizi\AFD\Parametri\MaxActiveTransmitFileCount

Se la funzione TransmitFile viene chiamata con il socket TCP (protocollo di IPPROTO_TCP) con i flag 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 fin dal lato remoto) sul socket TCP sono stati letti.
Il lato remoto ha chiuso la connessione (completata la chiusura normale della connessione TCP).

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 fino a quando non viene inviato il file.

Windows Phone 8: questa funzione è supportata per le app dello Store di Windows Phone 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 utilizzati in un socket in cui è stata richiesta la qualità del servizio, poiché il provider di servizi può eliminare immediatamente qualsiasi qualità del servizio associata 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	winsock.h (include Mswsock.h)
Libreria	Mswsock.lib
DLL	Mswsock.dll