Event Objects (Windows Sockets 2)

Introducing overlapped I/O requires a mechanism for applications to unambiguously associate send and receive requests with their subsequent completion indications. In Windows Sockets 2, this is accomplished with event objects that are modeled after Windows events. Windows Sockets event objects are fairly simple constructs that can be created and closed, set and cleared, and waited upon and polled. Their prime utility is the ability of an application to block and wait until one or more event objects become set.

Applications use WSACreateEvent to obtain an event object handle that can then be supplied as a required parameter to the overlapped versions of send and receive calls ( WSASend, WSASendTo, WSARecv, WSARecvFrom). The event object, which is cleared when first created, is set by the transport providers when the associated overlapped I/O operation has completed (either successfully or with errors). Each event object created by WSACreateEvent should have a matching WSACloseEvent to destroy it.

Event objects are also used in WSAEventSelect to associate one or more FD_XXX network events with an event object. This is described in Asynchronous Notification Using Event Objects.

In 32-bit environments, event object–related functions, including WSACreateEvent, WSACloseEvent, WSASetEvent, WSAResetEvent, and WSAWaitForMultipleEvents are directly mapped to the corresponding native Windows functions, using the same function name, but without the WSA prefix.