codice di controllo SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE

Articolo
10/11/2023

Descrizione

Il codice di controllo SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE notifica a un'applicazione quando il valore del backlog di invio ideale (ISB) cambia per la connessione.

Per eseguire questa operazione, chiamare la funzione WSAIoctl o WSPIoctl con i parametri seguenti.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_IDEAL_SEND_BACKLOG_CHANGE, // dwIoControlCode
  NULL,                         // lpvInBuffer
  0,                            // cbInBuffer
  NULL,         // output buffer
  0,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parametri

s

Descrittore che identifica un socket.

dwIoControlCode

Codice di controllo per l'operazione. Usare SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE per questa operazione.

lpvInBuffer

Puntatore al buffer di input. Questo parametro non è usato per questa operazione.

cbInBuffer

Dimensioni, in byte, del buffer di input. Questo parametro non è usato per questa operazione.

lpvOutBuffer

Puntatore al buffer di output. Questo parametro non è usato per questa operazione.

cbOutBuffer

Dimensioni, in byte, del buffer di output. Questo parametro deve essere impostato su zero.

lpcbBytesReturned

Puntatore a una variabile che riceve le dimensioni, in byte, dei dati archiviati nel buffer di output. Questo parametro restituito punta a un valore DWORD pari a zero per questa operazione, poiché non è presente alcun output.

lpvOverlapped

Puntatore a una struttura WSAOVERLAPPED.

Se socket s è stato creato senza l'attributo sovrapposto, il parametro lpOverlapped viene ignorato.

Se s è stato aperto con l'attributo sovrapposto e il parametro lpOverlapped non è NULL, l'operazione viene eseguita come operazione sovrapposta (asincrona). In questo caso, il parametro lpOverlapped deve puntare a una struttura WSAOVERLAPPED valida.

Per le operazioni sovrapposte, la funzione WSAIoctl o WSPIoctl restituisce immediatamente e il metodo di completamento appropriato viene segnalato al termine dell'operazione. In caso contrario, la funzione non restituisce finché l'operazione non è stata completata o si verifica un errore.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntatore alla routine di completamento chiamata quando l'operazione è stata completata (ignorata per socket non sovrapposti).

lpThreadId

Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID di riferimento (non il puntatore allo stesso) fino a quando non viene restituita la funzione WPUQueueApc.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

lpErrno

Puntatore al codice di errore.

Nota Questo parametro si applica solo alla funzione WSPIoctl .

Valore restituito

Se l'operazione viene completata correttamente, la funzione WSAIoctl o WSPIoctl restituisce zero.

Se l'operazione ha esito negativo o è in sospeso, la funzione WSAIoctl o WSPIoctl restituisce SOCKET_ERROR. Per ottenere informazioni estese sull'errore, chiamare WSAGetLastError.

Codice di errore	Significato
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSA_OPERATION_ABORTED	Un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando IOCTL SIO_FLUSH .
WSAEFAULT	Il parametro lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio indirizzi utente.
WSAEINPROGRESS	La funzione viene richiamata quando è in corso un callback.
WSAEINTR	Un'operazione di blocco è stata interrotta.
WSAEINVAL	Il parametro dwIoControlCode non è un comando valido o un parametro di input specificato non è accettabile oppure il comando non è applicabile al tipo di socket specificato. Questo errore viene restituito se il parametro cbOutBuffer non è zero.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOPROTOOPT	L'opzione socket non è supportata nel protocollo specificato.
WSAENOTCONN	Il socket s non è connesso.
WSAENOTSOCK	Il descrittore s non è un socket.
WSAEOPNOTSUPP	Il comando IOCTL specificato non è supportato. Questo errore viene restituito se il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL non è supportato dal provider di trasporto. Questo errore viene restituito anche quando viene eseguito un tentativo di utilizzare il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL in un socket di datagrammi.

Osservazioni:

Il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL è supportato in Windows Server 2008, Windows Vista con Service Pack 1 (SP1) e versioni successive del sistema operativo.

Quando si inviano dati tramite una connessione TCP usando i socket Windows, è importante mantenere una quantità sufficiente di dati in sospeso (inviati ma non ancora riconosciuti) in TCP per ottenere la velocità effettiva più elevata. Il valore ideale per la quantità di dati in sospeso per ottenere la massima velocità effettiva per la connessione TCP è detta dimensione ideale di backlog di invio (ISB). Il valore ISB è una funzione del prodotto in ritardo della larghezza di banda della connessione TCP e della finestra di ricezione pubblicizzata del ricevitore (e in parte della quantità di congestione nella rete).

Il valore ISB per connessione è disponibile dall'implementazione del protocollo TCP in Windows Server 2008, Windows Vista con SP1 e versioni successive del sistema operativo. Il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL può essere usato da un'applicazione per ricevere una notifica quando il valore ISB cambia in modo dinamico per una connessione.

In Windows Server 2008, Windows Vista con SP1 e versioni successive del sistema operativo, le SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE e le SIO_IDEAL_edizione StandardND_BACKLOG_QUERY IOCTLs sono supportate nei socket orientati ai flussi che si trovano in uno stato connesso.

L'intervallo per il valore ISB per una connessione TCP può variare teoricamente da 0 a un massimo di 16 megabyte.

Vedere la pagina di riferimento SIO_IDEAL_edizione StandardND_BACKLOG_QUERY IOCTL per l'uso tipico del meccanismo ISB per ottenere una migliore velocità effettiva rispetto alle connessioni prodotto con ritardo della larghezza di banda elevata.

Il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL è consentito solo in un socket di flusso nello stato connesso. In caso contrario, la funzione WSAIoctl o WSPIoctl avrà esito negativo con WSAENOTCONN.

Il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL non usa buffer di input o output e pend o blocchi fino a quando non si verifica una modifica ISB sulla connessione sottostante. Al termine di questo IOCTL, un'applicazione Winsock può usare il SIO_IDEAL_edizione StandardND_BACKLOG_QUERY IOCTL per recuperare il nuovo valore ISB nella connessione.

Il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL non supporta la modalità non bloccante. Un'applicazione può rilasciare questo IOCTL in un socket non bloccante, ma IOCTL semplicemente bloccherà o penderà fino a quando il valore ISB non cambia.

Se entrambi i parametri lpOverlapped e lpCompletionRoutine sono NULL, il socket in questa funzione verrà considerato come un socket non sovrapposto. Per un socket non sovrapposto, i parametri lpOverlapped e lpCompletionRoutine vengono ignorati, ad eccezione del fatto che la funzione può bloccare se socket s è in modalità di blocco. Se socket s è in modalità non bloccante, questa funzione continuerà a bloccarsi perché questo particolare IOCTL non supporta la modalità non bloccante.

Per i socket sovrapposti, le operazioni che non possono essere completate immediatamente verranno avviate e il completamento verrà indicato in un secondo momento.

Qualsiasi IOCTL può bloccarsi per un periodo illimitato, a seconda dell'implementazione del provider di servizi. Se l'applicazione non può tollerare il blocco in una chiamata di funzione WSAIoctl o WSPIoctl , è consigliabile usare I/O sovrapposti per IOCTLs che sono particolarmente probabili blocchi.

Il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL fornisce una notifica ed è previsto che venga bloccata o bloccata fino a quando il valore ISB non cambia. In genere viene chiamato in modo asincrono con il parametro lpOverlapped impostato su una struttura WSAOVERLAPPED valida.

L'SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL può avere esito negativo con WSAEINTR o WSA_OPERATION_ABORTED nei casi seguenti:

La connessione TCP viene disconnessa normalmente nella direzione di invio. Ciò può verificarsi come risultato di una chiamata alla funzione di arresto con il parametro impostato su SD_edizione Standard ND, una chiamata alla funzione DisconnectEx o una chiamata alla funzione TransmitFile o TransmitPackets con il parametro dwFlags impostato su TF_DISCONNECT o TF_REUedizione Standard.
La connessione TCP è stata reimpostata o interrotta.
L'applicazione emette un SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL quando è già presente una richiesta di notifica con penna. È consentita una sola richiesta di SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE pended alla volta.
La richiesta viene annullata da Gestione I/O.
Il socket è chiuso.

Due funzioni wrapper inline per questi IOCTL sono definite nel file di intestazione Ws2tcpip.h . È consigliabile usare queste funzioni inline anziché usare direttamente le SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE e SIO_IDEAL_edizione StandardND_BACKLOG_QUERY IOCTLs.

La funzione wrapper inline per il SIO_IDEAL_edizione StandardND_BACKLOG_CHANGE IOCTL è la funzione idealsendbacklognotify.

La funzione wrapper inline per il SIO_IDEAL_edizione StandardND_BACKLOG_QUERY IOCTL è la funzione idealsendbacklogquery.