Winsock introduces overlapped I/O and requires that all transport providers support this capability. Overlapped I/O can be performed only on sockets that were created through the WSPSocketfunction with the WSA_FLAG_OVERLAPPED flag set.

For receiving, a client uses WSPRecvor WSPRecvFromto supply buffers into which data is to be received. If one or more buffers are posted prior to the time when data has been received by the network, it is possible that data will be placed into the user's buffers immediately as it arrives and thereby avoid the copy operation that would otherwise occur. If data is already present when receive buffers are posted, it is copied immediately into the user's buffers. If data arrives when no receive buffers have been posted by the application, the service provider resorts to the synchronous style of operation where the incoming data is buffered internally until such time as the client issues a receive call and thereby supplies a buffer into which the data may be copied. An exception to this would be if the application used WSPSetSockOptto set the size of the receive buffer to zero. In this instance, reliable protocols would only allow data to be received when application buffers had been posted, and data on unreliable protocols would be lost.

On the sending side, clients use WSPSendor WSPSendToto supply pointers to filled buffers and then agree not to disturb the buffers in any way until the network has consumed the buffer's contents.

Overlapped send and receive calls return immediately. A return value of zero indicates that the I/O operation completed immediately and that the corresponding completion indication has already occurred. That is, the associated event object has been signaled, or the completion routine has called. A return value of SOCKET_ERROR coupled with an error code of WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that a subsequent indication will be provided when send buffers have been consumed or when receive buffers are filled. Any other error code indicates that the overlapped operation was not successfully initiated and that no completion indication will be forthcoming.

Both send and receive operations can be overlapped. The receive functions may be invoked multiple times to post receive buffers in preparation for incoming data, and the send functions may be invoked multiple times to queue up multiple buffers to be sent. Note that while a series of overlapped send buffers will be sent in the order supplied, the corresponding completion indications may occur in a different order. Likewise, on the receiving side, buffers will be completed in the order they are supplied, but completion indications may occur in a different order.

Deferred completion of overlapped I/O is also available for WSPIoctl.

Delivering Completion Indications

Service providers have two ways to indicate overlapped completion: setting a client-specified event object or invoking a client-specified completion routine. In both cases a data structure, WSAOVERLAPPED, is associated with each overlapped operation. This structure is allocated by the client and used by it to indicate which event object (if any) is to be set when completion occurs. The WSAOVERLAPPEDstructure may be used by the service provider as a place to store a handle to the results, for example, number of bytes transferred, updated flags, and error codes, for a particular overlapped operation. To obtain these results clients must invoke WSPGetOverlappedResult, passing in a pointer to the corresponding overlapped structure.

If event based completion indication is selected for a particular overlapped I/O request, the WSPGetOverlappedResultroutine may itself be used by clients to either poll or wait for completion of the overlapped operation. If completion-routine-based completion indication is selected for a particular overlapped I/O request, only the polling option of WSPGetOverlappedResultis available. A client may also use other means to wait until the corresponding event object has been signaled or the specified completion routine has been invoked by the service provider. Once completion has been indicated, the client may invoke WSPGetOverlappedResult, with the expectation that the call will complete immediately.

Summary of Overlapped Completion Indication Mechanisms in the SPI

The following table summarizes the completion semantics for an overlapped socket, showing the various combinations of lpOverlapped, hEvent,and lpCompletionRoutine.

See Also