Funzione di callback LPWSPASYNCSELECT (ws2spi.h)

Articolo
07/16/2024

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 di bit che specifica una combinazione di eventi di rete in cui è interessato il client SPI (Service Provider Interface) di Windows Sockets. Costruito usando l'operatore OR bit per bit con uno di questi valori.

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

[out] lpErrno

Puntatore al codice di errore. Per altre informazioni, vedi la sezione Valore restituito .

Valore restituito

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

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

Vedi 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.

Osservazioni

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 il quale è richiesta la notifica è identificato da .

Questa funzione imposta automaticamente socket sulla modalità non bloccante, indipendentemente dal valore di lEvent. Vedere LPWSPIoctl su come ripristinare la modalità di blocco del socket.

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

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

Quando si verifica uno degli eventi di rete designati suldel socket specificato , il provider di servizi usa WPUPostMessage per inviare messaggi wMsg alla finestra del client SPI Windows Sockets hWnd. 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 di evento di rete che possono essere indicati sono i seguenti.

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

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. Nella tabella seguente sono elencati i codici di errore possibili per ogni evento di rete.

evento : FD_CONNECT

Codice errore	Significato
WSAEAFNOSUPPORT	Gli indirizzi nella famiglia specificata non possono essere utilizzati con questo socket.
WSAECONNREFUSED	Il tentativo di connessione è stato rifiutato.
WSAENETUNREACH	Impossibile raggiungere la rete da questo host al 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	Non è disponibile alcuno spazio nel buffer. Il socket non può essere collegato.
WSAENOTCONN	Il socket non è connesso.
WSAETIMEDOUT	Tentativo di connessione timeout senza stabilire una connessione.

evento : FD_CLOSE

Codice 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 errore	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.

evento : FD_ROUTING_INTERFACE_CHANGE

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

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

Un provider Windows Sockets 2 non deve inondare continuamente un client WINDOWS Sockets SPI con messaggi per un determinato evento di rete. Dopo aver inviato correttamente la notifica di un determinato evento a una finestra del client SPI 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 effettua la chiamata di funzione che abilita in modo implicito la notifica di tale evento di rete.

Evento di rete	Riattivazione della 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 indicante che la funzione della condizione ha restituito CF_DEFER
FD_CONNECT	NESSUNO
FD_CLOSE	NESSUNO
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 il comando SIO_ROUTING_INTERFACE_CHANGE
FD_ADDRESS_LIST_CHANGE	LPWSPIoctl con il 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 di livello . Ciò significa che se viene chiamata la routine di ripetizione dell'abilitazione e la condizione pertinente viene comunque soddisfatta dopo la chiamata, viene inviato un messaggio LPWSPAsyncSelect al client SPI di Windows Sockets.

Gli eventi di FD_QOS e FD_GROUP_QOS vengono considerati attivato da edge. Un messaggio verrà pubblicato esattamente una volta quando si verifica una modifica QOS. Altri messaggi non saranno disponibili 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 disponibili fino a quando il client WINDOWS Sockets SPI ripubblica il IOCTL e viene rilevata un'altra modifica dopo l'emissione di IOCTL.

Se si verifica già un evento quando il client SPI Windows Sockets chiama LPWSPAsyncSelecto 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 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 LPWSPAccepte quindi dopo che un LPWSPSend o LPWSPSendTo ha esito negativo con WSAEWOULDBLOCK e lo spazio del buffer diventa disponibile. Pertanto, un client WINDOWS Sockets SPI può presupporre che gli invii siano possibili a partire dal primo messaggio FD_WRITE e durano fino a quando un invio non restituisce WSAEWOULDBLOCK. Dopo un errore di questo tipo, il client SPI Windows Sockets riceverà una notifica che indica che gli invii sono nuovamente possibili con un messaggio FD_WRITE.

L'evento FD_OOB viene utilizzato solo quando un socket è configurato per ricevere 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 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 è stata 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 la FD_CLOSE viene registrata quando la connessione entra negli stati TIME WAIT o CLOSE WAIT. Questo risultato dalla fine 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.

In caso di chiusura normale, il provider di servizi deve inviare un messaggio di FD_CLOSE per indicare la chiusura del circuito virtuale solo dopo la lettura di tutti i dati ricevuti. 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 di flusso associata al socket 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 di FD_ROUTING_INTERFACE_CHANGE viene inviato quando l'interfaccia locale che deve essere usata per raggiungere la destinazione specificata in LPWSPIoctl con modifiche SIO_ROUTING_INTERFACE_CHANGE modifiche dopo l'emissione di tale IOCTL.

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

Ecco un riepilogo degli eventi e delle 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 aver chiamato LPWSPRecv o LPWSPRecvFrom (con o senza MSG_PEEK), se i dati sono ancora disponibili per la ricezione.

Quando è abilitata SO_OOBINLINE LPWSPSetSockOpt, dati include dati normali e dati fuori banda (OOB) nelle istanze indicate in precedenza.

FD_WRITE

Quando viene chiamato LPWSPAsyncSelect, se è possibile LPWSPSend o LPWSPSendTo.
Dopo viene chiamato LPWSPConnect o LPWSPAccept, quando viene stabilita la connessione.
Dopo LPWSPSend o LPWSPSendTo non riesce 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 di MSG_OOB.
Quando arrivano i dati OOB, se FD_OOB non è già stato pubblicato.
Dopo viene chiamato LPWSPRecv o LPWSPRecvFrom 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 inviato.
Dopo viene chiamato LPWSPAccept, se è disponibile un'altra richiesta di connessione da accettare.

FD_CONNECT

Quando viene chiamato LPWSPAsyncSelect, se è attualmente stabilita una connessione.
Dopo viene chiamato LPWSPConnect, quando viene stabilita la connessione (anche quando LPWSPConnect ha esito positivo immediatamente, come è tipico con un socket di datagrammi) e anche quando ha esito negativo immediatamente).
Dopo aver chiamato WSPJoinLeaf, al termine dell'operazione di join.
Dopo connessione, WSAConnecto WSPJoinLeaf è stato chiamato con un socket non bloccante e orientato alla connessione. L'operazione iniziale restituita con un errore specifico di WSAEWOULDBLOCK, ma l'operazione di rete è andata avanti. Indipendentemente dal fatto che l'operazione abbia 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 e sono 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 ha avviato una chiusura normale con LPWSPShutdown e il sistema remoto ha risposto con una notifica di fine dei dati (ad esempio TCP FIN), quando non sono attualmente disponibili dati per la ricezione.
Quando il sistema remoto interrompe la connessione ( ad esempio, inviato TCP RST) e lParam conterrà il valore di errore WSAECONNRESET.

FD_CLOSE non viene pubblicato dopo viene chiamato LPWSPCloseSocket.

FD_QOS

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

FD_GROUP_QOS

Riservato per un uso futuro con i gruppi di socket:

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

FD_ROUTING_INTERFACE_CHANGE

dopo viene chiamato LPWSPIoctl con SIO_ROUTING_INTERFACE_CHANGE, quando viene usata l'interfaccia locale da usare per raggiungere la destinazione specificata nelle modifiche IOCTL.

FD_ADDRESS_LIST_CHANGE

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

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 10 Build 20348
server minimo supportato	Windows 10 Build 20348
intestazione	ws2spi.h

Vedere anche

funzione di callback LPWSPAsyncSelect

Condividi tramite