WPUCompleteOverlappedRequest (Compact 2013)

Article
11/04/2015

3/26/2014

This function performs overlapped I/O completion notification for overlapped I/O operations.

Syntax

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 WSAOVERLAPPED structure 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, WPUCompleteOverlappedRequest returns 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 WSAOVERLAPPED structure referenced by lpOverlapped and/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 WPUCompleteOverlappedRequest function 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 WPUCompleteOverlappedRequest is 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 WPUCreateSocketHandle and 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 WPUCreateSocketHandle and can make a correct decision between completion port-based notification and event-based notification. WPUCompleteOverlappedRequest will 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 WPU prefix 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 LoadLibrary and GetProcAddress, to retrieve the function pointer.

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

When WPUCompleteOverlappedRequest queues a completion indication, it sets the InternalHigh member of the WSAOVERLAPPED structure to the number of bytes transferred. Then, it sets the Internal member to an OS-dependent value other than the special value WSS_OPERATION_IN_PROGRESS. There might be a slight delay after WPUCompleteOverlappedRequest returns before these values appear, since processing might occur asynchronously. However, the InternalHigh value (byte count) is guaranteed to be set by the time the Internal value is set.

Interaction with WSPGetOverlappedResult

The behavior of WPUCompleteOverlappedRequest places some constraints on how a service provider implements WSPGetOverlappedResult since only the Offset and OffsetHigh members of the WSAOVERLAPPED structure 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 WPUCompleteOverlappedRequest properly. A typical implementation is as follows:

At the start of overlapped processing, the service provider sets Internal to WSS_OPERATION_IN_PROGRESS. When the I/O operation has completed, the provider sets OffsetHigh to the Windows Socket 2 error code resulting from the operation, sets Offset to the flags resulting from the I/O operation, and calls WPUCompleteOverlappedRequest, passing the transfer byte count as one of the parameters. WPUCompleteOverlappedRequest eventually sets InternalHigh to the transfer byte count, then sets Internal to a value other than WSS_OPERATION_IN_PROGRESS.

When WSPGetOverlappedResult is called, the service provider checks Internal. If its value is WSS_OPERATION_IN_PROGRESS, the provider waits on the event handle in the hEvent member 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 Offset as the transfer count, operation result error code, and flags, respectively.

Requirements

Header	ws2spi.h
Library	Ws2.lib