Windows API Reference

Microsoft Developer Network (MSDN)

Winsock I/O Management

This section details the functions and mechanisms used for managing input and output operations within the Windows Sockets API (Winsock).

select

int select( [in] int nfds, [in, out, optional] fd_set *readfds, [in, out, optional] fd_set *writefds, [in, out, optional] fd_set *exceptfds, [in, optional] const TIMEVAL *timeout );

The select function determines the status of multiple file descriptors, waiting until one or more of the descriptors are ready for some type of I/O operation (either reading, writing, or an exceptional condition), or until a timeout occurs.

Parameters

  • nfds: The highest-numbered file descriptor in any of the sets, plus one.
  • readfds: An optional pointer to a set of socket descriptors to be checked for readability.
  • writefds: An optional pointer to a set of socket descriptors to be checked for writability.
  • exceptfds: An optional pointer to a set of socket descriptors to be checked for errors.
  • timeout: An optional pointer to a TIMEVAL structure that specifies the amount of time to wait for a descriptor to become ready.

Return Value

  • Returns the total number of socket descriptors contained in the descriptor sets that are ready for reading, writing, or exceptions.
  • Returns 0 if the timeout expires before any socket descriptor is ready.
  • Returns SOCKET_ERROR if an error occurred and WSAGetLastError can be called to obtain a specific error code.

Remarks

The select function is a fundamental tool for network programming, allowing applications to efficiently manage multiple socket connections without blocking on a single operation. It's crucial for building responsive servers and clients.

See also: fd_set, TIMEVAL.

WSAEventSelect

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

The WSAEventSelect function associates a network event object with a specific set of network events for a given socket. This enables an application to receive asynchronous network event notifications.

Parameters

  • s: A descriptor identifying the socket.
  • hEventObject: A handle to the event object to be associated with the socket.
  • lNetworkEvents: A bitmask specifying the network events to be monitored.

Return Value

  • If no error occurs, WSAEventSelect returns zero.
  • Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Remarks

WSAEventSelect provides an event-driven mechanism for handling network I/O. When a specified network event occurs on the socket, the associated event object is signaled.

See also: Network Event Constants, WSAGetLastError.

WSAEnumNetworkEvents

int WSAEnumNetworkEvents( [in] SOCKET s, [in] WSAEVENT hEventObject, [out] LPWSANETWORKEVENTS lpNetworkEvents );

The WSAEnumNetworkEvents function retrieves a bitmask of network events that have occurred on the specified socket and resets the event object that was used to signal these events.

Parameters

  • s: A descriptor identifying the socket.
  • hEventObject: An optional handle to the event object. If NULL, all network events associated with the socket are cleared.
  • lpNetworkEvents: A pointer to a WSANETWORKEVENTS structure that receives a bitmask of occurred network events and associated error codes.

Return Value

  • If no error occurs, WSAEnumNetworkEvents returns zero.
  • Otherwise, it returns SOCKET_ERROR, and a specific error code can be retrieved by calling WSAGetLastError.

Remarks

This function is typically called after WSAEventSelect has been used and an event has been signaled. It allows the application to determine which specific network events have occurred and to handle them accordingly.

See also: WSANETWORKEVENTS, WSAEventSelect.

WSAWaitForMultipleEvents

DWORD WSAWaitForMultipleEvents( [in] DWORD cEvents, [in, optional] const WSAEVENT hEvents[], [in] BOOL bWaitAll, [in] DWORD dwTimeout, [in] BOOL bAlertable );

The WSAWaitForMultipleEvents function determines if any one or all of the specified event objects in the array are in a signaled state, or if the timeout interval expires.

Parameters

  • cEvents: The number of event objects in the array.
  • hEvents: A pointer to an array of event object handles.
  • bWaitAll: A boolean that specifies the wait condition.
  • dwTimeout: The time interval to wait, in milliseconds.
  • bAlertable: A boolean that indicates whether the function is alertable.

Return Value

  • Returns an index into the array of event objects that caused the wait to return (if bWaitAll is FALSE).
  • Returns 0 (if bWaitAll is TRUE and at least one event is signaled).
  • Returns WSA_WAIT_TIMEOUT if the timeout interval expires.
  • Returns WSA_WAIT_ABORTED if the wait was aborted.

Remarks

This function is useful for managing multiple asynchronous I/O operations that are signaled via Winsock event objects. It provides a robust way to synchronize progress across several network operations.

Non-Blocking Sockets

Winsock supports both blocking and non-blocking socket modes. In non-blocking mode, socket operations (like send or recv) do not wait for the operation to complete. Instead, they return immediately, indicating whether the operation succeeded, failed, or is pending.

To set a socket to non-blocking mode, use the ioctlsocket function with the FIONBIO command:


int iResult = ioctlsocket(mySocket, FIONBIO, (u_long FAR*)&nonBlocking);
if (iResult == SOCKET_ERROR) {
    // Handle error
}

I/O Completion Ports (IOCP)

For high-performance server applications, Winsock integrates with Windows I/O Completion Ports (IOCP). IOCP provides a scalable and efficient mechanism for handling I/O operations asynchronously. Applications can submit I/O requests to a completion port, and a worker thread can efficiently retrieve completed I/O operations without blocking.

Key functions related to IOCP in Winsock include:

  • CreateIoCompletionPort
  • PostQueuedCompletionStatus
  • GetQueuedCompletionStatus

Using IOCP typically involves creating a completion port, associating sockets with it, and then having worker threads repeatedly call GetQueuedCompletionStatus to process completed I/O operations.