The Windows Sockets WSAAsyncSelect
function requests Windows message-based notification of network events for a
int WSAAsyncSelect (
| SOCKET s,
| HWND hWnd,
| unsigned int wMsg,
| long lEvent
[in] A descriptor identifying the socket for which event notification is
[in] A handle identifying the window which should receive a message when a
network event occurs.
[in] The message to be received when a network event occurs.
[in] A bitmask which specifies a combination of network events in which the
application is interested.
This function is used to request that the Windows Sockets DLL should send a
message to the window hWnd
whenever it detects any of the network events specified by the lEvent
parameter. The message which should be sent is specified by the wMsg
parameter. The socket for which notification is required is identified by s
This function automatically sets socket s
to nonblocking mode, regardless of the value of lEvent
. See ioctlsocket
about how to set the nonoverlapped socket back to blocking mode.
parameter is constructed by or'ing any of the values specified in the
||Want to receive notification of readiness for reading
||Want to receive notification of readiness for writing
||Want to receive notification of the arrival of out-of-band data
||Want to receive notification of incoming connections
||Want to receive notification of completed connection
||Want to receive notification of socket closure
||Want to receive notification of socket Quality of Service (QOS) changes
||Want to receive notification of socket group Quality of Service (QOS) changes
Issuing a WSAAsyncSelect
for a socket cancels any previous WSAAsyncSelect
for the same socket. For example, to receive notification for both reading
and writing, the application must call WSAAsyncSelect
with both FD_READ and FD_WRITE, as follows:
rc = WSAAsyncSelect(s, hWnd, wMsg, FD_READ|FD_WRITE);
It is not possible to specify different messages for different events. The
following code will not work; the second call will cancel the effects of the
first, and only FD_WRITE events will be reported with message wMsg2:
rc = WSAAsyncSelect(s, hWnd, wMsg1, FD_READ);
rc = WSAAsyncSelect(s, hWnd, wMsg2, FD_WRITE);
To cancel all notification (that is, to indicate that Windows Sockets should
send no further messages related to network events on the socket) lEvent
should be set to zero.
rc = WSAAsyncSelect(s, hWnd, 0, 0);
Although in this instance WSAAsyncSelect
immediately disables event message posting for the socket, it is possible
that messages can be waiting in the application's message queue. The application
must therefore be prepared to receive network event messages even after
cancellation. Closing a socket with closesocket
also cancels WSAAsyncSelect
message sending, but the same caveat about messages in the queue prior to the closesocket
Since an accept'
ed socket has the same properties as the listening socket used to accept it,
events set for the listening socket apply to the accepted socket. For
example, if a listening socket has WSAAsyncSelect
events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that
listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the
value used for messages. If a different wMsg
or events are desired, the application should call WSAAsyncSelect
, passing the accepted socket and the desired new information.
When one of the nominated network events occurs on the specified socket s
, the application's window hWnd
receives message wMsg
. The wParam
argument identifies the socket on which a network event has occurred. The low
word of lParam
specifies the network event that has occurred. The high word of lParam
contains any error code. The error code be any error as defined in WINSOCK2.H.
Upon receipt of an event notification message the WSAGetLastError
function cannot be used to check the error value, because the error value
returned can differ from the value in the high word of lParam
The error and event codes can be extracted from the lParam
using the macros WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in
#define WSAGETSELECTERROR(lParam) HIWORD(lParam)
#define WSAGETSELECTEVENT(lParam) LOWORD(lParam)
The use of these macros will maximize the portability of the source code for
The possible network event codes which can be returned are as follows:
||Socket s ready for reading
||Socket s ready for writing
||Out-of-band data ready for reading on socket s
||Socket s ready for accepting a new incoming connection
||Connection initiated on socket s completed
||Connection identified by socket s has been closed
||Quality of Service associated with socket s has changed
||Quality of Service associated with the socket group to which s belongs has changed
The return value is zero if the application's declaration of interest in the
network event set was successful. Otherwise, the value SOCKET_ERROR is returned,
and a specific error number can be retrieved by calling WSAGetLastError
can be called with interest in multiple events, the application window will
receive a single message for each network event.
As in the case of the select
will frequently be used to determine when a data transfer operation (send
) can be issued with the expectation of immediate success. Nevertheless, a
robust application must be prepared for the possibility that it can receive a
message and issue a Windows Sockets 2 call which returns WSAEWOULDBLOCK
immediately. For example, the following sequence of events is possible:
- data arrives on socket s; Windows Sockets 2 posts WSAAsyncSelect message
- application processes some other message
- while processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read
- application issues a recv(s,...) to read the data
- application loops to process next message, eventually reaching the WSAAsyncSelect message indicating that data is ready to read
- application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.
Other sequences are possible.
The Windows Sockets DLL will not continually flood an application with
messages for a particular network event. Having successfully posted notification of a
particular event to an application window, no further message(s) for that
network event will be posted to the application window until the application makes
the function call which implicitly re-enables notification of that network event.
||recv, recvfrom, WSARecv, or WSARecvFrom
||send, sendto, WSASend, or WSASendTo
||recv, recvfrom, WSARecv, or WSARecvFrom
||accept or WSAAccept unless the error code is WSATRY_AGAIN indicating that the condition function
||WSAIoctl with command SIO_GET_QOS
||WSAIoctl with command SIO_GET_GROUP_QOS
Any call to the re-enabling routine, even one which fails, results in
re-enabling of message posting for the relevant event.
For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is
"level-triggered." This means that if the re-enabling routine is called and the relevant
condition is still met after the call, a WSAAsyncSelect
message is posted to the application. This allows an application to be
event-driven and not be concerned with the amount of data that arrives at any one
time. Consider the following sequence:
- Network transport stack receives 100 bytes of data on socket s and causes Windows Sockets 2 to post an FD_READ message.
- The application issues recv( s, buffptr, 50, 0) to read 50 bytes.
- Another FD_READ message is posted since there is still data to be read.
With these semantics, an application need not read all available data in
response to an FD_READ message
a single recv
in response to each FD_READ message is appropriate. If an application issues
calls in response to a single FD_READ, it can receive multiple FD_READ
messages. Such an application may need to disable FD_READ messages before starting
calls by calling WSAAsyncSelect
with the FD_READ event not set.
The FD_QOS and FD_GROUP_QOS events are considered edge triggered. A message
will be posted exactly once when a QOS change occurs. Further messages will not
be forthcoming until either the provider detects a further change in QOS or the
application renegotiates the QOS for the socket.
If any event has already happened when the application calls WSAAsyncSelect
or when the re-enabling function is called, then a message is posted as
appropriate. For example, consider the following sequence:
- an application calls listen,
- a connect request is received but not yet accepted,
- the application calls WSAAsyncSelect specifying that it wants to receive FD_ACCEPT messages for the socket. Due to
the persistence of events, Windows Sockets 2 posts an FD_ACCEPT message
The FD_WRITE event is handled slightly differently. An FD_WRITE message is
posted when a socket is first connected with connect/WSAConnect
(after FD_CONNECT, if also registered) or accepted with accept/WSAAccept
, and then after a send operation fails with WSAEWOULDBLOCK and buffer space
becomes available. Therefore, an application can assume that sends are possible
starting from the first FD_WRITE message and lasting until a send returns
WSAEWOULDBLOCK. After such a failure the application will be notified that sends are
again possible with an FD_WRITE message.
The FD_OOB event is used only when a socket is configured to receive
out-of-band data separately. (See section Out-Of-Band data
for a discussion of this topic.) If the socket is configured to receive
out-of-band data in-line, the out-of-band (expedited) data is treated as normal data
and the application should register an interest in, and will receive, FD_READ
events, not FD_OOB events. An application may set or inspect the way in which
out-of-band data is to be handled by using setsockopt or getsockopt for the
The error code in an FD_CLOSE message indicates whether the socket close was
graceful or abortive. If the error code is zero, then the close was graceful; if
the error code is WSAECONNRESET, then the socket's virtual circuit was reset.
This only applies to connection-oriented sockets such as SOCK_STREAM.
The FD_CLOSE message is posted when a close indication is received for the
virtual circuit corresponding to the socket. In TCP terms, this means that the
FD_CLOSE is posted when the connection goes into the TIME WAIT or CLOSE WAIT
states. This results from the remote end performing a shutdown
on the send side or a closesocket
. FD_CLOSE should only be posted after all data is read from a socket, but an
application should check for remaining data upon receipt of FD_CLOSE to avoid
any possibility of losing data.
Please note your application will receive ONLY an FD_CLOSE message to indicate
closure of a virtual circuit, and only when all the received data has been
read if this is a graceful close. It will not
receive an FD_READ message to indicate this condition.
The FD_QOS or FD_GROUP_QOS message is posted when any field in the flow
specification associated with socket s
or the socket group that s
belongs to has changed, respectively. Applications should use WSAIoctl
with command SIO_GET_QOS or SIO_GET_GROUP_QOS to get the current QOS for
or for the socket group s
belongs to, respectively.
Here is a summary of events and conditions for each asynchronous notification
- when WSAAsyncSelect called, if there is data currently available to receive,
- when data arrives, if FD_READ not already posted,
- after recv or recvfrom called (with or without MSG_PEEK), if data is still available to receive.
SO_OOBINLINE is enabled "data" includes both normal data and out-of-band
(OOB) data in the instances noted above.
- when WSAAsyncSelect called, if a send or sendto is possible
- after connect or accept called, when connection established
- after send or sendto fail with WSAEWOULDBLOCK, when send or sendto are likely to succeed,
- after bind on a datagram socket.
- FD_OOB: Only valid when setsockopt SO_OOBINLINE is disabled (default).
- when WSAAsyncSelect called, if there is OOB data currently available to receive with the MSG_OOB
- when OOB data arrives, if FD_OOB not already posted,
- after recv or recvfrom called with or without MSG_OOB flag, if OOB data is still available to receive.
- when WSAAsyncSelect called, if there is currently a connection request available to accept,
- when a connection request arrives, if FD_ACCEPT not already posted,
- after accept called, if there is another connection request available to accept.
- when WSAAsyncSelect called, if there is currently a connection established,
- after connect called, when connection is established (even when connect succeeds immediately, as is typical with a datagram socket)
- FD_CLOSE: Only valid on connection-oriented sockets (for example, SOCK_STREAM)
- when WSAAsyncSelect called, if socket connection has been closed,
- after remote system initiated graceful close, when no data currently available
to receive (note: if data has been received and is waiting to be read when the
remote system initiates a graceful close, the FD_CLOSE is not delivered until
all pending data has been read),
- after local system initiates graceful close with shutdown and remote system has responded with "End of Data" notification (for example,
TCP FIN), when no data currently available to receive,
- when remote system terminates connection (for example, sent TCP RST), and lParam will contain WSAECONNRESET error value.
FD_CLOSE is not
posted after closesocket
- when WSAAsyncSelect called, if the QOS associated with the socket has been changed,
- after WSAIoctl with SIO_GET_QOS called, when the QOS is changed.
- when WSAAsyncSelect called, if the group QOS associated with the socket has been changed,
- after WSAIoctl with SIO_GET_GROUP_QOS called, when the group QOS is changed.
||A successful WSAStartup must occur before using this function.
||The network subsystem has failed.
||Indicates that one of the specified parameters was invalid such as the window
handle not referring to an existing window, or the specified socket is in an
||A blocking Windows Sockets 1.1 call is in progress, or the service provider is
still processing a callback function.
||The descriptor is not a socket.
Additional error codes may be set when an application window receives a
message. This error code is extracted from the lParam
in the reply message using the WSAGETSELECTERROR macro. Possible error codes
for each network event are:
||The specified address is already in use.
||The specified address is not available from the local machine.
||Addresses in the specified family cannot be used with this socket.
||The attempt to connect was forcefully rejected.
||The network cannot be reached from this host at this time.
||The namelen argument is incorrect.
||The socket is already bound to an address.
||The socket is already connected.
||No more file descriptors are available.
||No buffer space is available. The socket cannot be connected.
||The socket is not connected.
||Attempt to connect timed out without establishing a connection.
||The network subsystem has failed.
||The connection was reset by the remote side.
||The connection was terminated due to a time-out or other failure.
||The network subsystem has failed.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages
- Databases for Amazon shops developers
Amazon Categories Database
Browse Nodes Database