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 performs overlapped I/O completion notification for overlapped I/O operations.

Copy Code 
int WSPAPI WPUCompleteOverlappedRequest(
  SOCKET 
s,
  LPWSAOVERLAPPED 
lpOverlapped,
  DWORD 
dwError,
  DWORD 
cbTransferred,
  LPINT 
lpErrno
);

Parameters

s

[in] Handle to service provider socket created by WPUCreateSocketHandle.

lpOverlapped

[in] Pointer to a WSAOVERLAPPEDstructure associated with the overlapped I/O operation for which to notify completion.

dwError

[in] Completion status of the overlapped I/O operation for which to notify completion.

cbTransferred

[in] Number of bytes transferred to or from client buffers. The direction of the transfer depends on the send or receive nature of the overlapped I/O operation for which to notify completion.

lpErrno

[out] Pointer to the error code.

Return Values

If successful, WPUCompleteOverlappedRequestreturns zero and notifies completion of the overlapped I/O operation according to the mechanism selected by the client. It signals an event found in the WSAOVERLAPPEDstructure referenced by lpOverlappedand/or queues a completion status report to any completion port associated with the socket.

If the function is not successful, it returns SOCKET_ERROR, and a specific error code is available in lpErrno.

Error value Description

WSAEINVAL

Socket is not a socket created by WPUCreateSocketHandle.

Remarks

The WPUCompleteOverlappedRequestfunction performs overlapped I/O completion notification for overlapped I/O operations when the client-specified completion mechanism is other than a user mode asynchronous procedure call (APC). The function WPUCompleteOverlappedRequestis used by service providers that do not implement Installable File System (IFS) functionality directly for the socket handles they expose.

This function can only be used for socket handles created by WPUCreateSocketHandleand not for handles created by a service provider directly. Windows Socket 2 architecture keeps track of any completion port association with a socket created by WPUCreateSocketHandleand can make a correct decision between completion port-based notification and event-based notification. WPUCompleteOverlappedRequestwill perform a completion notification as requested by the client whether or not a socket handle has been associated with a completion port.

Note:
This function is different from other functions with the WPUprefix in that it is not accessed through the upcall table. Instead, it is exported directly by Ws2.dll Service providers that need to use this function should link with Ws2.lib or use appropriate operating system functions, such as LoadLibraryand GetProcAddress, to retrieve the function pointer.

If the client selects a user mode APC as the notification method, the service provider should use WPUQueueApcor another appropriate operating system function to perform the completion notification.

When WPUCompleteOverlappedRequestqueues a completion indication, it sets the InternalHighmember of the WSAOVERLAPPEDstructure to the number of bytes transferred. Then, it sets the Internalmember to an OS-dependent value other than the special value WSS_OPERATION_IN_PROGRESS. There might be a slight delay after WPUCompleteOverlappedRequestreturns before these values appear, since processing might occur asynchronously. However, the InternalHighvalue (byte count) is guaranteed to be set by the time the Internalvalue is set.

Interaction with WSPGetOverlappedResult

The behavior of WPUCompleteOverlappedRequestplaces some constraints on how a service provider implements WSPGetOverlappedResultsince only the Offsetand OffsetHighmembers of the WSAOVERLAPPEDstructure are exclusively controlled by the service provider. However, three values (byte count, flags, and error) must be retrieved from the structure by WSPGetOverlappedResult. A service provider can accomplish this in any way, as long as the latter function interacts with the behavior of WPUCompleteOverlappedRequestproperly. A typical implementation is as follows:

At the start of overlapped processing, the service provider sets Internalto WSS_OPERATION_IN_PROGRESS. When the I/O operation has completed, the provider sets OffsetHighto the Windows Socket 2 error code resulting from the operation, sets Offsetto the flags resulting from the I/O operation, and calls WPUCompleteOverlappedRequest, passing the transfer byte count as one of the parameters. WPUCompleteOverlappedRequesteventually sets InternalHighto the transfer byte count, then sets Internalto a value other than WSS_OPERATION_IN_PROGRESS.

When WSPGetOverlappedResultis called, the service provider checks Internal. If its value is WSS_OPERATION_IN_PROGRESS, the provider waits on the event handle in the hEventmember or returns an error, based on the setting of the FWAIT flag of WSPGetOverlappedResult. If the operation is not in progress, or after wait completion, the provider retrieves the values from InternalHigh, OffsetHigh, and Offsetas the transfer count, operation result error code, and flags, respectively.

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