Skip to content

Latest commit

 

History

History
67 lines (43 loc) · 5.82 KB

IND2Overlapped.md

File metadata and controls

67 lines (43 loc) · 5.82 KB

IND2Overlapped interface

This interface is the base interface that is used for interfaces on which overlapped operations can be performed.

The IND2Overlapped interface inherits the methods of the IUnknown interface. In addition, IND2Overlapped defines the following methods:

Remarks:

Many operations in the NetworkDirect SPI take an OVERLAPPED structure as input. These operations provide the same functionality as Win32 asynchronous I/O operations. For added flexibility, this class also exposes the adapter's underlying file handle on which asynchronous operations are performed.

Providers never invoke callbacks into client code. All notifications are explicitly requested by the client.

IND2Overlapped::CancelOverlappedRequests

Cancels all overlapped requests that are in-progress.

HRESULT CancelOverlappedRequests();

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation succeeded. All requests for asynchronous notifications have been completed with ND_CANCELED. Note that completions for such notification requests may not have been delivered or processed.
  • ND_UNSUCCESSFUL - All outstanding operations could not be canceled.

IND2Overlapped::GetOverlappedResult

Retrieves the result of an overlapped request.

HRESULT GetOverlappedResult(
 [in]  OVERLAPPED *pOverlapped,
 [in]  BOOL wait
);

Parameters:

  • pOverlapped [in]

    The OVERLAPPED structure that was specified when the overlapped operation started.

  • wait [in]

    If this parameter is true, the function does not return until the operation completes. If this parameter is false, and the operation is still pending, the function returns ND_PENDING. Applications that set this parameter to true must have specified a valid event handle in the OVERLAPPED structure when initiating the I/O request.

Return Value:

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

  • ND_SUCCESS - The operation completed successfully.
  • ND_PENDING - The operation is still outstanding and has not yet completed.
  • ND_CANCELED - The NetworkDirect adapter was closed, or a new request for asynchronous notification was requested.
  • ND_DEVICE_REMOVED - The underlying NetworkDirect adapter was removed from the system. Only cleanup operations on the NetworkDirect adapter will succeed.

Remarks:

Clients are required to call this method to determine the final status of an operation, even if they detected completion through the Win32 GetOverlappedResult function, GetQueuedCompletionStatus, or other native Win32 APIs. This requirement allows providers to perform post-processing as necessary.

The behavior of this method is identical to that of the Win32 GetOverlappedResult function. You can call this function; however, you will not get the NetworkDirect return value. Specifically, instead of returning the status through GetLastError mechanisms, IND2Overlapped::GetOverlappedResult simply returns the actual result of the operation. When calling the Win32 GetOverlappedResult function, the value of the parameter specified by lpNumberOfBytesTransferred is specific to the provider implementationand does not convey any meaning to the client.

Multiple instances of this function w.r.t. the same IND2Overlapped interface can be called concurrently as long as the pOverlapped parameters point to different OVERLAPPED objects. To construct a parallel system using this feature, one may have multiple threads waiting for IOCP notifications by calling GetQueuedCompletionStatus, and then process the notification by calling GetOverlappedResult.

When completing a request that is in error, providers cannot change the status value to a success value in their IND2Overlapped::GetOverlappedResult method. They can, however, change a success value to an error, and they can return ND_PENDING if the request was only partially complete and the next phase initiated successfully. In the latter case, clients are required to again wait for the request completes.

The NetworkDirect status values are defined to map 1 to 1 to their corresponding NTSTATUS values. Providers are encouraged to use the WDK function NtDeviceIoControlFile to issue IOCTL requests to preserve the status value that is returned by their kernel driver. Note that this function is marked as deprecated in the Microsoft Platform SDK, but it is valid for device drivers to use given their tight coupling with the operating system.