WSPAsyncSelect

The WSPAsyncSelect function requests Windows message-based event notification of network events for a socket.

int WSPAsyncSelect (
  SOCKET s,            
  HWND hWnd,           
  unsigned int wMsg,   
  long lEvent,         
  LPINT lpErrno        
);
 

Parameters

s
[in] A descriptor identifying the socket for which event notification is required.
hWnd
[in] A handle identifying the window which should receive a message when a network event occurs.
wMsg
[in] The message to be sent when a network event occurs.
lEvent
[in] A bitmask which specifies a combination of network events in which the Windows Sockets SPI client is interested.
lpErrno
[out] A pointer to the error code.

This function is used to request that the service provider send a Window message to the client's window hWnd whenever it detects any of the network events specified by the lEvent parameter. The service provider should use the WPUPostMessage function to post the message. The message to 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 WSPIoctl about how to set the socket back to blocking mode.

The lEvent parameter is constructed by or'ing any of the values specified in the following list.

Value Meaning
FD_READ Issue notification of readiness for reading
FD_WRITE Issue notification of readiness for writing
FD_OOB Issue notification of the arrival of out-of-band data
FD_ACCEPT Issue notification of incoming connections
FD_CONNECT Issue notification of completed connection
FD_CLOSE Issue notification of socket closure
FD_QOS Issue notification of socket Quality of Service (QOS) changes
FD_GROUP_QOS Reserved for future use with socket groups: Issue notification of socket group Quality of Service (QOS) changes
FD_ROUTING
_INTERFACE_CHANGE
Issue notification of routing interface change for the specified destination
FD_ADDRESS_LIST
_CHANGE
Issue notification of local address list change for the socket's protocol family

Invoking WSPAsyncSelect for a socket cancels any previous WSPAsyncSelect or WSPEventSelect for the same socket. For example, to receive notification for both reading and writing, the Windows Sockets SPI client must call WSPAsyncSelect with both FD_READ and FD_WRITE, as follows:

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

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 = WSPAsyncSelect(s, hWnd, wMsg1, FD_READ, &error);
rc = WSPAsyncSelect(s, hWnd, wMsg2, FD_WRITE, &error);
 

To cancel all notification (for example, to indicate that the service provider should send no further messages related to network events on the socket) lEvent will be set to zero.

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

Since a socket created by WSPAccept has the same properties as the listening socket used to accept it, any WSPAsyncSelect events set for the listening socket apply to the accepted socket. For example, if a listening socket has WSPAsyncSelect 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 same wMsg value used for messages. If a different wMsg or events are needed, the Windows Sockets SPI client must call WSPAsyncSelect, passing the accepted socket and the new information.

When one of the nominated network events occurs on the specified socket s, the service provider uses WPUPostMessage to send message wMsg to the Windows Sockets SPI client's window hWnd. 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 WS2SPI.H.

The possible network event codes which can be indicated are as follows:

Value Meaning
FD_READ Socket s ready for reading
FD_WRITE Socket s ready for writing
FD_OOB Out-of-band data ready for reading on socket s
FD_ACCEPT Socket s ready for accepting a new incoming connection
FD_CONNECT Connection initiated on socket s completed
FD_CLOSE Connection identified by socket s has been closed
FD_QOS Quality of Service associated with socket s has changed
FD_GROUP_QOS Reserved for future use with socket groups: Quality of Service associated with the socket group to which s belongs has changed
FD_ROUTING
_INTERFACE_CHANGE
Local interface that should be used to send to the specified destination has changed
FD_ADDRESS_LIST
_CHANGE
The list of addresses of the socket's protocol family to which the Windows Socket SPI client can bind has changed

Return Values

The return value is zero if the Windows Sockets SPI client's declaration of interest in the network event set was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error code is available in lpErrno.

Comments

Although WSPAsyncSelect can be called with interest in multiple events, the service provider issues the same Windows message for each event.

A Windows Sockets 2 provider shall not continually flood a Windows Sockets SPI client with messages for a particular network event. Having successfully posted notification of a particular event to a Windows Sockets SPI client window, no further message(s) for that network event will be posted to the Windows Sockets SPI client window until the Windows Sockets SPI client makes the function call which implicitly re-enables notification of that network event.

Event Re-enabling function
FD_READ WSPRecv or WSPRecvFrom
FD_WRITE WSPSend or WSPSendTo
FD_OOB WSPRecv or WSPRecvFrom
FD_ACCEPT WSPAccept unless the error code returned is WSATRY_AGAIN indicating that the condition function returned CF_DEFER
FD_CONNECT NONE
FD_CLOSE NONE
FD_QOS WSPIoctl with SIO_GET_QOS
FD_GROUP_QOS Reserved for future use with socket groups: WSPIoctl with SIO_GET_GROUP_QOS
FD_ROUTING
_INTERFACE_CHANGE
WSPIoctl with command SIO_ROUTING_INTERFACE_CHANGE
FD_ADDRESS_LIST
_CHANGE
WSPIoctl with command SIO_ADDRESS_LIST_CHANGE

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 WSPAsyncSelect message is posted to the Windows Sockets SPI client.

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 Windows Sockets SPI client renegotiates the QOS for the socket.

The FD_ROUTING_INTERFACE_CHANGE and FD_ADDRESS_LIST_CHANGE events are considered "edge triggered" as well. A message will be posted exactly once when a change occurs after the Windows Socket 2 SPI client has request the notification by issuing WSPIoctl with SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE correspondingly. Further messages will not be forthcoming until the SPI client reissues the IOCTL and another change is detected since the IOCTL has been issued.

If any event has already happened when the Windows Sockets SPI client calls WSPAsyncSelect or when the re-enabling function is called, then a message is posted as appropriate. For example, consider the following sequence: 1) a SPI client calls WSPListen, 2) a connect request is received but not yet accepted, 3) the Windows Sockets SPI client calls WSPAsyncSelect specifying that it wants to receive FD_ACCEPT messages for the socket. Due to the persistence of events, the Windows Sockets service provider posts an FD_ACCEPT message immediately.

The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected with WSPConnect (after FD_CONNECT, if also registered) or accepted with WSPAccept, and then after a WSPSend or WSPSendTo fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, a Windows Sockets SPI client 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 Windows Sockets SPI client 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. 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 Windows Sockets SPI client must register an interest in FD_READ events, not FD_OOB events.

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 WSPShutdown on the send side or a WSPCloseSocket. FD_CLOSE shall only be posted after all data is read from a socket.

In the case of a graceful close, the service provider should only send an FD_CLOSE message to indicate virtual circuit closure after all the received data has been read. It should not send 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. The service provider must update the QOS information available to the client through WSPIoctl with SIO_GET_QOS and/or SIO_GET_GROUP_QOS.

The FD_ROUTING_INTERFACE_CHANGE message is posted when the local interface that should be used to reach the destination specified in WSPIoctl with SIO_ROUTING_INTERFACE_CHANGE changes AFTER such IOCTL has been issued.

The FD_ADDRESS_LIST_CHANGE message is posted when the list of addresses to which the Windows Socket 2 SPI client can bind changes AFTER WSPIoctl with SIO_ADDRESS_LIST_CHANGE has been issued.

Here is a summary of events and conditions for each asynchronous notification message:

Note When WSPSetSockOpt SO_OOBINLINE is enabled, "data" includes both normal data and out-of-band (OOB) data in the instances noted above.

Error Codes

WSAENETDOWN The network subsystem has failed.
WSAEINVAL 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 invalid state.
WSAEINPROGRESS A blocking Windows Sockets call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK The descriptor is not a socket.

Additional error codes can be set when the service provider issues a message to a Windows Sockets SPI client's window. This error code is embedded in the lParam field of the message. Possible error codes for each network event are:

Event: FD_CONNECT

Error Code Meaning
WSAEAFNOSUPPORT Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED The attempt to connect was forcefully rejected.
WSAENETUNREACH The network cannot be reached from this host at this time.
WSAEFAULT The namelen argument is incorrect.
WSAEINVAL The socket is already bound to an address.
WSAEISCONN The socket is already connected.
WSAEMFILE No more file descriptors are available.
WSAENOBUFS No buffer space is available. The socket cannot be connected.
WSAENOTCONN The socket is not connected.
WSAETIMEDOUT Attempt to connect timed out without establishing a connection.

Event: FD_CLOSE

Error Code Meaning
WSAENETDOWN The network subsystem has failed.
WSAECONNRESET The connection was reset by the remote side.
WSAECONNABORTED The connection was terminated due to a time-out or other failure.

Event: FD_READ

Event: FD_WRITE

Event: FD_OOB

Event: FD_ACCEPT

Event: FD_QOS

Event: FD_GROUP_QOS

Event: FD_ADDRESS_LIST_CHANGE

Error Code Meaning
WSAENETDOWN The network subsystem has failed.

Event: FD_ROUTING_INTERFACE_CHANGE

Error Code Meaning
WSAENETUNREACH The specified destination is no longer reachable
WSAENETDOWN The network subsystem has failed.

QuickInfo

  Windows NT: Yes
  Windows: Yes
  Windows CE: Unsupported.
  Header: Declared in ws2spi.h.

See Also

WSPSelect