IWDFIoQueue::Purge method (wudfddi.h)

Article
02/22/2024

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The Purge method directs the framework to reject new incoming I/O requests and to cancel all outstanding requests.

Syntax

void Purge(
  [in, optional] IQueueCallbackStateChange *pPurgeComplete
);

Parameters

[in, optional] pPurgeComplete

A pointer to the IQueueCallbackStateChange interface whose method the framework calls to deliver queue state to the driver. The framework calls the method after all requests are canceled. This parameter is optional and can be NULL.

Return value

None

Remarks

The framework cancels unprocessed requests in the queue. For requests that are delivered to the driver and marked cancelable, the framework calls IRequestCallbackCancel::OnCancel.

The driver should ensure that only one of the following methods is in progress at any given time:

IWDFIoQueue::Stop
IWDFIoQueue::Drain
IWDFIoQueue::Purge

For example, if the driver previously called Purge, it should wait for notification from the method of the interface that the pPurgeComplete parameter points to before it calls either Stop or Drain. Violating this rule results in termination of the host process.

Examples

The following code example shows how to stop requests to a queue.

VOID
CUmdfHidFile::OnCleanupFile(
    __in IWDFFile* /* WdfFile */
    )
/*++
    This method handles the cleanup operation for the file object.  
    Because the file is disabled, no new reports should be added to the ring buffer.
--*/
{
    this->Disable();

    //
    // Stop all current requests to read reports.
    //

    m_GetReportQueue->Purge(NULL);
}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.5
Header	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll