Funzione di callback LPWSPIOCTL (ws2spi.h)

Articolo
08/28/2023

La funzione LPWSPIoctl controlla la modalità di un socket.

Sintassi

LPWSPIOCTL Lpwspioctl;

int Lpwspioctl(
  [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,
  [in]  LPWSATHREADID lpThreadId,
  [in]  LPINT lpErrno
)
{...}

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

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

[in] lpThreadId

Puntatore a una struttura WSATHREADID da usare dal provider in una chiamata successiva a WPUQueueApc. Il provider deve archiviare la struttura WSATHREADID di riferimento (non il puntatore) fino a quando non viene restituita la funzione WPUQueueApc .

[in] lpErrno

Puntatore al codice di errore.

Valore restituito

Se non si verifica alcun errore e l'operazione è stata completata immediatamente, LPWSPIoctl restituisce zero. Si noti che in questo caso la routine di completamento, se specificata, sarà già stata accodata. In caso contrario, viene restituito un valore di SOCKET_ERROR e in lpErrno è disponibile un codice di errore specifico. Il codice di errore WSA_IO_PENDING indica che un'operazione sovrapposta è stata avviata correttamente e che il completamento verrà indicato in un secondo momento. Qualsiasi altro codice di errore indica che non è stata avviata alcuna operazione sovrapposta e che non si verificherà alcuna indicazione di completamento.

Codice di errore	Significato
WSA_IO_PENDING	Un'operazione sovrapposta è stata avviata correttamente e il completamento verrà indicato in un secondo momento.
WSAEFAULT	Il parametro lpvInBuffer, lpvOutBuffer o lpcbBytesReturned non è totalmente contenuto in una parte valida dello spazio indirizzi utente oppure il parametro cbInBuffer o cbOutBuffer è troppo piccolo.
WSAEINVAL	DwIoControlCode non è un comando valido o un parametro di input fornito non è accettabile oppure il comando non è applicabile al tipo di socket fornito.
WSAEINPROGRESS	La funzione viene richiamata quando è in corso un callback.
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAENOTSOCK	Il descrittore s non è un socket.
WSAEOPNOTSUPP	Impossibile realizzare il comando IOCTL specificato. Ad esempio, le specifiche del flusso specificate in SIO_SET_QOS non possono essere soddisfatte.
WSAEWOULDBLOCK	Il socket è contrassegnato come non bloccante e l'operazione richiesta blocca.

Commenti

Questa routine 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 i socket non sovrapposti, i parametri lpOverlapped e lpCompletionRoutine vengono ignorati e questa funzione può bloccare se socket s è in modalità di blocco. Si noti che se socket s è in modalità non bloccante, questa funzione può restituire WSAEWOULDBLOCK se l'operazione specificata non può essere completata immediatamente. In questo caso, il client SPI di Windows Sockets 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 in caso di SIO_ROUTING_INTERFACE_CHANGE o SIO_ADDRESS_LIST_CHANGE) usando il messaggio di Windows (tramite LPWSPAsyncSelect o evento (tramite LPWSPEventSelect) 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ò bloccarsi a tempo indefinito, a seconda dell'implementazione del provider di servizi. Se il client SPI Windows Sockets non può tollerare il blocco in una chiamata LPWSPIoctl , è consigliabile usare I/O sovrapposti per IOCTLs 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. Per informazioni disponibili, vedere l'allegato specifico del protocollo pertinente.

Il prototipo della routine di completamento a cui punta il parametro lpCompletionRoutine è il seguente.

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.

In quanto il parametro dwIoControlCode è ora un'entità a 32 bit, è possibile adottare uno schema di codifica che offre un modo pratico per partizionare lo spazio identificatore opcode. Il parametro dwIoControlCode viene costruito 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.

bit 31	bit 30	bit 29	bit 28 e 27	bit da 26 a 16 bit	bit da 15 a 0
I	O	V	T	Famiglia fornitore/indirizzo	Codice

Viene impostato se il buffer di input è valido per il codice, come per IOC_IN.

O viene impostato se il buffer di output è valido per il codice, come per IOC_OUT. Si noti che per i codici con parametri di input e output, verranno impostati sia I che O .

V viene impostato se non sono presenti parametri per il codice, come con IOC_VOID.

T è una quantità a due bit che definisce il tipo di IOCTL. Vengono definiti i valori seguenti.

0 indica che IOCTL è un codice IOCTL UNIX standard, come per FIONREAD, FIONBIO e così via.
1 indica che IOCTL è un codice IOCTL Windows Sockets 2 generico. I nuovi codici IOCTL definiti per Windows Sockets 2 avranno T == 1.
2 indica che L'IOCTL si applica solo a una famiglia di indirizzi specifica.
3 L'IOCTL si applica solo a un fornitore specifico. Questo tipo consente alle aziende di essere assegnati un numero fornitore visualizzato nel membro 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.

La 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 membro ha lo stesso valore del codice in UNIX. Se si tratta di un IOCTL (T == 1) Windows Sockets 2 generico, questo membro può essere usato come estensione del membro di codice per fornire valori di codice aggiuntivi.

Il codice è il codice IOCTL specifico per l'operazione.

Sono supportati i comandi UNIX seguenti:

FIONBIO

Abilita o disabilita la modalità di non blocco nel socket s. Il parametro lpvInBuffer punta a un valore long senza segno, che è diverso da zero se la modalità di non blocco deve essere abilitata e zero se deve essere disabilitata. Quando viene creato un socket, funziona in modalità di blocco , ovvero la modalità non bloccante è disabilitata. Ciò è coerente con i socket di Berkeley Software Distribution (BSD).

La routine LPWSPAsyncSelect o LPWSPEventSelect imposta automaticamente un socket in modalità non bloccante. Se LPWSPAsyncSelect o LPWSPEventSelect è stato emesso su un socket, qualsiasi tentativo di usare LPWSPIoctl per impostare di nuovo il socket sulla modalità di blocco avrà esito negativo con WSAEINVAL. Per ripristinare la modalità di blocco del socket, un client SPI di Windows Sockets deve prima disabilitare LPWSPAsyncSelect chiamando LPWSPAsyncSelect con il parametro lEvent uguale a zero oppure disabilitare LPWSPEventSelect chiamando LPWSPEventSelect con il parametro lNetworkEvents uguale a zero.

FIONREAD

Determinare la quantità di dati che possono essere letti in modo atomico dal socket s. Il parametro lpvOutBuffer punta a un long senza segno in cui WSAIoctl archivia il risultato.

Se il socket passato nel parametro s è orientato al flusso (ad esempio, tipo SOCK_STREAM), FIONREAD restituisce la quantità totale di dati che possono essere letti in una singola operazione di ricezione; si tratta in genere della quantità totale di dati accodati sul socket (poiché un flusso di dati è orientato ai byte, questo non è garantito).

Se il socket passato nel parametro s è orientato ai messaggi (ad esempio, tipo SOCK_DGRAM), FIONREAD restituisce il numero totale di byte disponibili per la lettura, non le dimensioni del primo datagramma (messaggio) accodato sul socket.

SIOCATMARK

Determina se tutti i dati OOB sono stati letti o meno. Questo vale solo per un socket di stile di flusso (ad esempio, tipo SOCK_STREAM) configurato per la ricezione inline di qualsiasi dati OOB (SO_OOBINLINE). Se non è in attesa di lettura alcun dato OOB, l'operazione restituisce TRUE. In caso contrario, restituisce FALSE e l'operazione di ricezione successiva eseguita sul socket recupererà alcuni o tutti i dati precedenti al contrassegno; Il client SPI Windows Sockets deve usare l'operazione SIOCATMARK per determinare se rimane. Se sono presenti dati normali che precedono i dati urgenti (OOB), verranno ricevuti in ordine. Si noti che le operazioni di ricezione non combinano mai dati OOB e normali nella stessa chiamata. lpvOutBuffer punta a un valore BOOL in cui LPWSPIoctl archivia il risultato.

Sono supportati i comandi di Windows Sockets 2 seguenti:

SIO_ACQUIRE_PORT_RESERVATION (impostazione opcode: I, T==3)

Richiedere una prenotazione di runtime per un blocco di porte TCP o UDP. Per le prenotazioni delle porte di runtime, il pool di porte richiede che le prenotazioni vengano utilizzate dal processo in cui è stata concessa la prenotazione. Le prenotazioni delle porte di runtime durano solo a condizione che sia stata chiamata la durata del socket in cui è stato chiamato il SIO_ACQUIRE_PORT_RESERVATION IOCTL. Al contrario, le prenotazioni di porta persistenti create usando createPersistentTcpPortReservation o CreatePersistentUdpPortReservation possono essere utilizzate da qualsiasi processo con la possibilità di ottenere prenotazioni persistenti.

Per informazioni più dettagliate, vedere le informazioni di riferimento sul SIO_ACQUIRE_PORT_RESERVATION .

SIO_ACQUIRE_PORT_RESERVATION è supportato in Windows Vista e versioni successive del sistema operativo.

SIO_ADDRESS_LIST_CHANGE (impostazione opcode: T==1)

Per ricevere una notifica delle modifiche nell'elenco degli indirizzi di trasporto locali della famiglia di protocolli del socket a cui è possibile associare il client SPI Windows Sockets. Nessuna informazione di output verrà fornita al completamento di questo IOCTL; il completamento indica semplicemente che l'elenco degli indirizzi locali disponibili è stato modificato e deve essere nuovamente sottoposto a query tramite SIO_ADDRESS_LIST_QUERY.

Si presuppone (anche se non obbligatorio) che il client SPI di Windows Sockets usi operazioni di I/O sovrapposte per ricevere una notifica di modifica al completamento della richiesta di SIO_ADDRESS_LIST_CHANGE . In alternativa, se il SIO_ADDRESS_LIST_CHANGE IOCTL viene emesso su un socket non bloccante e senza parametri sovrapposti (lpOverlapped e lpCompletionRoutine sono impostati su NULL), verrà completato immediatamente con l'errore WSAEWOULDBLOCK. Il client SPI Di Windows Sockets può quindi attendere gli eventi di modifica dell'elenco di indirizzi tramite una chiamata a LPWSPEventSelect o LPWSPAsyncSelect con il bit FD_ADDRESS_LIST_CHANGE impostato nella maschera di bit dell'evento di rete.

SIO_ADDRESS_LIST_QUERY (impostazione opcode: O, T==1)

Ottiene un elenco di indirizzi di trasporto locali della famiglia di protocolli del socket a cui l'applicazione può associare. L'elenco degli indirizzi varia in base alla famiglia di indirizzi e alcuni indirizzi vengono esclusi dall'elenco.

Nota

Negli ambienti Plug-n-Play di Windows gli indirizzi possono essere aggiunti e rimossi in modo dinamico. Pertanto, le applicazioni non possono basarsi sulle informazioni restituite da SIO_ADDRESS_LIST_QUERY per essere persistenti. Le applicazioni possono registrarsi per le notifiche di modifica degli indirizzi tramite il SIO_ADDRESS_LIST_CHANGE IOCTL che fornisce la notifica tramite un evento di I/O sovrapposto o FD_ADDRESS_LIST_CHANGE. La sequenza di azioni seguente può essere usata per garantire che l'applicazione abbia sempre informazioni sull'elenco indirizzi corrente:

Problema SIO_ADDRESS_LIST_CHANGE IOCTL
Problema SIO_ADDRESS_LIST_QUERY IOCTL
Ogni volta che SIO_ADDRESS_LIST_CHANGE IOCTL invia una notifica all'applicazione della modifica dell'elenco indirizzi (tramite operazioni di I/O sovrapposte o segnalando FD_ADDRESS_LIST_CHANGE evento), è necessario ripetere l'intera sequenza di azioni.

Per informazioni più dettagliate, vedere le informazioni di riferimento SIO_ADDRESS_LIST_QUERY . SIO_ADDRESS_LIST_QUERY è supportato in Windows 2000 e versioni successive.

SIO_ASSOCIATE_HANDLE (impostazione opcode: I, T==1)

Associa questo socket all'handle specificato di un'interfaccia complementare. Il buffer di input contiene il valore intero corrispondente alla costante del manifesto per l'interfaccia complementare (ad esempio, TH_NETDEV e TH_TAPI), seguito da un valore che rappresenta un handle dell'interfaccia complementare specificata, insieme a qualsiasi altra informazione richiesta. Per altri dettagli, vedere la sezione appropriata in Windows Sockets 2 Protocol-Specific Allegato e/o documentazione per l'interfaccia complementare specifica. Queste risorse possono essere disponibili solo in inglese. La dimensione totale viene riflessa nella lunghezza del buffer di input. Non è necessario alcun buffer di output. Il codice di errore WSAENOPROTOOPT è indicato per i provider di servizi che non supportano questo IOCTL. L'handle associato a questo IOCTL può essere recuperato usando SIO_TRANSLATE_HANDLE.

È possibile usare un'interfaccia complementare, ad esempio, se un provider specifico fornisce:

Una grande quantità di controllo aggiuntivo sul comportamento di un socket.
Controlli specifici del provider che non eseguono il mapping alle funzioni Windows Socket esistenti (o a quelle probabilmente per il futuro).

Si consiglia di utilizzare il modello COM (Component Object Model) anziché IOCTL per identificare e registrare le eventuali altre interfacce supportate da un socket. Questo IOCTL è presente per la compatibilità con le versioni precedenti con i sistemi in cui COM non è disponibile o non può essere usato per qualche altro motivo.

SIO_ASSOCIATE_PORT_RESERVATION (impostazione opcode: I, T==3)

Associare un socket a una prenotazione persistente o di runtime per un blocco di porte TCP o UDP identificate dal token di prenotazione della porta. Il SIO_ASSOCIATE_PORT_RESERVATION IOCTL deve essere rilasciato prima che il socket sia associato. Se e quando il socket è associato, la porta assegnata verrà selezionata dalla prenotazione della porta identificata dal token specificato. Se non sono disponibili porte dalla prenotazione specificata, la chiamata di funzione Bind avrà esito negativo.

Per informazioni più dettagliate, vedere le informazioni di riferimento sul SIO_ASSOCIATE_PORT_RESERVATION .

SIO_ASSOCIATE_PORT_RESERVATION è supportato in Windows Vista e versioni successive del sistema operativo.

SIO_BASE_HANDLE (impostazione opcode: O, T==1)

Recupera l'handle del provider di servizi di base per un determinato socket. Il valore restituito è un socket.

Un provider di servizi a più livelli non deve mai intercettare questo IOCTL perché il valore restituito deve essere l'handle socket del provider di servizi di base.

Se il buffer di output non è sufficientemente grande per un handle socket ( cbOutBuffer è minore delle dimensioni di un SOCKET) o il parametro lpvOutBuffer è un puntatore NULL , SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAEFAULT.

SIO_BASE_HANDLE è definito nel file di intestazione Mswsock.h e supportato in Windows Vista e versioni successive.

SIO_BSP_HANDLE (impostazione opcode: O, T==1)

Recupera l'handle del provider di servizi di base per un socket utilizzato dalla funzione WSASendMsg . Il valore restituito è un socket.

Questo Ioctl viene usato da un provider di servizi a più livelli per garantire che il provider intercetta la funzione WSASendMsg .

SIO_BSP_HANDLE è definito nel file di intestazione Mswsock.h e supportato in Windows Vista e versioni successive.

SIO_BSP_HANDLE_SELECT (impostazione opcode: O, T==1)

Recupera l'handle del provider di servizi di base per un socket utilizzato dalla funzione select . Il valore restituito è un socket.

Questo Ioctl viene usato da un provider di servizi a più livelli per garantire che il provider intercetta la funzione select .

SIO_BSP_HANDLE_SELECT è definito nel file di intestazione Mswsock.h e supportato in Windows Vista e versioni successive.

SIO_BSP_HANDLE_POLL (impostazione opcode: O, T==1)

Recupera l'handle del provider di servizi di base per un socket utilizzato dalla funzione WSAPoll . Il parametro lpOverlapped deve essere un puntatore NULL . Il valore restituito è un socket.

Questo Ioctl viene usato da un provider di servizi a più livelli per garantire che il provider intercetta la funzione WSAPoll .

Se il buffer di output non è sufficientemente grande per un handle socket ( cbOutBuffer è minore delle dimensioni di un socket), il parametro lpvOutBuffer è un puntatore NULL o il parametro lpOverlapped non è un puntatore NULL , SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAEFAULT.

SIO_BSP_HANDLE_POLL è definito nel file di intestazione Mswsock.h e supportato in Windows Vista e versioni successive.

SIO_CHK_QOS (impostazione opcode: I, O, T==3)

Recupera informazioni sulle caratteristiche del traffico QoS. Durante la fase transitoria del sistema di invio tra la configurazione del flusso e la ricezione di un messaggio RESV (vedere How the RSVP Service Invokes TC per altre informazioni sulla fase transitoria), il traffico associato a un flusso RSVP viene modellato in base al tipo di servizio ( BEST EFFORT, CONTROLLED LOAD o GUARANTEED). Per altre informazioni, vedere Uso di SIO_CHK_QOS nella sezione Qualità del servizio di Platform Software Development Kit (SDK).

SIO_ENABLE_CIRCULAR_QUEUEING (impostazione opcode: V, T==1)

Indica a un provider di servizi orientati ai messaggi che un messaggio appena arrivato non deve mai essere eliminato a causa di un overflow della coda del buffer. Al contrario, il messaggio meno recente nella coda deve essere eliminato per contenere il messaggio appena arrivato. Non sono necessari buffer di input e output. Si noti che questo IOCTL è valido solo per i socket associati a protocolli non affidabili e orientati ai messaggi. Il codice di errore WSAENOPROTOOPT è indicato per i provider di servizi che non supportano questo IOCTL.

SIO_FIND_ROUTE (impostazione opcode: O, T==1)

Quando viene emesso, questo IOCTL richiede che venga individuata la route all'indirizzo remoto specificato come sockaddr nel buffer di input. Se l'indirizzo esiste già nella cache locale, la relativa voce viene invalidata. Nel caso di IPX di Novell, questa chiamata avvia un ipX GetLocalTarget (GLT), che esegue una query sulla rete per l'indirizzo remoto specificato.

SIO_FLUSH (impostazione opcode: V, T==1)

Rimuove il contenuto corrente della coda di invio associata a questo socket. Non sono necessari buffer di input e output. Il codice di errore WSAENOPROTOOPT è indicato per i provider di servizi che non supportano questo IOCTL.

SIO_GET_BROADCAST_ADDRESS (impostazione opcode: O, T==1)

Questo IOCTL riempie il buffer di output con una struttura sockaddr contenente un indirizzo broadcast adatto per l'uso con LPWSPSendTo.

SIO_GET_EXTENSION_FUNCTION_POINTER (impostazione opcode: O, I, T==1)

Recuperare un puntatore alla funzione di estensione specificata supportata dal provider di servizi associato. Il buffer di input contiene un identificatore univoco globale (GUID) il cui valore identifica la funzione di estensione in questione. Il puntatore alla funzione desiderata viene restituito nel buffer di output. Gli identificatori di funzione di estensione vengono stabiliti dai fornitori del provider di servizi e devono essere inclusi nella documentazione del fornitore che descrive le funzionalità e la semantica delle funzioni di estensione.

I valori GUID per le funzioni di estensione supportate dal provider di servizi TCP/IP di Windows sono definiti nel file di intestazione Mswsock.h . Il valore possibile per questi GUID è il seguente:

Termine	Descrizione
WSAID_ACCEPTEX	Funzione di estensione AcceptEx .
WSAID_CONNECTEX	Funzione di estensione ConnectEx .
WSAID_DISCONNECTEX	Funzione di estensione DisconnectEx .
WSAID_GETACCEPTEXSOCKADDRS	Funzione di estensione GetAcceptExSockaddrs .
WSAID_TRANSMITFILE	Funzione di estensione TransmitFile .
WSAID_TRANSMITPACKETS	Funzione di estensione TransmitPackets .
WSAID_WSARECVMSG	Funzione di estensione LPFN_WSARECVMSG (WSARecvMsg).
WSAID_WSASENDMSG	Funzione di estensione WSASendMsg .

SIO_GET_GROUP_QOS (impostazione opcode: O, T==1)

Riservato.

SIO_GET_INTERFACE_LIST (impostazione opcode: O, T==0)

Restituisce un elenco di interfacce IP configurate e i relativi parametri come matrice di strutture INTERFACE_INFO .

Nota

Il supporto di questo comando è obbligatorio per i provider di servizi TCP/IP conformi a Windows Sockets 2.

Il parametro lpvOutBuffer punta al buffer in cui archiviare le informazioni sulle interfacce come matrice di strutture INTERFACE_INFO per indirizzi IP unicast nelle interfacce. Il parametro cbOutBuffer specifica la lunghezza del buffer di output. Il numero di interfacce restituite (numero di strutture restituite nel buffer a cui punta il parametro lpvOutBuffer ) può essere determinato in base alla lunghezza effettiva del buffer di output restituito nel parametro lpcbBytesReturned .

Se la funzione WSAIoctl viene chiamata con SIO_GET_INTERFACE_LIST e il membro di livello del parametro del socket non viene definito come IPPROTO_IP, viene restituito WSAEINVAL . Una chiamata alla funzione WSAIoctl con SIO_GET_INTERFACE_LIST restituisce WSAEFAULT se il parametro cbOutBuffer che specifica la lunghezza del buffer di output è troppo piccolo, riceve l'elenco di interfacce configurate.

SIO_GET_INTERFACE_LIST_EX (impostazione opcode: O, T==0)

Riservato per uso futuro con socket.

Restituisce un elenco di interfacce IP configurate e i relativi parametri come matrice di strutture INTERFACE_INFO_EX .

Il parametro lpvOutBuffer punta al buffer in cui archiviare le informazioni sulle interfacce come matrice di strutture INTERFACE_INFO_EX per indirizzi IP unicast nell'interfaccia. Il parametro cbOutBuffer specifica la lunghezza del buffer di output. Il numero di interfacce restituite (numero di strutture restituite in lpvOutBuffer) può essere determinato in base alla lunghezza effettiva del buffer di output restituito nel parametro lpcbBytesReturned .

SIO_GET_INTERFACE_LIST_EX non è attualmente supportato in Windows.

SIO_GET_QOS (impostazione opcode: O, T==1)

Recupera la struttura QOS associata al socket. Il buffer di input è facoltativo. Alcuni protocolli( ad esempio RSVP) consentono di usare il buffer di input per qualificare una richiesta QOS . La struttura QOS verrà copiata nel buffer di output. Il buffer di output deve essere di dimensioni sufficienti per poter contenere la struttura QOS completa. Il codice di errore WSAENOPROTOOPT è indicato per i provider di servizi che non supportano la qualità del servizio.

SIO_IDEAL_SEND_BACKLOG_CHANGE (impostazione opcode: V, T==0)

Notifica a un'applicazione quando il valore ISB (Ideal Send BackLog) cambia per la connessione sottostante.

Quando si inviano dati tramite una connessione TCP usando i socket di Windows, è importante mantenere una quantità sufficiente di dati in attesa (inviati ma non ancora riconosciuti) in TCP per ottenere la velocità effettiva più elevata. Il valore ideale per la quantità di dati in attesa per ottenere la velocità effettiva migliore per la connessione TCP è detta dimensione ideale per il backlog di invio (ISB). Il valore ISB è una funzione del prodotto di ritardo della larghezza di banda della connessione TCP e della finestra di ricezione pubblicizzata del ricevitore (e in parte la quantità di congestione nella rete).

Il valore ISB per connessione è disponibile dall'implementazione del protocollo TCP in Windows Server 2008, Windows Vista con Service Pack 1 (SP1) e versioni successive del sistema operativo. Il SIO_IDEAL_SEND_BACKLOG_CHANGE IOCTL può essere usato da un'applicazione per ricevere una notifica quando il valore ISB cambia in modo dinamico per una connessione.

Per informazioni più dettagliate, vedere le informazioni di riferimento sul SIO_IDEAL_SEND_BACKLOG_CHANGE .

SIO_IDEAL_SEND_BACKLOG_CHANGE è supportato in Windows Server 2008, Windows Vista con SP1 e versioni successive del sistema operativo.

SIO_IDEAL_SEND_BACKLOG_QUERY (impostazione opcode: O, T==0)

Recupera il valore di backlog di invio ideale (ISB) per la connessione sottostante.

Il valore ISB per connessione è disponibile dall'implementazione del protocollo TCP in Windows Server 2008 e versioni successive. Il SIO_IDEAL_SEND_BACKLOG_QUERY IOCTL può essere usato da un'applicazione per eseguire una query sul valore ISB per una connessione.

Per informazioni più dettagliate, vedere le informazioni di riferimento sul SIO_IDEAL_SEND_BACKLOG_QUERY .

SIO_IDEAL_SEND_BACKLOG_QUERY è supportato in Windows Server 2008, Windows Vista con SP1 e versioni successive del sistema operativo.

SIO_KEEPALIVE_VALS (impostazione opcode: I, T==3)

Abilita o disabilita l'impostazione per connessione dell'opzione keep-alive TCP che specifica il timeout e l'intervallo keep-alive TCP. Per altre informazioni sull'opzione keep-alive, vedere la sezione 4.2.3.6 sui requisiti per gli host Internet- Livelli di comunicazione specificati in RFC 1122 disponibile nel sito Web IETF.

SIO_KEEPALIVE_VALS può essere usato per abilitare o disabilitare probe keep-alive e impostare il timeout e l'intervallo keep-alive. Il timeout keep-alive specifica il timeout, espresso in millisecondi, senza alcuna attività fino all'invio del primo pacchetto keep-alive. L'intervallo keep-alive specifica l'intervallo, espresso in millisecondi, tra l'invio dei pacchetti keep-alive successivi se non viene ricevuto alcun riconoscimento.

L'opzione SO_KEEPALIVE , che è una delle opzioni socket SOL_SOCKET, può essere usata anche per abilitare o disabilitare il keep-alive TCP in una connessione, nonché eseguire una query sullo stato corrente di questa opzione. Per verificare se il keep-alive TCP è abilitato su un socket, è possibile chiamare la funzione getsockopt con l'opzione SO_KEEPALIVE . Per abilitare o disabilitare il keep-alive TCP, è possibile chiamare la funzione setsockopt con l'opzione SO_KEEPALIVE . Se il keep-alive TCP è abilitato con SO_KEEPALIVE, le impostazioni TCP predefinite vengono usate per il timeout e l'intervallo keep-alive, a meno che questi valori non siano stati modificati usando SIO_KEEPALIVE_VALS.

Per informazioni più dettagliate, vedere le informazioni di riferimento SIO_KEEPALIVE_VALS. SIO_KEEPALIVE_VALS è supportato in Windows 2000 e versioni successive.

SIO_MULTIPOINT_LOOPBACK (impostazione opcode: I, T==1)

Controlla se i dati inviati da un'applicazione nel computer locale (non necessariamente dallo stesso socket) in una sessione multicast verranno ricevuti da un socket unito al gruppo di destinazione multicast nell'interfaccia di loopback. Un valore TRUE fa sì che i dati multicast inviati da un'applicazione nel computer locale vengano recapitati a un socket di ascolto nell'interfaccia di loopback. Il valore FALSE impedisce che i dati multicast inviati da un'applicazione nel computer locale vengano recapitati a un socket di ascolto nell'interfaccia di loopback. Per impostazione predefinita, SIO_MULTIPOINT_LOOPBACK è abilitato.

SIO_MULTICAST_SCOPE (impostazione opcode: I, T==1)

Specifica l'ambito in cui verranno eseguite le trasmissioni multicast. L'ambito viene definito come numero di segmenti di rete indirizzati da coprire. Un ambito pari a zero indica che la trasmissione multicast non verrebbe inserita in rete, ma potrebbe essere distribuita tra socket all'interno dell'host locale. Un valore di ambito pari a 1 (impostazione predefinita) indica che la trasmissione verrà inserita in rete, ma non intersecerà alcun router. I valori di ambito più elevati determinano il numero di router che è possibile attraversare. Si noti che corrisponde al parametro TTL (Time-to-Live) nel multicast IP.

SIO_QUERY_RSS_SCALABILITY_INFO (impostazione opcode: O, T==3)

Esegue l'offload delle interfacce per la funzionalità rss (Receive-Side Scaling). La struttura dell'argomento restituita per SIO_QUERY_RSS_SCALABILITY_INFO viene specificata nella struttura RSS_SCALABILITY_INFO definita nel file di intestazione Mstcpip.h . Questa struttura è definita come segue.

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

Il valore restituito nel membro RssEnabled indica se RSS è abilitato in almeno un'interfaccia.

Se il buffer di output non è sufficientemente grande per la struttura RSS_SCALABILITY_INFO ( cbOutBuffer è minore delle dimensioni di un RSS_SCALABILITY_INFO) o il parametro lpvOutBuffer è un puntatore NULL , SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAEINVAL.

Nelle reti ad alta velocità in cui si trovano più CPU all'interno di un singolo sistema, la capacità dello stack di protocolli di rete di ridimensionare correttamente in un sistema multi-CPU è inibita perché l'architettura di NDIS 5.1 e le versioni precedenti limitano l'elaborazione del protocollo a una singola CPU. Il ridimensionamento lato ricezione risolve questo problema consentendo il bilanciamento del carico di rete da una scheda di rete tra più CPU.

SIO_QUERY_RSS_SCALABILITY_INFO è supportato in Windows Vista e versioni successive.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE (impostazione opcode: O, T==3)

Esegue una query sull'handle dell'endpoint APPLICATION Layer Enforcement (ALE).

Windows Filtering Platform (WFP) supporta l'ispezione e la modifica del traffico di rete. In Windows Vista il WFP è incentrato sugli scenari in cui il computer host è l'endpoint di comunicazione. In Windows Server 2008, tuttavia, esistono implementazioni del firewall perimetrale che vorrebbero sfruttare la piattaforma WFP per controllare e proxy il traffico pass-through. Il server ISA (Internet Security and Acceleration) è un esempio di un dispositivo perimetrale di questo tipo.

Esistono alcuni scenari firewall che potrebbero richiedere la possibilità di inserire un pacchetto in ingresso nel percorso di invio associato a un endpoint esistente. È necessario un meccanismo per individuare l'handle dell'endpoint del livello di trasporto associato all'endpoint di destinazione. L'applicazione che ha creato l'endpoint è proprietario di questi endpoint del livello di trasporto. Questo IOCTL viene usato per fornire l'handle socket al mapping dell'handle dell'endpoint del livello di trasporto.

Se il buffer di output non è sufficientemente grande per l'handle dell'endpoint ( cbOutBuffer è minore delle dimensioni di un UINT64) o il parametro lpvOutBuffer è un puntatore NULL , SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAEINVAL.

SIO_QUERY_WFP_ALE_ENDPOINT_HANDLE è supportato in Windows Vista e versioni successive.

SIO_QUERY_PNP_TARGET_HANDLE (impostazione opcode: O, T==1)

Per ottenere il descrittore socket del provider successivo nella catena in cui dipende il socket corrente in senso PnP. Questo IOCTL viene richiamato dalla DLL di Windows Sockets 2 solo sui socket di provider di servizi non IFS creati tramite LA CHIAMATA WPUCreateSocketHandle . Il provider deve restituire nel buffer di output l'handle del socket del provider successivo nella catena in cui dipende un handle di socket specifico, ad esempio la rimozione del dispositivo che supporta l'handle sottostante comporterà l'invalidazione dell'handle precedente nella catena.

Se un'operazione sovrapposta viene completata immediatamente, questa funzione 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. Al termine dell'operazione sovrapposta, 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 LPWSPGetOverlappedResult.

SIO_RCVALL (impostazione opcode: I, T==3)

Consente a un socket di ricevere tutti i pacchetti IPv4 o IPv6 che passano attraverso un'interfaccia di rete. L'handle del socket passato alla funzione WSAIoctl deve essere uno dei seguenti:

Socket IPv4 creato con la famiglia di indirizzi impostata su AF_INET, il tipo di socket impostato su SOCK_RAW e il protocollo impostato su IPPROTO_IP.
Socket IPv6 creato con la famiglia di indirizzi impostata su AF_INET6, tipo di socket impostato su SOCK_RAW e protocollo impostato su IPPROTO_IPV6.

Il socket deve anche essere associato a un'interfaccia IPv4 o IPv6 locale esplicita, il che significa che non è possibile eseguire l'associazione a INADDR_ANY o in6addr_any.

In Windows Server 2008 e versioni precedenti, l'impostazione SIO_RCVALL IOCTL non acquisisce i pacchetti locali inviati da un'interfaccia di rete. Inclusi i pacchetti ricevuti in un'altra interfaccia e inoltrato l'interfaccia di rete specificata per il SIO_RCVALL IOCTL.

In Windows 7 e Windows Server 2008 R2 questo è stato modificato in modo che vengano acquisiti anche i pacchetti locali inviati da un'interfaccia di rete. Sono inclusi i pacchetti ricevuti in un'altra interfaccia e quindi inoltrata l'interfaccia di rete associata al socket con SIO_RCVALL IOCTL.

L'impostazione di questo IOCTL richiede privilegi di amministratore nel computer locale.

Questa funzionalità viene talvolta definita modalità promiscua.

I valori possibili per l'opzione SIO_RCVALL IOCTL vengono specificati nell'enumerazione RCVALL_VALUE definita nel file di intestazione Mstcpip.h . I valori possibili per SIO_RCVALL sono i seguenti:

Termine	Descrizione
RCVALL_OFF	Disabilitare questa opzione in modo che un socket non riceva tutti i pacchetti IPv4 o IPv6 nella rete.
RCVALL_ON	Abilitare questa opzione in modo che un socket riceva tutti i pacchetti IPv4 o IPv6 nella rete. Questa opzione abilita la modalità promiscua sulla scheda di interfaccia di rete (NIC), se la scheda di interfaccia di rete supporta la modalità promiscua. In un segmento LAN con un hub di rete, una scheda di interfaccia di rete che supporta la modalità promiscua acquisirà tutto il traffico IPv4 o IPv6 nella LAN, incluso il traffico tra altri computer nello stesso segmento LAN. Tutti i pacchetti acquisiti (IPv4 o IPv6, a seconda del socket) verranno recapitati al socket non elaborato. Questa opzione non acquisisce altri pacchetti (ad esempio ARP, IPX e NetBEUI) nell'interfaccia. Netmon usa la stessa modalità per l'interfaccia di rete, ma non usa questa opzione per acquisire il traffico.
RCVALL_SOCKETLEVELONLY	Questa funzionalità non è attualmente implementata, pertanto l'impostazione di questa opzione non ha alcun effetto.
RCVALL_IPLEVEL	Abilitare questa opzione in modo che un socket IPv4 o IPv6 riceva tutti i pacchetti a livello IP nella rete. Questa opzione non abilita la modalità promiscua sulla scheda di interfaccia di rete. Questa opzione influisce solo sull'elaborazione dei pacchetti a livello ip. La scheda di interfaccia di rete riceve ancora solo i pacchetti indirizzati agli indirizzi unicast e multicast configurati. Tuttavia, un socket con questa opzione abilitata riceverà non solo pacchetti indirizzati a indirizzi IP specifici, ma riceverà tutti i pacchetti IPv4 o IPv6 ricevuti dalla scheda di interfaccia di rete. Questa opzione non acquisisce altri pacchetti (pacchetti ARP, IPX e NetBEUI, ad esempio) ricevuti nell'interfaccia.

Per informazioni più dettagliate, vedere le informazioni di riferimento sulle SIO_RCVALL .

SIO_RCVALL è supportato in Windows 2000 e versioni successive.

SIO_RELEASE_PORT_RESERVATION (impostazione opcode: I, T==3)

Rilascia una prenotazione di runtime per un blocco di porte TCP o UDP. La prenotazione di runtime da rilasciare deve essere stata ottenuta dal processo di emissione usando il SIO_ACQUIRE_PORT_RESERVATION IOCTL.

Per informazioni più dettagliate, vedere il riferimento SIO_RELEASE_PORT_RESERVATION .

SIO_RELEASE_PORT_RESERVATION è supportato in Windows Vista e versioni successive del sistema operativo.

SIO_ROUTING_INTERFACE_CHANGE (impostazione opcode: I, T==1)

Per ricevere la notifica di una modifica dell'interfaccia di routing che deve essere usata per raggiungere l'indirizzo remoto nel buffer di input (specificato come struttura sockaddr ). Nessuna informazione di output sulla nuova interfaccia di routing verrà fornita al completamento di questo IOCTL; il completamento indica semplicemente che l'interfaccia di routing per una determinata destinazione è stata modificata e deve essere eseguita una query usando il SIO_ROUTING_INTERFACE_QUERY IOCTL.

Si presuppone (anche se non obbligatorio) che l'applicazione usi operazioni di I/O sovrapposte per ricevere una notifica della modifica dell'interfaccia di routing tramite il completamento di SIO_ROUTING_INTERFACE_CHANGE richiesta. In alternativa, se il SIO_ROUTING_INTERFACE_CHANGE IOCTL viene emesso in un socket non bloccante con i parametri lpOverlapped e lpCompletionRoutine impostati su NULL), verrà completato immediatamente con l'errore WSAEWOULDBLOCK e il client SPI Windows Socket può attendere gli eventi di modifica del routing usando una chiamata a LPWSPEventSelect o LPWSPAsyncSelect con il bit FD_ROUTING_INTERFACE_CHANGE impostato nella maschera di bit dell'evento di rete.

Si riconosce che le informazioni di routing rimangono stabili nella maggior parte dei casi, in modo da richiedere all'applicazione di mantenere più IOCTL in sospeso per ricevere notifiche su tutte le destinazioni a cui è interessato e che il provider di servizi tenga traccia di queste richieste di notifica userà una quantità significativa di risorse di sistema. Questa situazione può essere evitata estendendo il significato dei parametri di input e riducendo i requisiti del provider di servizi come indicato di seguito:

Il client SPI Windows Sockets può specificare un indirizzo jolly specifico della famiglia di protocolli (uguale a quello usato nella chiamata Bind quando si richiede di eseguire l'associazione a qualsiasi indirizzo disponibile) per richiedere notifiche di eventuali modifiche al routing. In questo modo il client WINDOWS Sockets SPI può mantenere solo un SIO_ROUTING_INTERFACE_CHANGE in sospeso per tutti i socket e le destinazioni di cui dispone e quindi usare SIO_ROUTING_INTERFACE_QUERY per ottenere le informazioni di routing effettive.

Il provider di servizi può scegliere di ignorare le informazioni fornite dal client SPI Windows Sockets nel buffer di input del SIO_ROUTING_INTERFACE_CHANGE (come se il client SPI Windows Sockets ha specificato un indirizzo jolly) e completare l'evento SIO_ROUTING_INTERFACE_CHANGE IOCTL o segnale FD_ROUTING_INTERFACE_CHANGE in caso di modifica delle informazioni di routing (non solo la route alla destinazione specificata nel buffer di input).

SIO_ROUTING_INTERFACE_QUERY (impostazione opcode: I, O, T==1)

Per ottenere l'indirizzo dell'interfaccia locale (rappresentata come struttura sockaddr ) da usare per inviare all'indirizzo remoto specificato nel buffer di input (come sockaddr). Gli indirizzi multicast remoti possono essere inviati nel buffer di input per ottenere l'indirizzo dell'interfaccia preferita per la trasmissione multicast. In ogni caso, l'indirizzo dell'interfaccia restituito può essere usato dall'applicazione in una richiesta bind successiva.

Si noti che le route sono soggette a modifiche. Pertanto, i client SPI Windows Socket non possono basarsi sulle informazioni restituite da SIO_ROUTING_INTERFACE_QUERY per essere persistenti. I client SPI possono registrarsi per il routing delle notifiche di modifica usando il SIO_ROUTING_INTERFACE_CHANGE IOCTL, che fornisce la notifica tramite operazioni di I/O sovrapposte o un evento di FD_ROUTING_INTERFACE_CHANGE. La sequenza di azioni seguente può essere usata per garantire che il client SPI Windows Socket abbia sempre informazioni sull'interfaccia di routing correnti per una determinata destinazione:

Problema SIO_ROUTING_INTERFACE_CHANGE IOCTL.
Problema SIO_ROUTING_INTERFACE_QUERY IOCTL.
Ogni volta che SIO_ROUTING_INTERFACE_CHANGE IOCTL notifica al client SPI WinSock la modifica del routing (tramite operazioni di I/O sovrapposte o segnalando FD_ROUTING_INTERFACE_CHANGE evento), è necessario ripetere l'intera sequenza di azioni.

Se il buffer di output non è sufficientemente grande da contenere l'indirizzo dell'interfaccia, SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAEFAULT. In questo caso, le dimensioni necessarie del buffer di output verranno restituite in lpcbBytesReturned . Si noti che il codice di errore WSAEFAULT viene restituito anche se il parametro lpvInBuffer, lpvOutBuffer o lpcbBytesReturned non è totalmente contenuto in una parte valida dello spazio indirizzi utente.

Se l'indirizzo di destinazione specificato nel buffer di input non può essere raggiunto tramite alcuna delle interfacce disponibili, SOCKET_ERROR viene restituito come risultato di questo IOCTL e WSAGetLastError restituisce WSAENETUNREACH o anche WSAENETDOWN se tutta la connettività di rete viene persa.

SIO_SET_COMPATIBILITY_MODE (impostazione opcode: I, T==3)

Richiede il modo in cui lo stack di rete deve gestire determinati comportamenti per i quali il modo predefinito di gestire il comportamento può differire tra le versioni di Windows. La struttura dell'argomento per SIO_SET_COMPATIBILITY_MODE viene specificata nella struttura WSA_COMPATIBILITY_MODE definita nel file di intestazione Mswsockdef.h . Questa struttura è definita come segue:

} WSA_COMPATIBILITY_MODE, *PWSA_COMPATIBILITY_MODE;

Il valore specificato nel membro BehaviorId indica il comportamento richiesto. Il valore specificato nel membro TargetOsVersion indica la versione di Windows richiesta per il comportamento.

Il membro BehaviorId può essere uno dei valori del tipo di enumerazione WSA_COMPATIBILITY_BEHAVIOR_ID definito nel file di intestazione Mswsockdef.h . I valori possibili per il membro BehaviorId sono i seguenti:

Termine	Descrizione
WsaBehaviorAll	Equivale a richiedere tutti i possibili comportamenti compatibili definiti per WSA_COMPATIBILITY_BEHAVIOR_ID.
WsaBehaviorReceiveBuffering	Quando il membro TargetOsVersion è impostato su un valore per Windows Vista o versione successiva, le riduzioni delle dimensioni del buffer di ricezione TCP in questo socket tramite l'opzione socket SO_RCVBUF sono consentite anche dopo l'istituzione di una connessione TCP. Quando il membro TargetOsVersion è impostato su un valore precedente a Windows Vista, le riduzioni alla dimensione del buffer di ricezione TCP in questo socket tramite l'opzione socket SO_RCVBUF non sono consentite dopo la creazione della connessione.
WsaBehaviorAutoTuning	Quando il membro TargetOsVersion è impostato su un valore per Windows Vista o versione successiva, l'ottimizzazione automatica della finestra di ricezione è abilitata e il fattore di scala della finestra TCP viene ridotto a 2 dal valore predefinito 8. Quando TargetOsVersion è impostato su un valore precedente a Windows Vista, l'ottimizzazione automatica della finestra di ricezione è disabilitata. L'opzione tcp window scaling è disabilitata e la dimensione massima della finestra di ricezione è limitata a 65.535 byte. L'opzione di ridimensionamento delle finestre TCP non può essere negoziata sulla connessione anche se l'opzione socket SO_RCVBUF è stata chiamata su questo socket specificando un valore maggiore di 65.535 byte prima che la connessione sia stata stabilita.

Per informazioni più dettagliate, vedere le informazioni di riferimento SIO_SET_COMPATIBILITY_MODE .

SIO_SET_COMPATIBILITY_MODE è supportato in Windows Vista e versioni successive.

SIO_SET_GROUP_QOS (impostazione opcode: I, T==1)

Riservato.

SIO_SET_QOS (impostazione opcode: I, T==1)

Associare la struttura QOS fornita al socket. Non è necessario alcun buffer di output, la struttura QOS verrà ottenuta dal buffer di input. Il codice di errore WSAENOPROTOOPT è indicato per i provider di servizi che non supportano la qualità del servizio.

SIO_TRANSLATE_HANDLE (impostazione opcode: I, O, T==1)

Per ottenere un handle corrispondente per socket s valido nel contesto di un'interfaccia complementare , ad esempio TH_NETDEV e TH_TAPI. Una costante manifesto che identifica l'interfaccia complementare insieme a qualsiasi altro parametro necessario viene specificata nel buffer di input. L'handle corrispondente sarà disponibile nel buffer di output al termine di questa funzione. Per altri dettagli, vedere la sezione appropriata in Windows Sockets 2 Protocol-Specific Allegato e/o documentazione per l'interfaccia complementare specifica. Il codice di errore WSAENOPROTOOPT è indicato per i provider di servizi che non supportano questo IOCTL per l'interfaccia complementare specificata. Questo IOCTL recupera l'handle associato tramite SIO_TRANSLATE_HANDLE.

È consigliabile usare COM anziché questo IOCTL per individuare e tenere traccia di altre interfacce che potrebbero essere supportate da un socket. Questo IOCTL è presente per la compatibilità con le versioni precedenti con i sistemi in cui COM non è disponibile o non può essere usato per qualche altro motivo.

SIO_UDP_CONNRESET (impostazione opcode: I, T==3)

Windows XP: Controlla se vengono segnalati messaggi di PORT_UNREACHABLE UDP. Impostare su TRUE per abilitare la creazione di report. Impostare su FALSE per disabilitare la creazione di report.

Quando viene chiamato con un socket sovrapposto, il parametro lpOverlapped deve essere valido per la durata dell'operazione sovrapposta.

Se il parametro lpCompletionRoutine è NULL, il provider di servizi segnala il membro hEvent di lpOverlapped quando l'operazione sovrapposta viene completata se contiene un handle di oggetto evento valido. Il client SPI Di Windows Sockets può usare LPWSPGetOverlappedResult per eseguire il polling o attendere l'oggetto evento.

Se lpCompletionRoutine non è NULL, il membro hEvent viene ignorato e può essere usato dal client SPI Windows Sockets per passare le informazioni di contesto alla routine di completamento. Un client che passa un valore lpCompletionRoutine non NULL e 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 membro hEvent non è definito e il tentativo di attendere il membro hEvent produrrebbe risultati imprevedibili.

È responsabilità del provider di servizi disporre della chiamata della routine di completamento specificata dal client al termine dell'operazione sovrapposta. Poiché la routine di completamento deve essere eseguita nel contesto dello stesso thread che ha avviato l'operazione sovrapposta, non può essere richiamata direttamente dal provider di servizi. Il WS2_32.DLL offre un meccanismo APC (Procedure Call) asincrona per facilitare la chiamata delle routine di completamento.

Un provider di servizi dispone che una funzione venga eseguita nel contesto di thread e processo appropriato chiamando WPUQueueApc. Questa funzione può essere chiamata da qualsiasi contesto di processo e thread, anche da un contesto diverso dal thread e dal processo usato per avviare l'operazione sovrapposta.

WPUQueueApc accetta come parametri di input un puntatore a una struttura WSATHREADID (fornita al provider tramite il parametro di input lpThreadId ), un puntatore a una funzione APC da richiamare e un valore di contesto a 32 bit che viene successivamente passato alla funzione APC. Poiché è disponibile solo un singolo valore di contesto a 32 bit, la funzione APC stessa non può essere la routine di completamento specificata dal client. Il provider di servizi deve invece fornire un puntatore alla propria funzione APC che utilizza il valore di contesto fornito per accedere alle informazioni sul risultato necessarie per l'operazione sovrapposta e quindi richiama la routine di completamento specificata dal client.

Il prototipo per la routine di completamento fornita dal client è il seguente:

);

CompletionRoutine è un segnaposto per una funzione fornita dal client. DwError specifica lo stato di completamento per l'operazione sovrapposta, come indicato da lpOverlapped. CbTransferred specifica il numero di byte restituiti. Attualmente, non esistono valori di flag definiti e dwFlags sarà zero. Questa funzione 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, anche se 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.

Nota

Tutte le operazioni di I/O avviate da un determinato thread vengono annullate quando il thread viene chiuso. Per i socket sovrapposti, le operazioni asincrone in sospeso possono avere esito negativo se il thread viene chiuso prima del completamento delle operazioni. Per altre informazioni, vedere ExitThread .

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	ws2spi.h

Vedi anche

Funzione di callback LPWSPIOCTL (ws2spi.h)

Sintassi

Parametri

Valore restituito

Commenti

Compatibilità

Requisiti

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive