IFWXExternalIOCompletion::CompleteAsyncIO method

Article
08/27/2012

Applies to: desktop apps only

The CompleteAsyncIO method receives a notification from the Microsoft Firewall service when an asynchronous Windows I/O operation involving reading or writing to a file on a disk completes.

Syntax

HRESULT CompleteAsyncIO(
  [in]  BOOL fSuccess,
  [in]  DWORD NumberOfBytesTransfered,
  [in]  DWORD Win32ErrorCode,
  [in]  IFWXOverlapped *pOverlapped,
  [in]  UserContextType UserData
);

Parameters

fSuccess [in]
Success flag. If TRUE, the I/O operation succeeded. If FALSE, it failed.
NumberOfBytesTransfered [in]
Number of bytes transferred during a successful I/O operation.
Win32ErrorCode [in]
Windows error code for a failed I/O operation.
pOverlapped [in]
Pointer to the IFWXOverlapped interface on the overlapped object used for this operation.
UserData [in]
The UserData parameter set in the call to the IFWXOverlapped::SetNotificationInterface method.

Return value

Implementations of this method should handle any run-time error and return S_OK.

Remarks

If the Firewall service is performing asynchronous I/O for an operating system file, it must have access to the Windows Sockets OVERLAPPED structure and a means of setting up a callback when the I/O is completed.

The IFWXOverlapped interface gets a pointer to the Windows Sockets OVERLAPPED structure. The IFWXOverlapped interface also provides the link between the OVERLAPPED structure and a completion notification interface and includes user context information that allows the filter to distinguish between different notifications.

Use the IFWXOverlapped::SetNotificationInterface method to set the notification interface and user context. Then use the IFWXOverlapped::GetOverlapped method to get an OVERLAPPED structure that will be used in a call to an asynchronous Windows API.

The call to the Windows API must use a handle that is associated with the Firewall service's completion port. For more information, see the IFWXFirewall::HookToCompletionPort method.

When the overlapped operation completes, the Firewall service will get the completion notification in its completion port and will call the completion notification method of the specified interface.

The UserData parameter provides a context to the notification. You can use the same notification interface for completion notifications from distinct network socket objects and differentiate between them by using different values for the UserData parameter.

Examples

This example implementation of IFWXExternalIOCompletion::CompleteAsycnIO is taken from the Exeblock sample filter.

HRESULT
STDMETHODCALLTYPE
CEBScannerDataFilter::CompleteAsyncIO(
    /* [in] */ BOOL fSuccess,
    /* [in] */ DWORD NumberOfBytesTransfered,
    /* [in] */ DWORD Win32ErrorCode,
    /* [in] */ IFWXOverlapped __RPC_FAR *pOverlapped,
    /* [in] */ UserContextType UserData)
{
    UNREFERENCED_PARAMETER(UserData);
    UNREFERENCED_PARAMETER(Win32ErrorCode);
    UNREFERENCED_PARAMETER(NumberOfBytesTransfered);
    
    // The _Abort method closes and releases both sockets.
    if (!fSuccess) _Abort();
    pOverlapped->Release();
    IFWXSocket *pISocket = _GetExternalSocket();
    if (pISocket)
    {
        pISocket->Recv(NULL, this, 0);
        pISocket->Release();
    }
    return S_OK;
}

Requirements

Minimum supported client	None supported
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 (64-bit only)
Version	Forefront Threat Management Gateway (TMG) 2010
Header	Wspfwext.idl