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 (ignorata per socket non sovrapposti).

[in] lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Valore restituito

Al termine, il WSAIoctl restituisce zero. In caso contrario, viene restituito un valore di SOCKET_ERROR e un codice di errore specifico può essere recuperato chiamando WSAGetLastError.

Osservazioni

La funzione WSAIoctl viene utilizzata 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, 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 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ò 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 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 il ioctlsocket opcodes 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 consente 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.

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 lpOverlapped contiene l'indirizzo di una struttura di 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.

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