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.

[in] lpvInBuffer

Puntatore al buffer di input.

[in] cbInBuffer

Dimensione, in byte, del buffer di input.

[out] lpvOutBuffer

Puntatore al buffer di output.

[in] cbOutBuffer

Dimensione, 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

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

Valore restituito

Al termine, WSAIoctl restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e è possibile recuperare un codice di errore specifico chiamando WSAGetLastError.

Codice di errore Significato
WSA_IO_PENDING
Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSAENETDOWN
Il sottosistema di rete non è riuscito.
WSAEFAULT
Il parametro lpvInBuffer, lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine non è totalmente contenuto in una parte valida dello spazio indirizzi utente oppure il parametro cbInBuffer o cbOutBuffer è troppo piccolo.
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.
WSAEINPROGRESS
La funzione viene richiamata quando è in corso un callback.
WSAENOTSOCK
Il descrittore s non è un socket.
WSAEOPNOTSUPP
Impossibile realizzare il comando IOCTL specificato. Ad esempio, le strutture FLOWSPEC specificate in SIO_SET_QOS o SIO_SET_GROUP_QOS non possono essere soddisfatte.
WSAEWOULDBLOCK
Il socket è contrassegnato come non bloccanti e l'operazione richiesta blocca.
WSAENOPROTOOPT
L'opzione socket non è supportata nel protocollo specificato. Ad esempio, è stato effettuato un tentativo di usare il SIO_GET_BROADCAST_ADDRESS IOCTL in un socket IPv6 o un tentativo di usare il protocollo TCP SIO_KEEPALIVE_VALS IOCTL su un socket di datagrammi.

Commenti

La funzione WSAIoctl viene usata per impostare o recuperare i 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 un socket non sovrapposto. Per un socket non sovrapposto, i parametri lpOverlapped e lpCompletionRoutine vengono ignorati, causando 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_CHANGE o SIO_ADDRESS_LIST_CHANGE) usando un messaggio di Windows (tramite WSAAsyncSelect)-based o un evento (tramite WSAEventSelect) meccanismo 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 a cui punta 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 a tempo indefinito, a seconda dell'implementazione del provider di servizi. Se l'applicazione non può tollerare il blocco in una chiamata WSAIoctl , è consigliabile che le operazioni di I/O sovrapposte siano consigliate per IOCTL che probabilmente bloccano, 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 IOCTL 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 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 gli opcode ioctlsocket attualmente definiti, fornendo un modo pratico per partizionare lo spazio degli identificatori opcode in quanto il parametro dwIoControlCode è ora un'entità a 32 bit. Il parametro dwIoControlCode viene creato 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 ha il formato seguente.

I 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
 
Nota I bit nel parametro dwIoControlCode visualizzati nella tabella devono essere letti verticalmente dall'alto verso il basso per colonna. Il bit più a sinistra è quindi 31, il bit successivo è 30 e il bit più a destra è 0.
 
Viene impostato se il buffer di input è valido per il codice, come con IOC_IN.

O viene 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 viene 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. Vengono definiti i valori seguenti:

0 IOCTL è un codice IOCTL Unix standard, come con FIONREAD e FIONBIO.

1 L'IOCTL è un codice IOCTL generico di Windows Sockets 2. 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 con IOC_VENDOR. Questo tipo consente alle aziende di assegnare un numero fornitore visualizzato nel parametro Famiglia fornitore/indirizzo . Il fornitore può quindi definire nuovi IOCTLs specifici del fornitore senza dover registrare IOCTL con una clearinghouse, fornendo così flessibilità e privacy dei fornitori.

Famiglia fornitore/indirizzo Quantità a 11 bit che definisce il fornitore che possiede il 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 pari a 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 indicato 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 nell'oggetto evento.

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 .
 
Se lpCompletionRoutine non è NULL, il parametro hEvent viene ignorato e può essere usato dall'applicazione per passare le informazioni di contesto alla routine di completamento. Un chiamante che passa una richiesta non NULLlpCompletionRoutine e versioni successive chiama WSAGetOverlappedResult per la stessa richiesta di I/O sovrapposta potrebbe non impostare il parametro fWait per tale chiamata di WSAGetOverlappedResult su TRUE. In questo caso, l'utilizzo del parametro hEvent non è definito e il tentativo di attendere il parametro hEvent produrrà risultati imprevedibili.

Il prototipo della routine di completamento è il seguente:


void CALLBACK CompletionRoutine(
  IN DWORD dwError, 
  IN DWORD cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD dwFlags 
);

Questo completamentoRoutine è un segnaposto per una funzione definita dall'applicazione o definita dalla libreria. La routine di completamento viene richiamata solo se il thread è in uno stato avvisabile. Per inserire un thread in uno stato avvisabile, 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 vengono definiti valori 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 le operazioni sovrapposte vengono completate.

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.
Nota Alcuni codici IOCTL richiedono file di intestazione aggiuntivi. Ad esempio, l'uso del SIO_RCVALL IOCTL richiede il file di intestazione Mstcpip.h.
 
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

   
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

opzioni socket SOL_SOCKET

WSASocket

Funzioni Winsock

Informazioni di riferimento su Winsock

getsockopt

ioctlsocket

Setsockopt

Socket