LPFN_TRANSMITPACKETS funzione di callback (mswsock.h)

Articolo
08/25/2023

La funzione TransmitPackets trasmette dati in memoria o dati di file su un socket connesso. La funzione TransmitPackets usa la gestione cache del sistema operativo per recuperare i dati dei file, bloccando la memoria per il tempo minimo necessario per trasmettere e ottenendo una trasmissione efficiente e ad alte prestazioni.

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

Sintassi

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

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

Parametri

hSocket

Handle per il socket connesso da utilizzare nella trasmissione. Anche se il socket non deve essere un circuito orientato alla connessione, la destinazione/peer predefinita deve essere stata stabilita usando la funzione connect, WSAConnect, accept, WSAAccept, AcceptEx o WSAJoinLeaf .

lpPacketArray

Matrice di tipo TRANSMIT_PACKETS_ELEMENT, che descrive i dati da trasmettere.

nElementCount

Numero di elementi in lpPacketArray.

nSendSize

Dimensione, in byte, del blocco di dati utilizzato nell'operazione di invio . Impostare nSendSize su zero per consentire al livello socket di selezionare una dimensione di invio predefinita.

L'impostazione di nSendSize su 0xFFFFFFF consente al chiamante di controllare le dimensioni e il contenuto di ogni richiesta di invio , ottenuto usando il flag TP_ELEMENT_EOP nella matrice TRANSMIT_PACKETS_ELEMENT a cui punta il parametro lpPacketArray . Questa funzionalità è utile per i protocolli di messaggio che applicano limitazioni alle dimensioni delle singole richieste di invio .

lpOverlapped

Puntatore a una struttura OVERLAPPED . Se l'handle del socket specificato nel parametro hSocket è stato aperto come sovrapposto, usare questo parametro per ottenere un'operazione di I/O asincrona (sovrapposta). Gli handle socket vengono aperti come sovrapposti per impostazione predefinita.

dwFlags

Set di flag utilizzati per personalizzare l'elaborazione della funzione TransmitPackets . Nella tabella seguente viene descritto l'uso del parametro dwFlags .

Valore	Significato
TF_DISCONNECT	Avvia una disconnessione a livello di trasporto dopo che tutti i dati del file sono stati accodati per la trasmissione. Si applica solo ai socket orientati alla connessione. Se si specifica questo flag per i socket che non supportano la semantica di disconnessione ,ad esempio i socket di datagrammi, viene generato un errore.
TF_REUSE_SOCKET	Prepara l'handle socket da riutilizzare. Al termine della funzione TransmitPackets , l'handle del socket può essere passato alla funzione AcceptEx . Valido solo quando vengono specificati un socket orientato alla connessione e TF_DISCONNECT. Nota La trasmissione del pacchetto a livello di socket è soggetta al comportamento del trasporto sottostante. Ad esempio, un socket TCP può essere soggetto allo stato di TIME_WAIT TCP, causando il ritardo della chiamata a TransmitPackets .
TF_USE_DEFAULT_WORKER	Indica a Winsock di usare il thread predefinito del sistema per elaborare le richieste TransmitPackets lunghe. Le richieste TransmitPackets lunghe vengono definite come richieste che richiedono più di una sola lettura dal file o da una cache; la definizione di richiesta lunga dipende quindi dalle dimensioni del file e dalla lunghezza specificata del pacchetto di invio. Il thread predefinito del sistema può essere modificato usando il parametro del Registro di sistema seguente come REG_DWORD:HKEY_LOCAL_MACHINE\Parametri\AFD\dei servizi\CurrentControlSet\
TF_USE_SYSTEM_THREAD	Indirizza Winsock all'uso dei thread di sistema per elaborare richieste TransmitPackets lunghe. Le richieste TransmitPackets lunghe vengono definite come richieste che richiedono più di una sola lettura dal file o da una cache; la definizione di richiesta lunga dipende quindi dalle dimensioni del file e dalla lunghezza specificata del pacchetto di invio.
TF_USE_KERNEL_APC	Indica a Winsock di usare le chiamate a procedure asincrone del kernel anziché i thread di lavoro per elaborare richieste TransmitPackets lunghe. Le richieste TransmitPackets lunghe vengono definite come richieste che richiedono più di una sola lettura dal file o da una cache; la definizione di richiesta lunga dipende quindi dalle dimensioni del file e dalla lunghezza specificata del pacchetto di invio. Per ulteriori informazioni, vedere la sezione Osservazioni.

Valore restituito

Se la funzione TransmitPackets ha esito positivo, il valore restituito è TRUE. In caso contrario, il valore restituito è FALSE. Per ottenere informazioni estese sull'errore, 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. In questo caso, le applicazioni devono gestire ERROR_IO_PENDING o WSA_IO_PENDING.

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 lpPacketArray 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 dwFlags ha il flag 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 numero totale di byte da trasmettere è 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 inattiva. 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. Questo errore viene restituito per un socket di flusso in cui la connessione è stata interrotta a causa dell'attività keep-alive che rileva un errore.
WSAENOBUFS	Non è stato possibile eseguire un'operazione su un socket perché il sistema non disponeva di spazio sufficiente nel buffer o perché una coda era piena. Questo errore viene restituito anche se il provider Windows Sockets segnala un deadlock del buffer.
WSAENOTCONN	Una richiesta di invio o ricezione di dati non è consentita perché il socket non è connesso. Questo errore viene restituito per un socket di flusso.
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 un socket di flusso è stato arrestato per l'invio. Non è possibile chiamare TransmitFile su un socket di flusso 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 TransmitPackets è ottimizzata in base al sistema operativo in cui viene usato:

Nelle edizioni di Windows Server la funzione TransmitPackets è ottimizzata per prestazioni elevate.
Nelle edizioni client di Windows la funzione TransmitPackets è ottimizzata per l'utilizzo minimo della memoria e delle risorse.

Il numero massimo di byte che possono essere trasmessi usando una singola chiamata alla funzione TransmitPackets è pari a 2.147.483.646, il valore massimo per un intero a 32 bit meno 1. Se un'applicazione deve trasmettere dati superiori a 2.147.483.646 byte, è possibile usare più chiamate alla funzione TransmitPackets con ogni chiamata che trasferisce non più di 2.147.483.646 byte.

Nota Il puntatore di funzione per la funzione TransmitPackets deve essere ottenuto in fase di esecuzione eseguendo una chiamata alla funzione WSAIoctlcon il SIO_GET_EXTENSION_FUNCTION_POINTER opcode specificato. Il buffer di input passato alla funzione WSAIoctl deve contenere WSAID_TRANSMITPACKETS, un identificatore univoco globale (GUID) il cui valore identifica la funzione di estensione TransmitPackets . In caso di esito positivo, l'output restituito dalla funzione WSAIoctl contiene un puntatore alla funzione TransmitPackets . Il GUID WSAID_TRANSMITPACKETS è definito nel file di intestazione Mswsock.h .

Prevedere risultati migliori sulle prestazioni quando si usa la funzione TransmitPackets in Windows Server 2003.

Quando lpOverlapped non è NULL, l/O sovrapposto potrebbe non terminare prima che la funzione TransmitPackets restituisca. In questo caso, la funzione TransmissionPackets restituisce un errore e una chiamata alla funzione WSAGetLastError restituisce ERROR_IO_PENDING, consentendo al chiamante di continuare l'elaborazione durante il completamento della trasmissione.

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. Per altre informazioni, vedere ExitThread .

Quando la funzione TransmitPackets restituisce TRUE o restituisce FALSE e WSAGetLastError restituisce ERROR_IO_PENDING, Windows imposta l'evento specificato dal membro hEvent della struttura OVERLAPPED o dal socket specificato da hSocket allo stato segnalato e al completamento, recapita la notifica a qualsiasi porta di completamento associata al socket. Usare GetOverlappedResult o WSAGetOverlappedResult o GetQueuedCompletionStatus per recuperare lo stato finale e il numero di byte trasmessi.

TransmitPackets e chiamate di routine asincrone (API)

L'uso del flag di TF_USE_KERNEL_APC può offrire vantaggi significativi sulle prestazioni. Se il thread che avvia la chiamata di funzione TransmitPackets viene usato per calcoli pesanti, è possibile, anche se improbabile, che le API potrebbero non essere avviate.

Nota Esiste una differenza tra le API in modalità kernel e utente:

Le API kernel avviano quando un thread si trova in uno stato di attesa.
Le API in modalità utente avviano quando un thread si trova in uno stato di attesa avvisabile.

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.

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