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 IOCTLs Winsock.
[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
[in] lpCompletionRoutine
Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
Valore restituito
Al termine, il WSAIoctl
| 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 lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlappedo lpCompletionRoutine parametro non è completamente contenuto in una parte valida dello spazio indirizzi utente, o il parametro cbInBuffer o cbOutBuffer è troppo piccolo. | |
|
Il parametro dwIoControlCode |
|
| La funzione viene richiamata quando è in corso un callback. | |
| Il descrittore non è un socket. | |
|
Impossibile realizzare il comando IOCTL specificato. Ad esempio, le strutture |
|
| Il socket è contrassegnato come non bloccanti e l'operazione richiesta viene bloccata. | |
| L'opzione socket non è supportata nel protocollo specificato. Ad esempio, è stato effettuato un tentativo di usare il SIO_GET_BROADCAST_ADDRESS IOCTL su un socket IPv6 o un tentativo di usare tcp SIO_KEEPALIVE_VALS IOCTL su un socket di datagram. |
Osservazioni
La funzione WSAIoctl
Se sia lpOverlapped che lpCompletionRoutine sono NULL, il socket in questa funzione verrà considerato come un socket non sovrapposto. Per un socket non sovrapposto, lpOverlapped e i parametri lpCompletionRoutine, il che fa sì che la funzione si comporti come lo standard funzione ioctlsocket, ad eccezione del fatto che la funzione può bloccare se il socket è in modalità di blocco. Se il socket è 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 nuovamente 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_CHANGE o SIO_ADDRESS_LIST_CHANGE) usando un messaggio di Windows (usando WSAAsyncSelect)-based o evento (usando WSAEventSelectmeccanismo di notifica basato su ).
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
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 un WSAIoctl chiamata, è consigliabile usare operazioni di I/O sovrapposte per IOCTLs che sono particolarmente probabili blocchi, 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 per la 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
);
CompletionRoutine è un segnaposto per un nome di funzione fornito dall'applicazione. Il parametro dwError specifica lo stato di completamento per l'operazione sovrapposta, come indicato da parametro lpOverlapped. Il parametro cbTransferred
È possibile adottare uno schema di codifica che mantiene il
| Io | O | V | T | Famiglia fornitore/indirizzo | 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 per 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. Sono definiti i valori seguenti:
0 IOCTL è un codice IOCTL Unix standard, come per 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 essere assegnati un numero fornitore visualizzato nel parametro famiglia fornitore/indirizzo. Il fornitore può quindi definire nuovi IOCTL specifici del fornitore senza dover registrare IOCTL con una clearinghouse, offrendo così flessibilità e privacy del fornitore.
famiglia fornitore/indirizzo Una 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 Windows Sockets 2 IOCTL (T == 1), 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
Se il parametro
Il prototipo della routine di completamento è il seguente:
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
Questo 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
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
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 di 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.
Fabbisogno
| 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 | Finestre |
| intestazione |
winsock2.h |
| libreria |
Ws2_32.lib |
| dll | Ws2_32.dll |
Vedere anche
opzioni socket