Funzione di callback LPWSPASYNCSELECT (ws2spi.h)

Articolo
08/28/2023

La funzione LPWSPAsyncSelect richiede la notifica degli eventi di rete basata su messaggi di Windows per un socket.

Sintassi

LPWSPASYNCSELECT Lpwspasyncselect;

int Lpwspasyncselect(
  [in]  SOCKET s,
  [in]  HWND hWnd,
  [in]  unsigned int wMsg,
  [in]  long lEvent,
  [out] LPINT lpErrno
)
{...}

Parametri

[in] s

Descrittore che identifica il socket per il quale è necessaria la notifica degli eventi.

[in] hWnd

Gestire l'identificazione della finestra che deve ricevere un messaggio quando si verifica un evento di rete.

[in] wMsg

Messaggio da inviare quando si verifica un evento di rete.

[in] lEvent

Maschera bit che specifica una combinazione di eventi di rete in cui è interessato il client dell'interfaccia del provider di servizi Windows Sockets (SPI). Costruito usando l'operatore OR bit per bit con uno di questi valori.

Valore	Significato
FD_READ	Invia una notifica di idoneità per la lettura.
FD_WRITE	Notifica dell'idoneità per la scrittura.
FD_OOB	Invia una notifica all'arrivo dei dati OOB.
FD_ACCEPT	Problemi di notifica delle connessioni in ingresso.
FD_CONNECT	Problemi di notifica delle connessioni completate.
FD_CLOSE	Problemi di notifica della chiusura del socket.
FD_QOS	Problemi di notifica della qualità del servizio (QoS) delle modifiche.
FD_GROUP_QOS	Riservato.
FD_ROUTING_INTERFACE_CHANGE	Problemi di notifica della modifica dell'interfaccia di routing per la destinazione specificata.
FD_ADDRESS_ LIST_CHANGE	Problemi di notifica della modifica dell'elenco indirizzi locali per la famiglia di protocolli del socket.

[out] lpErrno

Puntatore al codice di errore. Per altre informazioni, vedere la sezione Restituisci valore .

Valore restituito

Il valore restituito è zero se la dichiarazione di interesse del client SPI di Windows Sockets nel set di eventi di rete ha avuto esito positivo. In caso contrario, il valore SOCKET_ERROR viene restituito e un codice di errore specifico è disponibile in lpErrno.

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEINVAL	Indica che uno dei parametri specificati non è valido, ad esempio l'handle della finestra che non fa riferimento a una finestra esistente o il socket specificato è in uno stato non valido.
WSAEINPROGRESS	Una chiamata windows Sockets bloccata è in corso o il provider di servizi sta ancora elaborando una funzione di callback.
WSAENOTSOCK	Il descrittore non è un socket.

Vedere Osservazioni per informazioni sui codici di errore aggiuntivi che possono essere impostati (nella parola alta di lParam all'interno del messaggio) quando una finestra dell'applicazione riceve un messaggio.

Commenti

Questa funzione viene usata per richiedere che il provider di servizi invii un messaggio di Windows alla finestra del client hWnd ogni volta che il provider di servizi rileva uno degli eventi di rete specificati dall'argomento lEvent . Il provider di servizi deve usare la funzione WPUPostMessage per pubblicare il messaggio. Il messaggio da inviare viene specificato dal parametro wMsg . Il socket per cui è necessaria la notifica è identificato da s.

Questa funzione imposta automaticamente socket s su modalità nonblocking, indipendentemente dal valore di lEvent. Vedere LPWSPIoctl su come impostare nuovamente il socket sulla modalità di blocco.

Richiamare LPWSPAsyncSelect per un socket annulla qualsiasi precedente LPWSPAsyncSelect o LPWSPEventSelect per lo stesso socket. Ad esempio, per ricevere una notifica per la lettura e la scrittura, il client SPI di Windows Sockets deve chiamare LPWSPAsyncSelect con FD_READ e FD_WRITE, come questo.

rc = WSPAsyncSelect(s, hWnd, wMsg, FD_READ | FD_WRITE, &error);

Non è possibile specificare messaggi diversi per eventi diversi. Il codice seguente non funzionerà; la seconda chiamata annulla gli effetti del primo e l'unica associazione sarà l'evento FD_WRITE associato a wMsg2.

// Incorrect example.
rc = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);

Per annullare tutte le notifiche, ovvero per indicare che il provider di servizi non deve inviare altri messaggi correlati agli eventi di rete nel socket, impostare lEvent su zero.

rc = WSPAsyncSelect(s, hWnd, 0, 0, &error);

Poiché un socket LPWSPAccept'ed ha le stesse proprietà del socket di ascolto usato per accettarlo, tutti gli eventi LPWSPAsyncSelect impostati per il socket di ascolto si applicano al socket accettato. Ad esempio, se un socket in ascolto ha eventi LPWSPAsyncSelect FD_ACCEPT, FD_READ e FD_WRITE, qualsiasi socket accettato in tale socket di ascolto avrà anche FD_ACCEPT, FD_READ e FD_WRITE eventi con lo stesso valore wMsg usato per i messaggi. Se si desidera un wMsg o eventi diversi, il client SPI di Windows Sockets deve chiamare LPWSPAsyncSelect, passando il socket accettato e le nuove informazioni desiderate.

Quando si verifica uno degli eventi di rete designati nel socket specificato, il provider di servizi usa WPUPostMessage per inviare messaggi wMsg alla finestra hWnd del client Windows Sockets SPI. Nel messaggio inviato l'argomento wParam identifica il socket in cui si è verificato un evento di rete. La parola bassa di lParam specifica l'evento di rete che si è verificato. I possibili codici eventi di rete che possono essere indicati sono i seguenti.

Valore	Significato
FD_READ	Socket s è pronto per la lettura
FD_WRITE	Socket s è pronto per la scrittura
FD_OOB	I dati fuori banda sono pronti per la lettura in socket s
FD_ACCEPT	Socket s è pronto per accettare una nuova connessione in ingresso
FD_CONNECT	La connessione avviata sul socket s è stata completata
FD_CLOSE	La connessione identificata da socket s è stata chiusa
FD_QOS	La qualità del servizio associato a socket s è cambiata
FD_GROUP_QOS	Riservato per l'uso futuro con i gruppi di socket: qualità del servizio associato al gruppo di socket a cui appartiene il socket è cambiato
FD_ROUTING_INTERFACE_CHANGE	L'interfaccia locale che deve essere usata per inviare alla destinazione specificata è stata modificata
FD_ADDRESS_LIST_CHANGE	Elenco di indirizzi della famiglia di protocolli del socket in cui è possibile associare il client SPI di Windows Sockets

La parola alta di lParam contiene qualsiasi codice di errore (può essere estratto usando la macro WSAGETSELECTERROR ). Il codice di errore è qualsiasi errore definito in ws2spi.h. I codici di errore possibili per ogni evento di rete sono elencati nella tabella seguente.

Evento: FD_CONNECT

Codice di errore	Significato
WSAEAFNOSUPPORT	Impossibile utilizzare gli indirizzi della famiglia specificata con questo socket.
WSAECONNREFUSED	Il tentativo di connessione è stato rifiutato.
WSAENETUNREACH	Impossibile raggiungere la rete da questo host in questo momento.
WSAEFAULT	Il parametro namelen non è valido.
WSAEINVAL	Il socket è già associato a un indirizzo.
WSAEISCONN	Il socket è già connesso.
WSAEMFILE	Non sono disponibili altri descrittori di file.
WSAENOBUFS	Nessuno spazio di buffer disponibile. Il socket non può essere connesso.
WSAENOTCONN	Il socket non è connesso.
WSAETIMEDOUT	Tentativo di connessione timeout senza stabilire una connessione.

Evento: FD_CLOSE

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAECONNRESET	La connessione è stata reimpostata dal lato remoto.
WSAECONNABORTED	La connessione è stata terminata a causa di un timeout o di un altro errore.

Evento...: FD_ACCEPT, FD_ADDRESS_LIST_CHANGE, FD_GROUP_QOS, FD_OOB, FD_QOS, FD_READ, FD_WRITE

Codice di errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.

Evento: FD_ROUTING_INTERFACE_CHANGE

Codice di errore	Significato
WSAENETUNREACH	La destinazione specificata non è più raggiungibile.
WSAENETDOWN	Il sottosistema di rete non è riuscito.

Anche se LPWSPAsyncSelect può essere chiamato con interesse in più eventi, il provider di servizi invia lo stesso messaggio di Windows per ogni evento.

Un provider Windows Sockets 2 non deve continuamente inondare un client SPI Windows Sockets con messaggi per un determinato evento di rete. Dopo aver inviato correttamente la notifica di un determinato evento a una finestra del client SPI di Windows Sockets, non verranno inviati altri messaggi per tale evento di rete alla finestra del client SPI Windows Sockets finché il client SPI Windows Sockets esegue la chiamata di funzione che abilita in modo implicito la notifica di tale evento di rete.

Evento di rete	Riabilitare la funzione
FD_READ	LPWSPRecv o LPWSPRecvFrom
FD_WRITE	LPWSPSend o LPWSPSendTo
FD_OOB	LPWSPRecv o LPWSPRecvFrom
FD_ACCEPT	LPWSPAccept, a meno che il codice di errore restituito non sia WSATRY_AGAIN che indica che la funzione della condizione ha restituito CF_DEFER
FD_CONNECT	NONE
FD_CLOSE	NONE
FD_QOS	LPWSPIoctl con SIO_GET_QOS
FD_GROUP_QOS	Riservato per uso futuro con i gruppi di socket: LPWSPIoctl con SIO_GET_GROUP_QOS
FD_ROUTING_INTERFACE_CHANGE	LPWSPIoctl con comando SIO_ROUTING_INTERFACE_CHANGE
FD_ADDRESS_LIST_CHANGE	LPWSPIoctl con comando SIO_ADDRESS_LIST_CHANGE

Qualsiasi chiamata alla routine di riabilitazione, anche una che ha esito negativo, comporta la riattivazione della registrazione dei messaggi per l'evento pertinente.

Per gli eventi di FD_READ, FD_OOB e FD_ACCEPT, la registrazione dei messaggi viene attivata a livello. Ciò significa che se viene chiamata la routine di riabilitazione e la condizione pertinente viene comunque soddisfatta dopo la chiamata, viene inviato un messaggio LPWSPAsyncSelect al client SPI di Windows Sockets.

Gli eventi FD_QOS e FD_GROUP_QOS vengono considerati attivati da edge. Un messaggio verrà inviato esattamente una volta quando si verifica una modifica QOS. Altri messaggi non saranno imminenti finché il provider non rileva un'ulteriore modifica in QOS o il client SPI Windows Sockets rinegozia il QOS per il socket.

Anche gli eventi FD_ROUTING_INTERFACE_CHANGE e FD_ADDRESS_LIST_CHANGE vengono considerati attivati da edge . Un messaggio verrà inviato esattamente una volta quando si verifica una modifica dopo che il client SPI Windows Sockets ha richiesto la notifica inviando WSAIoctl con SIO_ROUTING_INTERFACE_CHANGE o SIO_ADDRESS_LIST_CHANGE corrispondente. Altri messaggi non saranno imminenti finché il client SPI Windows Sockets esegue nuovamente L'IOCTL e viene rilevata un'altra modifica dopo l'emissione di IOCTL.

Se si è già verificato un evento quando il client SPI Windows Sockets chiama LPWSPAsyncSelect o quando viene chiamata la funzione di riattivazione, viene inviato un messaggio in base alle esigenze. Si consideri ad esempio la sequenza seguente.

Un client SPI Windows Sockets chiama LPWSPListen.
Viene ricevuta una richiesta di connessione, ma non ancora accettata.
Il client SPI Windows Sockets chiama LPWSPAsyncSelect specificando che vuole ricevere FD_ACCEPT messaggi per il socket. A causa della persistenza degli eventi, il provider di servizi WinSock invia immediatamente un messaggio di FD_ACCEPT.

L'evento FD_WRITE viene gestito in modo leggermente diverso. Un messaggio di FD_WRITE viene inviato quando un socket viene connesso per la prima volta con LPWSPConnect (dopo FD_CONNECT, se anche registrato) o accettato con LPWSPAccept e quindi dopo che un LPWSPSend o LPWSPSendTo ha esito negativo con WSAEWOULDBLOCK e lo spazio del buffer diventa disponibile. Pertanto, un client SPI Windows Sockets può presupporre che gli invii siano possibili a partire dal primo messaggio FD_WRITE e duraturi fino a quando un invio non restituisce WSAEWOULDBLOCK. Dopo un errore di questo tipo, il client SPI Windows Sockets riceverà una notifica che gli invii sono di nuovo possibili con un messaggio di FD_WRITE.

L'evento FD_OOB viene usato solo quando un socket è configurato per ricevere i dati fuori banda separatamente. Se il socket è configurato per ricevere dati fuori banda in linea, i dati fuori banda (accelerati) vengono considerati come dati normali e il client SPI Di Windows Sockets deve registrare un interesse per gli eventi FD_READ, non FD_OOB eventi.

Il codice di errore in un messaggio di FD_CLOSE indica se la chiusura del socket è stata normale o interrotta. Se il codice di errore è 0, la chiusura è normale; se il codice di errore è WSAECONNRESET, il circuito virtuale del socket è stato reimpostato. Questo vale solo per i socket orientati alla connessione, ad esempio SOCK_STREAM.

Il messaggio FD_CLOSE viene inviato quando viene ricevuta un'indicazione di chiusura per il circuito virtuale corrispondente al socket. In termini TCP, ciò significa che il FD_CLOSE viene registrato quando la connessione entra negli stati TIME WAIT o CLOSE WAIT. Questo risultato dall'estremità remota esegue un LPWSPShutdown sul lato di invio o un LPWSPCloseSocket. È corretto che FD_CLOSE venga pubblicato solo dopo che tutti i dati vengono letti da un socket.

Nel caso di una chiusura normale, il provider di servizi deve inviare un messaggio di FD_CLOSE per indicare la chiusura del circuito virtuale solo dopo che tutti i dati ricevuti sono stati letti. Non deve inviare un messaggio di FD_READ per indicare questa condizione.

Il messaggio FD_QOS o FD_GROUP_QOS viene inviato quando è stata apportata una modifica a qualsiasi campo nella specifica del flusso associata a socket s o al gruppo di socket a cui appartiene rispettivamente. Il provider di servizi deve aggiornare le informazioni QOS disponibili per il client tramite LPWSPIoctl con SIO_GET_QOS e/o SIO_GET_GROUP_QOS.

Il messaggio FD_ROUTING_INTERFACE_CHANGE viene inviato quando l'interfaccia locale da usare per raggiungere la destinazione specificata in LPWSPIoctl con SIO_ROUTING_INTERFACE_CHANGE modifiche dopo l'emissione di tale IOCTL.

Il messaggio FD_ADDRESS_LIST_CHANGE viene inviato quando è stato emesso l'elenco di indirizzi a cui il client SPI Windows Sockets può associare le modifiche dopol'emissione di LPWSPIoctl con SIO_ADDRESS_LIST_CHANGE.

Ecco un riepilogo di eventi e condizioni per ogni messaggio di notifica asincrono.

FD_READ

Quando viene chiamato LPWSPAsyncSelect , se sono attualmente disponibili dati da ricevere.
Quando arrivano i dati, se FD_READ non è già stato pubblicato.
Dopo la chiamata di LPWSPRecv o LPWSPRecvFrom (con o senza MSG_PEEK), se i dati sono ancora disponibili per la ricezione.

Quando l'opzione LPWSPSetSockOpt SO_OOBINLINE è abilitata, i dati includono dati normali e dati fuori banda (OOB) nelle istanze indicate in precedenza.

FD_WRITE

Quando viene chiamato LPWSPAsyncSelect , se è possibile un LPWSPSend o LPWSPSendTo .
Dopo aver chiamato LPWSPConnect o LPWSPAccept , quando viene stabilita la connessione.
Dopo che LPWSPSend o LPWSPSendTo ha esito negativo con WSAEWOULDBLOCK, quando È probabile che LPWSPSend o LPWSPSendTo abbia esito positivo.
Dopo LPWSPBind su un socket senza connessione. FD_WRITE può verificarsi o meno in questo momento (dipendente dall'implementazione). In ogni caso, un socket senza connessione è sempre scrivibile immediatamente dopo LPWSPBind.

FD_OOB (valido solo quando LPWSPSetSockOpt SO_OOBINLINE è disabilitato (impostazione predefinita)

Quando viene chiamato LPWSPAsyncSelect , se sono attualmente disponibili dati OOB da ricevere con il flag MSG_OOB.
Quando arrivano i dati OOB, se FD_OOB non è già stato pubblicato.
Dopo che LPWSPRecv o LPWSPRecvFrom viene chiamato con o senza flag di MSG_OOB, se i dati OOB sono ancora disponibili per la ricezione.

FD_ACCEPT

Quando viene chiamato LPWSPAsyncSelect , se è attualmente disponibile una richiesta di connessione da accettare.
Quando arriva una richiesta di connessione, se FD_ACCEPT non è già stato pubblicato.
Dopo aver chiamato LPWSPAccept , se è disponibile un'altra richiesta di connessione da accettare.

FD_CONNECT

Quando viene chiamato LPWSPAsyncSelect , se è attualmente stabilita una connessione.
Dopo aver chiamato LPWSPConnect , quando viene stabilita la connessione (anche quando LPWSPConnect ha esito positivo immediatamente, come in genere con un socket di datagram) e anche quando ha esito negativo immediatamente.
Dopo la chiamata a WSPJoinLeaf , al termine dell'operazione di join.
Dopo la connessione, WSAConnect o WSPJoinLeaf è stato chiamato con un socket non bloccante orientato alla connessione. L'operazione iniziale restituita con un errore specifico di WSAEWOULDBLOCK, ma l'operazione di rete è andata avanti. Se l'operazione ha esito positivo o negativo, quando il risultato è stato determinato, FD_CONNECT si verifica. Il client deve controllare il codice di errore per determinare se il risultato è riuscito o negativo.

FD_CLOSE (valido solo sui socket orientati alla connessione( ad esempio, SOCK_STREAM))

Quando viene chiamato LPWSPAsyncSelect , se la connessione socket è stata chiusa.
Dopo che il sistema remoto ha avviato una chiusura normale, quando non sono attualmente disponibili dati da ricevere (se i dati sono stati ricevuti ed è in attesa di essere letti quando il sistema remoto avvia una chiusura normale, il FD_CLOSE non viene recapitato fino a quando non vengono letti tutti i dati in sospeso).
Dopo che il sistema locale avvia una chiusura normale con LPWSPShutdown e il sistema remoto ha risposto con una notifica di fine dati (ad esempio TCP FIN), quando non sono attualmente disponibili dati per la ricezione.
Quando il sistema remoto interrompe la connessione (ad esempio, TCP RST inviato) e lParam conterrà il valore di errore WSAECONNRESET.

FD_CLOSE non viene pubblicato dopo la chiamata di LPWSPCloseSocket .

FD_QOS

Quando viene chiamato LPWSPAsyncSelect , se il QOS associato al socket è stato modificato.
Dopo la chiamata di LPWSPIoctl con SIO_GET_QOS, quando viene modificato il QOS.

FD_GROUP_QOS

Riservato per uso futuro con i gruppi di socket:

Quando viene chiamato LPWSPAsyncSelect , se il gruppo QOS associato al socket è stato modificato.
Dopo la chiamata di LPWSPIoctl con SIO_GET_GROUP_QOS, quando il gruppo QOS viene modificato.

FD_ROUTING_INTERFACE_CHANGE

dopo LPWSPIoctl con SIO_ROUTING_INTERFACE_CHANGE viene chiamato, quando viene modificata l'interfaccia locale che deve essere usata per raggiungere la destinazione specificata in IOCTL.

FD_ADDRESS_LIST_CHANGE

dopo LPWSPIoctl con SIO_ADDRESS_LIST_CHANGE viene chiamato, quando viene chiamato l'elenco di indirizzi locali a cui il client SPI Windows Sockets può associare le modifiche.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10 Build 20348
Server minimo supportato	Windows 10 Build 20348
Intestazione	ws2spi.h

Vedi anche

Funzione di callback LPWSPAsyncSelect