Funzione WSAPoll (winsock2.h)

Articolo
08/27/2023

La funzione WSAPoll determina lo stato di uno o più socket.

Sintassi

int WSAAPI WSAPoll(
  [in, out] LPWSAPOLLFD fdArray,
  [in]      ULONG       fds,
  [in]      INT         timeout
);

Parametri

[in, out] fdArray

Matrice di una o più strutture POLLFD che specificano il set di socket per cui viene richiesto lo stato. La matrice deve contenere almeno una struttura con un socket valido. Al ritorno, questo parametro riceve i socket aggiornati con i flag di stato revents del membro impostato su ogni oggetto che corrisponde ai criteri di query di stato.

[in] fds

Numero di strutture WSAPOLLFD in fdarray. Questo non è necessariamente il numero di socket per cui è richiesto lo stato.

[in] timeout

Valore che specifica il comportamento di attesa, in base ai valori seguenti.

Valore	Significato
Maggiore di zero	Tempo, in millisecondi, da attendere.
Zero	Restituisce immediatamente.
Minore di zero	Attendere in modo indefinito.

Valore restituito

Restituisce uno dei valori seguenti.

Valore restituito	Descrizione
Zero	Nessun socket nello stato sottoposto a query prima della scadenza del timer.
Maggiore di zero	Il numero di elementi in fdarray per cui un membro revents della struttura POLLFD è diverso da zero.
SOCKET_ERROR	Si è verificato un errore. Chiamare la funzione WSAGetLastError per recuperare il codice di errore esteso.

Codice errore esteso	Significato
WSAENETDOWN	Il sottosistema di rete non è riuscito.
WSAEFAULT	Si è verificata un'eccezione durante la lettura dei parametri di input utente.
WSAEINVAL	È stato passato un parametro non valido. Questo errore viene restituito se le strutture WSAPOLLFD puntano al parametro fdarray quando si richiede lo stato del socket. Questo errore viene restituito anche se nessuno dei socket specificati nel membro fd di una delle strutture WSAPOLLFD puntate dal parametro fdarray è valido.
WSAENOBUFS	La funzione non è in grado di allocare memoria sufficiente.

Commenti

La funzione WSAPoll è definita in Windows Vista e versioni successive.

Strutture WSAPOLLFD . Un'applicazione imposta i flag appropriati nel membro eventi della struttura WSAPOLLFD per specificare il tipo di stato richiesto per ogni socket corrispondente. La funzione WSAPoll restituisce lo stato di un socket nel membro revents della struttura WSAPOLLFD .

Per ogni socket, un chiamante può richiedere informazioni sullo stato di lettura o scrittura. Le condizioni di errore vengono sempre restituite, quindi non è necessario richiedere informazioni su di essi.

La struttura WSAPOLLFD punta al parametro fdarray . Tutti i socket che non soddisfano questi criteri e non hanno alcuna condizione di errore avranno il membro revents corrispondente impostato su 0.

Una combinazione dei flag seguenti può essere impostata nella struttura WSAPOLLFD per un determinato socket quando si richiede lo stato per tale socket:

Flag	Descrizione
POLLPRI	I dati con priorità possono essere letti senza bloccare. Questo flag non è supportato dal provider Microsoft Winsock.
POLLRDBAND	I dati della banda di priorità (fuori banda) possono essere letti senza bloccare.
POLLRDNORM	I dati normali possono essere letti senza bloccare.
POLLWRNORM	I dati normali possono essere scritti senza bloccare.

Il flag POLLIN è definito come combinazione dei valori del flag POLLRDNORM e POLLRDBAND . Il flag POLLOUT è definito come lo stesso valore del flag POLLWRNORM .

La struttura WSAPOLLFD deve contenere solo una combinazione dei flag precedenti supportati dal provider Winsock. Tutti gli altri valori vengono considerati errori e WSAPoll restituirà SOCKET_ERROR. Una chiamata successiva alla funzione WSAGetLastError recupera il codice di errore esteso di WSAEINVAL. Se il flag POLLPRI è impostato su un socket per il provider Microsoft Winsock, la funzione WSAPoll avrà esito negativo.

Quando le strutture WSAPOLLFD puntano al parametro fdarray per indicare lo stato del socket:

Flag	Descrizione
POLLERR	un errore.
POLLHUP	Una connessione orientata al flusso è stata disconnessa o interrotta.
POLLNVAL	È stato usato un socket non valido.
POLLPRI	I dati con priorità possono essere letti senza bloccare. Questo flag non viene restituito dal provider Microsoft Winsock.
POLLRDBAND	I dati della banda di priorità (fuori banda) possono essere letti senza bloccare.
POLLRDNORM	I dati normali possono essere letti senza bloccare.
POLLWRNORM	I dati normali possono essere scritti senza bloccare.

Per quanto riguarda i socket TCP e UDP:

Struttura WSAPOLLFD come dati normali come POLLRDNORM.
La struttura WSAPOLLFD , un'operazione recv successiva è garantita senza bloccare.
Struttura WSAPOLLFD di POLLWRNORM.
Struttura WSAPOLLFD di POLLRDNORM. Una chiamata successiva da accettare è garantita per il completamento senza blocco.
Struttura WSAPOLLFD di POLLRDBAND.
Struttura WSAPOLLFD quando un peer remoto arresta un'operazione di invio (è stata ricevuta una fin TCP). Una richiesta di funzione recv successiva restituirà zero byte.
Struttura WSAPOLLFD quando il peer remoto avvia una disconnessione graziata.
La struttura WSAPOLLFD viene restituita quando un peer remoto si disconnette improvvisamente.
Struttura WSAPOLLFD quando il socket locale viene chiuso.

Il numero di elementi (non socket) in fdarray è indicato da nfds. I membri di fdarray che hanno il loro membro fd impostato su un valore negativo vengono ignorati e i loro ricorsi verranno impostati su POLLNVAL al momento del ritorno. Questo comportamento è utile per un'applicazione che gestisce un'allocazione fdarray fissa e non compatta la matrice per rimuovere le voci inutilizzate o per riallocare la memoria. Non è necessario cancellare i rivent per qualsiasi elemento prima di chiamare WSAPoll.

L'argomento timeout specifica per quanto tempo la funzione deve attendere prima della restituzione. Un valore positivo contiene il numero di millisecondi di attesa prima della restituzione. Un valore zero forza WSAPoll a restituire immediatamente e un valore negativo indica che WSAPoll deve attendere per un periodo illimitato.

Nota Quando si esegue una chiamata Winsock bloccante, ad esempio WSAPoll con il parametro di timeout impostato su un numero negativo, Winsock potrebbe dover attendere un evento di rete prima che la chiamata possa essere completata. Winsock esegue un'attesa avvisabile in questa situazione, che può essere interrotta da una chiamata di procedura asincrona pianificata nello stesso thread. L'esecuzione di un'altra chiamata Winsock bloccante all'interno di un APC che ha interrotto una chiamata winsock in corso sullo stesso thread causerà un comportamento non definito e non deve mai essere tentata dai client Winsock.

Nota A partire da Windows 10 versione 2004, quando un socket TCP non riesce a connettersi ( POLLHUP \| POLLERR \| POLLWRNORM) è indicato.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock2.h (include Winsock2.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll

Vedi anche

WSAGetLastError

WSAPOLLFD

Share via