Funzione WSAIoctl (winsock2.h)
La funzione WSAIoctl controlla la modalità di un socket.
Sintassi
int WSAAPI WSAIoctl(
[in] SOCKET s,
[in] DWORD dwIoControlCode,
[in] LPVOID lpvInBuffer,
[in] DWORD cbInBuffer,
[out] LPVOID lpvOutBuffer,
[in] DWORD cbOutBuffer,
[out] LPDWORD lpcbBytesReturned,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
Parametri
[in] s
Descrittore che identifica un socket.
[in] dwIoControlCode
Codice di controllo dell'operazione da eseguire. Vedere Winsock IOCTLs.
[in] lpvInBuffer
Puntatore al buffer di input.
[in] cbInBuffer
Dimensioni, in byte, del buffer di input.
[out] lpvOutBuffer
Puntatore al buffer di output.
[in] cbOutBuffer
Dimensioni, in byte, del buffer di output.
[out] lpcbBytesReturned
Puntatore al numero effettivo di byte di output.
[in] lpOverlapped
Puntatore a una struttura WSAOVERLAPPED (ignorata per socket non sovrapposti).
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valore restituito
Al termine del completamento, WSAIoctl restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.
| Codice di errore | Significato |
|---|---|
| Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento. | |
| Il sottosistema di rete non è riuscito. | |
| Il parametro lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio degli indirizzi utente oppure il parametro cbInBuffer o cbOutBuffer è troppo piccolo. | |
| 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. | |
| La funzione viene richiamata quando un callback è in corso. | |
| Il descrittore s non è un socket. | |
| Impossibile realizzare il comando IOCTL specificato. Ad esempio, le strutture FLOWPEC specificate in SIO_SET_QOS o SIO_SET_GROUP_QOS non possono essere soddisfatte. | |
| Il socket è contrassegnato come non blocca e l'operazione richiesta blocca. | |
| L'opzione socket non è supportata nel protocollo specificato. Ad esempio, un tentativo di usare la SIO_GET_BROADCAST_ADDRESS IOCTL è stato effettuato su un socket IPv6 o su un tentativo di usare il protocollo TCPSIO_KEEPALIVE_VALS IOCTL è stato effettuato in un socket di datagram. |
Commenti
La funzione WSAIoctl viene usata per impostare o recuperare parametri operativi associati al socket, al protocollo di trasporto o al sottosistema di comunicazione.
Se sia lpOverlapped che lpCompletionRoutine sono NULL, il socket in questa funzione verrà considerato come socket non sovrapposto. Per un socket non sovrapposto, i parametri lpOverlapped e lpCompletionRoutine vengono ignorati, che causano il comportamento della funzione come la funzione ioctlsocket standard, ad eccezione del fatto che la funzione può bloccare se socket s è in modalità di blocco. Se socket s è in modalità non bloccabile, questa funzione può restituire WSAEWOULDBLOCK quando l'operazione specificata non può essere completata immediatamente. In questo caso, l'applicazione può modificare il socket in modalità di blocco e riemettere la richiesta o attendere l'evento di rete corrispondente (ad esempio FD_ROUTING_INTERFACE_CHANGE o FD_ADDRESS_LIST_CHANGE nel caso di SIO_ROUTING_INTERFACE_CHANGEo SIO_ADDRESS_LIST_CHANGE) usando un messaggio di Windows (usando WSAAsyncSelect)-based o evento (usando il meccanismo di notifica basato su WSAEventSelect).
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 fa riferimento il parametro lpcbBytesReturned restituito può essere ignorato. Lo stato di completamento finale e i byte restituiti possono essere recuperati quando il metodo di completamento appropriato viene segnalato al termine dell'operazione.
Qualsiasi IOCTL può bloccare in modo indefinito, a seconda dell'implementazione del provider di servizi. Se l'applicazione non può tollerare il blocco in una chiamata WSAIoctl , l'I/O sovrapposto dovrebbe essere consigliato per IOCTLs che sono particolarmente probabile bloccare, tra cui:
SIO_ADDRESS_LIST_CHANGE
SIO_FINDROUTE
SIO_FLUSH
SIO_GET_QOS
SIO_GET_GROUP_QOS
SIO_ROUTING_INTERFACE_CHANGE
SIO_SET_QOS
SIO_SET_GROUP_QOS
Alcuni IOCTLs specifici del protocollo possono anche essere particolarmente probabili da bloccare. Controllare l'allegato specifico del protocollo pertinente per eventuali informazioni disponibili.
Il prototipo della routine di completamento a cui punta il parametro lpCompletionRoutine è il seguente:
#ifndef UNICODE
#define UNICODE
#endif
#define WIN32_LEAN_AND_MEAN
#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>
// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")
void CALLBACK CompletionRoutine (
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Il completamentoRoutine è un segnaposto per un nome di funzione fornito dall'applicazione. Il parametro dwError specifica lo stato di completamento dell'operazione sovrapposta, come indicato dal parametro lpOverlapped . Il parametro cbTransferred specifica il numero di byte ricevuti. Il parametro dwFlags non viene usato per questo IOCTL. La routine di completamento non restituisce un valore.
È possibile adottare uno schema di codifica che mantiene i codici opcode ioctlsocket attualmente definiti, fornendo un modo pratico per partizionare lo spazio dell'identificatore opcode in quanto il parametro dwIoControlCode è ora un'entità a 32 bit. Il parametro dwIoControlCode viene compilato per consentire l'indipendenza del protocollo e del fornitore quando si aggiungono nuovi codici di controllo mantenendo la compatibilità con le versioni precedenti con i codici di controllo Windows Sockets 1.1 e Unix. Il parametro dwIoControlCode contiene il modulo seguente.
| I | O | V | T | Famiglia di fornitori/indirizzi | Codice |
|---|---|---|---|---|---|
| 3 | 3 | 2 | 2 2 | 2 2 2 2 2 2 2 1 1 1 1 | 1 1 1 1 1 1 |
| 1 | 0 | 9 | 8 7 | 6 5 4 3 2 1 0 9 8 7 6 | 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 |
O è impostato se il buffer di output è valido per il codice, come con IOC_OUT. I codici di controllo che usano sia i buffer di input che di output impostano sia I che O.
V è impostato se non sono presenti parametri per il codice, come con IOC_VOID.
T è una quantità a 2 bit che definisce il tipo di IOCTL. I valori seguenti sono definiti:
0 IOCTL è un codice IOCTL Unix standard, come con FIONREAD e FIONBIO.
1 IOCTL è un codice IOCTL Windows Sockets 2 generico. I nuovi codici IOCTL definiti per Windows Sockets 2 avranno T == 1.
2 L'IOCTL si applica solo a una famiglia di indirizzi specifica.
3 L'IOCTL si applica solo al provider di un fornitore specifico, come per IOC_VENDOR. Questo tipo consente alle aziende di assegnare un numero fornitore visualizzato nel parametro della famiglia Fornitore/Indirizzo . Quindi, il fornitore può definire nuovi IOCTL specifici di tale fornitore senza dover registrare IOCTL con una clearinghouse, fornendo così flessibilità e privacy del fornitore.
Famiglia fornitore/indirizzo Quantità a 11 bit che definisce il fornitore proprietario del codice (se T == 3) o che contiene la famiglia di indirizzi a cui si applica il codice (se T == 2). Se si tratta di un codice IOCTL Unix (T == 0), questo parametro ha lo stesso valore del codice in Unix. Se si tratta di un generico IOCTL (T == 1) di Windows Sockets 2, questo parametro può essere usato come estensione del parametro di codice per fornire valori di codice aggiuntivi.
Codice Quantità a 16 bit che contiene il codice IOCTL specifico per l'operazione.
Sono supportati i seguenti codici IOCTL Unix (comandi).
Sono supportati i comandi di Windows Sockets 2 seguenti.
Se un'operazione sovrapposta viene completata immediatamente, WSAIoctl restituisce un valore zero e il parametro lpcbBytesReturned viene aggiornato con il numero di byte nel buffer di output. Se l'operazione sovrapposta viene avviata correttamente e verrà completata in un secondo momento, questa funzione restituisce SOCKET_ERROR e indica il codice di errore WSA_IO_PENDING. In questo caso , lpcbBytesReturned non viene aggiornato. Quando l'operazione sovrapposta completa la quantità di dati nel buffer di output viene indicata tramite il parametro cbTransferred nella routine di completamento (se specificato) o tramite il parametro lpcbTransfer in WSAGetOverlappedResult.
Quando viene chiamato con un socket sovrapposto, il parametro lpOverlapped deve essere valido per la durata dell'operazione sovrapposta. Il parametro lpOverlapped contiene l'indirizzo di una struttura WSAOVERLAPPED .
Se il parametro lpCompletionRoutine è NULL, il parametro hEvent di lpOverlapped viene segnalato quando l'operazione sovrapposta viene completata se contiene un handle di oggetto evento valido. Un'applicazione può usare WSAWaitForMultipleEvents o WSAGetOverlappedResult per attendere o eseguire il polling sull'oggetto evento.
Il prototipo della routine di completamento è il seguente:
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Questa CompletionRoutine è un segnaposto per una funzione definita dall'applicazione o definita dalla libreria. La routine di completamento viene richiamata solo se il thread si trova in uno stato di avviso. Per inserire un thread in uno stato di avviso, usare la funzione WSAWaitForMultipleEvents, WaitForSingleObjectEx o WaitForMultipleObjectsEx con il parametro fAlertable o bAlertable impostato su TRUE.
Il parametro dwError di CompletionRoutine specifica lo stato di completamento per l'operazione sovrapposta, come indicato da lpOverlapped. Il parametro cbTransferred specifica il numero di byte restituiti. Attualmente non sono definiti valori di flag e dwFlags sarà zero. La funzione CompletionRoutine non restituisce un valore.
La restituzione da questa funzione consente la chiamata di un'altra routine di completamento in sospeso per questo socket. Le routine di completamento possono essere chiamate in qualsiasi ordine, non necessariamente nello stesso ordine in cui vengono completate le operazioni sovrapposte.
Compatibilità
I codici IOCTL con T == 0 sono un subset dei codici IOCTL usati nei socket Berkeley. In particolare, non esiste alcun comando equivalente a FIOASYNC.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 | winsock2.h |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |
Vedi anche
Commenti e suggerimenti
Presto disponibile: nel corso del 2024 verranno dismessi i problemi di GitHub come meccanismo di feedback per il contenuto e verranno sostituiti con un nuovo sistema di feedback. Per altre informazioni, vedere: https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per