WSAEventSelect Function

Windows Sockets API

The WSAEventSelect function associates a Windows event object with a set of socket network events and collects all network events that occur for that socket into the specified event object.

Syntax


int WSAEventSelect(
    SOCKET    s,
    WSAEVENT  hEventObject,
    long      lNetworkEvents
);

Parameters

Parameter Description
s A descriptor identifying an unbound socket.
hEventObject A handle to a Windows event object created by a call to WSACreateEvent.
lNetworkEvents A bitmask that specifies the network events to be associated with the event object. This parameter can be a combination of the following values:
  • FD_READ: Network events of type read.
  • FD_WRITE: Network events of type write.
  • FD_OOB: Network events of type out-of-band data reception.
  • FD_ACCEPT: Network events of type accept connection.
  • FD_CONNECT: Network events of type connect completed.
  • FD_CLOSE: Network events of type close.

Return Value

Value Description
0 If the function succeeds.
SOCKET_ERROR (-1) If the function fails. The specific error code can be retrieved by calling WSAGetLastError.

Remarks

The WSAEventSelect function is used to make a socket capable of receiving network event notifications. When a socket is created, it is not initially associated with any event object.

If lNetworkEvents is zero, WSAEventSelect deselects all network events for the specified socket and closes the associated event object. This is equivalent to calling WSAEventSelect with a NULL event object handle.

When WSAEventSelect is called with a non-zero lNetworkEvents, the specified network events are registered for notification through the provided event object. Any previously registered events for the socket are replaced by the new set.

Once registered, whenever one of the specified network events occurs on the socket, the event object associated with the socket is set. The application can then use WSAWaitForMultipleEvents or WSAEnumNetworkEvents to determine which event(s) have occurred.

After an event has been detected, the event object remains set until the application calls WSAResetEvent or WSAEventSelect again, or until the socket is closed.

WSAEventSelect is the preferred method for receiving network event notifications in Windows Sockets applications, as it allows for efficient asynchronous I/O processing.
Note: For a socket to receive network event notifications, it must be associated with an event object using WSAEventSelect. Otherwise, Windows Sockets cannot signal events.
Tip: It is good practice to call WSACleanup when your application is finished using Windows Sockets.

Requirements

Minimum supported client: Windows 2000 Professional

Minimum supported server: Windows 2000 Server

Header: winsock2.h

Library: Ws2_32.lib

DLL: Ws2_32.dll

See Also