codice di controllo SIO_APPLY_TRANSPORT_SETTING
Descrizione
Il codice di controllo SIO_APPLY_TRANSPORT_SETTING applica una o più impostazioni di trasporto a un socket.
Per eseguire questa operazione, chiamare la funzione WSAIoctl o WSPIoctl con i parametri seguenti.
int WSAIoctl(
(socket) s, // descriptor identifying a socket
SIO_APPLY_TRANSPORT_SETTING, // dwIoControlCode
(LPVOID) lpvInBuffer, // pointer to the input buffer
(DWORD) cbInBuffer, // size, in bytes, of the input buffer
(LPVOID) lpvOutBuffer, // pointer to the output buffer
(DWORD) cbOutBuffer, // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING, // dwIoControlCode
(LPVOID) lpvInBuffer, // pointer to the input buffer
(DWORD) cbInBuffer, // size, in bytes, of the input buffer
(LPVOID) lpvOutBuffer, // pointer to the output buffer
(DWORD) cbOutBuffer, // size, in bytes, of the 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_APPLY_TRANSPORT_SETTING per questa operazione.
lpvInBuffer
Puntatore al buffer di input. Questo parametro contiene un puntatore a una struttura in cui il primo membro della struttura è una struttura TRANSPORT_SETTING_ID che determina quale impostazione di trasporto viene applicata.
cbInBuffer
Dimensione, in byte, del buffer di input. Questo parametro dipende dall'impostazione del trasporto da applicare.
lpvOutBuffer
Puntatore al buffer di output. Questo parametro dipende dall'impostazione del trasporto da applicare.
cbOutBuffer
Dimensione, in byte, del buffer di output.
lpcbBytesReturned
Puntatore a una variabile che riceve le dimensioni, in byte, dei dati archiviati nel buffer di output.
Se il buffer di output è troppo piccolo, la chiamata non riesce, WSAGetLastErrorrestituisce WSAEINVAL e il parametro lpcbBytesReturned punta a un valore DWORD pari a zero.
Se lpOverlapped è NULL, il valore DWORD a cui punta il parametro lpcbBytesReturned restituito in una chiamata riuscita non può essere zero.
Se il parametro lpOverlapped non è NULL per i socket sovrapposti, le operazioni che non possono essere completate immediatamente verranno avviate e il completamento verrà indicato in un secondo momento. Il valore DWORD a cui punta il parametro lpcbBytesReturned restituito può essere zero perché le dimensioni dei dati archiviati non possono essere determinate fino al completamento dell'operazione sovrapposta. Lo stato di completamento finale può essere recuperato quando viene segnalato il metodo di completamento appropriato al termine dell'operazione.
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 a cui si fa 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 | L'operazione di I/O sovrapposta è in corso. Questo valore viene restituito se un'operazione sovrapposta è stata avviata correttamente e 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 un'operazione sovrapposta è stata annullata a causa della chiusura del socket o dell'esecuzione del comando IOCTL SIO_FLUSH . |
| WSAEFAULT | Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un argomento puntatore in una chiamata. Questo errore viene restituito del parametro lpvInBuffer, lpvoutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine non è completamente contenuto in una parte valida dello spazio indirizzi utente. |
| WSAEINPROGRESS | È in corso un'operazione di blocco. Questo errore viene restituito se la funzione viene richiamata quando è in corso un callback. |
| WSAEINTR | Un'operazione di blocco è stata interrotta da una chiamata a WSACancelBlockingCall. Questo errore viene restituito se un'operazione di blocco è stata interrotta. |
| WSAEINVAL | Argomento fornito non valido. Questo errore viene restituito se 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. |
| WSAENETDOWN | Rete inattiva rilevata durante l'operazione del socket. Questo errore viene restituito se il sottosistema di rete non è riuscito. |
| WSAENOTSOCK | È stata tentata un'operazione su un elemento che non è un socket. Questo errore viene restituito se il descrittore s non è un socket. |
| WSAEOPNOTSUPP | L'operazione tentata non è supportata per il tipo di oggetto a cui si fa riferimento. Questo errore viene restituito se il comando IOCTL specificato non è supportato. Questo errore viene restituito anche se il SIO_APPLY_TRANSPORT_SETTING IOCTL non è supportato dal provider di trasporto. Questo errore viene restituito anche quando viene eseguito un tentativo di utilizzo del SIO_APPLY_TRANSPORT_SETTING IOCTL su un socket diverso da UDP o TCP. |
Commenti
Il SIO_APPLY_TRANSPORT_SETTING IOCTL è supportato in Windows 8 e Windows Server 2012 e versioni successive del sistema operativo.
Il SIO_APPLY_TRANSPORT_SETTING IOCTL è un IOCTL generico usato per applicare l'impostazione di trasporto al socket. L'impostazione di trasporto applicata è basata sul TRANSPORT_SETTING_ID passato nel parametro lpvInBuffer .
A partire da Windows 8 e Windows Server 2012, il sistema definisce la funzionalità di REAL_TIME_NOTIFICATION_CAPABILITY su un socket TCP. A partire da Windows 10 e Windows Server 2016, viene definito anche ASSOCIATE_NAMERES_CONTEXT. Per altre informazioni, vedere addrinfoex4 e ASSOCIATE_NAMERES_CONTEXT_INPUT.
Se il TRANSPORT_SETTING_ID passato nel parametro lpvInBuffer ha il membro Guid impostato su REAL_TIME_NOTIFICATION_CAPABILITY, si tratta di una richiesta di applicare le impostazioni di notifica in tempo reale per il socket TCP usato con ControlChannelTrigger per ricevere notifiche di rete in background in un'app di Windows Store. Il parametro lpvInBuffer deve puntare a una struttura REAL_TIME_NOTIFICATION_SETTING_INPUT . Il parametro lpvOutBuffer non è usato per questa operazione. Questa impostazione di trasporto si applica solo ai socket TCP. Questa impostazione di trasporto consente a WinInet o a servizi di rete simili di contrassegnare un determinato socket TCP come ControlChannelTrigger abilitato. Windows contrassegnerà il socket TCP corrispondente e configurerà le impostazioni hardware e software appropriate quando questa opzione viene chiamata. Un'app di Windows Store non chiamerà direttamente questo IOCTL.