Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

Syntax 

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

Parameters

s

[in] Descriptor identifying the socket for which event notification is required.

hWnd

[in] Handle identifying the window that should receive a message when a network event occurs.

wMsg

[in] Message to be sent when a network event occurs.

lEvent

[in] Bitmask that specifies a combination of network events in which the Windows Sockets SPI client is interested.

lpErrno

[out] Pointer to the error code.

This function is used to request that the service provider send a Windows message to the client's window hWndwhenever it detects any of the network events specified by the lEventparameter. The message to be sent is specified by the wMsgparameter. The socket for which notification is required is identified by s.

This function automatically sets socket sto nonblocking mode, regardless of the value of lEvent. See WSPIoctlabout how to set the socket back to blocking mode.

The lEventparameter is constructed by using the bitwise OR operator with any of the values specified in the following table.

Value Description

FD_READ

Issues notification of readiness for reading.

FD_WRITE

Issues notification of readiness for writing.

FD_OOB

Issues notification of the arrival of OOB data.

FD_ACCEPT

Issues notification of incoming connections.

FD_CONNECT

Issues notification of completed connections.

FD_CLOSE

Issues notification of socket closure.

FD_ROUTING_ INTERFACE_CHANGE

Issues notification of routing interface change for the specified destination.

FD_ADDRESS_ LIST_CHANGE

Issues notification of local address list change for the socket's protocol family.

Invoking WSPAsyncSelectfor a socket cancels any previous WSPAsyncSelector WSPEventSelectfor the same socket. For example, to receive notification for both reading and writing, the Windows Sockets SPI client must call WSPAsyncSelectwith both FD_READ and FD_WRITE, as shown in the following code sample.

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

It is not possible to specify different messages for different events. The following code sample will not work; the second call will cancel the effects of the first, and only FD_WRITE events will be reported with message wMsg2.

Copy Code 
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) lEventwill be set to zero.

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

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

The possible network event codes that may be indicated are shown in the following table.

Value Description

FD_READ

Socket sready for reading.

FD_WRITE

Socket sready for writing.

FD_OOB

OOB data ready for reading on socket s.

FD_ACCEPT

Socket sready for accepting a new incoming connection.

FD_CONNECT

Connection initiated on socket scompleted.

FD_CLOSE

Connection identified by socket shas been closed.

FD_ROUTING_ INTERFACE_CHANGE

Local interface that should be used to send to the specified destination has changed.

FD_ADDRESS_ LIST_CHANGE

List of addresses of the socket's protocol family to which the Windows Socket SPI client can bind has changed.

Return Value

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.

This function always returns SOCKET_ERROR in Windows Embedded CE and sets lpErrnoto WSASYSCALLFAILURE.

The following table shows other possible error codes.

Error value Description

WSAENETDOWN

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

Blocking Windows Sockets call is in progress, or the service provider is still processing a callback function.

WSAENOTSOCK

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 lParammember of the message.

The following tables show the possible error codes for each network event.

Event: FD_CONNECT

Error value Description

WSAEAFNOSUPPORT

Addresses in the specified family cannot be used with this socket.

WSAECONNREFUSED

Attempt to connect was forcefully rejected.

WSAENETUNREACH

Network cannot be reached from this host at this time.

WSAEFAULT

The namelenparameter is incorrect.

WSAEINVAL

Socket is already bound to an address.

WSAEISCONN

Socket is already connected.

WSAEMFILE

No more file descriptors are available.

WSAENOBUFS

No buffer space is available. The socket cannot be connected.

WSAENOTCONN

Socket is not connected.

WSAETIMEDOUT

Attempt to connect timed out without establishing a connection.

Event: FD_CLOSE

Error value Description

WSAENETDOWN

Network subsystem has failed.

WSAECONNRESET

Connection was reset by the remote side.

WSAECONNABORTED

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_ADDRESS_LIST_CHANGE

Error value Description

WSAENETDOWN

Network subsystem has failed.

Event: FD_ROUTING_INTERFACE_CHANGE

Error value Description

WSAENETUNREACH

Specified destination can no longer be reached.

WSAENETDOWN

Network subsystem has failed.

Remarks

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

A Winsock provider will 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 messages for that network event will be posted to the window until the Windows Sockets SPI client makes the function call that implicitly re-enables notification of that network event.

The following table shows the functions that will re-enable notification of events.

Event Re-enabling function

FD_READ

WSPRecvor WSPRecvFrom

FD_WRITE

WSPSendor WSPSendTo

FD_OOB

WSPRecvor WSPRecvFrom

FD_ACCEPT

WSPAcceptunless the error code returned is WSATRY_AGAIN indicating that the condition function returned CF_DEFER

FD_CONNECT

None

FD_CLOSE

None

FD_ROUTING_ INTERFACE_CHANGE

WSPIoctlwith command SIO_ROUTING_INTERFACE_CHANGE

FD_ADDRESS_ LIST_CHANGE

WSPIoctlwith command SIO_ADDRESS_LIST_CHANGE

Any call to the re-enabling routine, even one that 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 if the re-enabling routine is called and the relevant condition is still met after the call, a WSPAsyncSelectmessage is posted to the Windows Sockets SPI client.

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 Winsock SPI client has requested the notification by issuing WSPIoctlwith SIO_ROUTING_INTERFACE_CHANGE or SIO_ADDRESS_LIST_CHANGE correspondingly. Further messages will not be forthcoming until the SPI client re-issues the IOCTL and another change is detected since the IOCTL has been issued.

If any event has already occurred when the Windows Sockets SPI client calls WSPAsyncSelector when the re-enabling function is called, then an appropriate message is posted. For example, consider the following sequence:

  1. An SPI client calls WSPListen.

  2. A connect request is received but not yet accepted.

  3. The Windows Sockets SPI client calls WSPAsyncSelectspecifying 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 WSPSendor WSPSendTofails 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 OOB data separately. If the socket is configured to receive OOB data inline, the OOB (expedited) data is treated as typical 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 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 WSPShutdownon 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 notsend an FD_READ message to indicate this condition.

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

The FD_ADDRESS_LIST_CHANGE message is posted when the list of addresses to which the Winsock SPI client can bind changes after  WSPIoctlwith SIO_ADDRESS_LIST_CHANGE has been issued.

The following table provides a summary of events and conditions that exists for each asynchronous notification message.

Notification message Events and conditions

FD_READ

  • When WSPAsyncSelectis called, if there is data currently available to receive.

  • When data arrives, if FD_READ is not already posted.

  • After WSPRecvor WSPRecvfromis called (with or without MSG_PEEK), if data is still available to receive.

    Note:
    When WSPSetSockOptSO_OOBINLINE is enabled, data includes both typical data and OOB data in the instances noted in the preceding.

FD_WRITE:
  • When WSPAsyncSelectis called, if a WSPSendor WSPSendTois possible.

  • After WSPConnector WSPAccept is called, when connection is established.

  • After WSPSendor WSPSendTofails with WSAEWOULDBLOCK, when WSPSendor WSPSendTois likely to succeed.

  • After WSPBindon a datagram socket. FD_WRITE may or may not occur at this time (implementation dependent). In any case, a connectionless socket is always writeable immediately after WSPBind.

FD_OOB: Only valid when WSPSetSockOptSO_OOBINLINE is disabled (default).
  • When WSPAsyncSelectis called, if there is OOB data currently available to receive with the MSG_OOB flag.

  • When OOB data arrives, if FD_OOB is not already posted.

  • After WSPRecvor WSPRecvfromis called with or withoutMSG_OOB flag, if OOB data is still available to receive.

FD_ACCEPT

  • When WSPAsyncSelectis called, if there is currently a connection request available to accept.

  • When a connection request arrives, if FD_ACCEPT is not already posted.

  • After WSPAcceptis called, if there is another connection request available to accept.

FD_CONNECT

  • When WSPAsyncSelectis called, if there is currently a connection established.

  • After WSPConnectis called, when connection is established (even when WSPConnectsucceeds immediately, as is typical with a datagram socket, and even when it fails immediately).

  • After connect, or WSAConnectwas called with a nonblocking, connection-oriented socket. The initial operation returned with a specific error of WSAEWOULDBLOCK, but the network operation went ahead. Whether the operation eventually succeeds or not, when the outcome has been determined, FD_CONNECT happens. The client should check the error code to determine whether the outcome was a success or failure.

FD_CLOSE: Only valid on connection-oriented sockets (for example, SOCK_STREAM).
  • When WSPAsyncSelectis called, if socket connection has been closed.

  • After the remote system initiated a graceful close, when no data is currently available to receive (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 the local system initiates a graceful close with WSPShutdownand the remote system has responded with End of Data notification (for example, TCP FIN), when no data is currently available to receive.

  • When the remote system terminates connection (for example, sent TCP RST), and lParamwill contain the WSAECONNRESET error value.

    Note:
    FD_CLOSE is not posted after WSPCloseSocketis called.

FD_ROUTING_INTERFACE_CHANGE

  • After WSPIoctlwith SIO_ROUTING_INTERFACE_CHANGE is called, when the local interface that should be used to reach the destination specified in the IOCTL changes.

FD_ADDRESS_LIST_CHANGE

  • After WSPIoctlwith SIO_ADDRESS_LIST_CHANGE is called, when the list of local addresses to which the Winsock SPI client can bind changes.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also