EVT_SERCX_FILECLEANUP callback function (sercx.h)

Article
10/21/2021

The EvtSerCxFileCleanup event callback function notifies the serial controller driver that a client has closed the last handle to the file object that represents the serial controller device.

Syntax

EVT_SERCX_FILECLEANUP EvtSercxFilecleanup;

void EvtSercxFilecleanup(
  [in] WDFDEVICE Device
)
{...}

Parameters

[in] Device

A WDFDEVICE handle to the framework device object that represents the serial controller.

Return value

None

Remarks

This function can deallocate certain system resources that the driver previously allocated for the lifetime of the file object. In conjunction with the EvtSerCxFileClose function, the EvtSerCxFileCleanup function should remove the serial controller device from the state in which it is ready to receive and transmit data. The EvtSerCxFileCleanup function should focus specifically on clean-up tasks, such as deallocating memory.

If the serial controller driver previously allocated memory only for the lifetime of the file object that is now closed, the driver should deallocate this memory in either the EvtSerCxFileCleanup or EvtSerCxFileClose function.

Typically, interrupts should be disabled only after the file object is released. Thus, the EvtSerCxFileClose function, and not the EvtSerCxFileCleanup function, should disable the interrupts.

SerCx calls a driver's EvtSerCxFileCleanup function after the last handle to the file object is closed. Because of outstanding I/O requests, this object might not yet be released. After this call, the driver receives no new requests for I/O operations.

SerCx calls a driver's EvtSerCxFileClose function after it calls the driver's EvtSerCxFileCleanup function. SerCx calls the EvtSerCxFileClose function after the file object is released, which occurs only when all outstanding I/O requests are either completed or canceled.

The EvtSerCxFileCleanup function is optional. If a serial controller driver does not implement this function, the driver's EvtSerCxFileClose function must handle all clean-up tasks that are required after the last file handle is closed.

To register an EvtSerCxFileCleanup callback function, the driver must call the SerCxInitialize method.

For more information, see Framework File Objects.

Examples

The function type for this callback is declared in Sercx.h, as follows.

typedef VOID
  EVT_SERCX_FILECLEANUP(
    __in WDFDEVICE Device
    );

To define an EvtSerCxFileCleanup callback function that is named MyEvtSerCxFileCleanup, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as follows.

EVT_SERCX_FILECLEANUP MyEvtSerCxFileCleanup;

Then, implement your callback function as follows.

VOID
  MyEvtSerCxFileCleanup(
    __in WDFDEVICE Device
    )
{ ... }

For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for KMDF Drivers.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 8.
Target Platform	Desktop
Header	sercx.h
IRQL	Called at IRQL <= DISPATCH_LEVEL

Share via