WDF_FILEOBJECT_CONFIG structure (wdfdevice.h)

Article
04/01/2021

[Applies to KMDF and UMDF]

The WDF_FILEOBJECT_CONFIG structure contains configuration information of a driver's framework file objects.

Syntax

typedef struct _WDF_FILEOBJECT_CONFIG {
  ULONG                      Size;
  PFN_WDF_DEVICE_FILE_CREATE EvtDeviceFileCreate;
  PFN_WDF_FILE_CLOSE         EvtFileClose;
  PFN_WDF_FILE_CLEANUP       EvtFileCleanup;
  WDF_TRI_STATE              AutoForwardCleanupClose;
  WDF_FILEOBJECT_CLASS       FileObjectClass;
} WDF_FILEOBJECT_CONFIG, *PWDF_FILEOBJECT_CONFIG;

Members

Size

The size, in bytes, of this structure.

EvtDeviceFileCreate

A pointer to the driver's EvtDeviceFileCreate callback function, or NULL.

EvtFileClose

A pointer to the driver's EvtFileClose callback function, or NULL.

EvtFileCleanup

A pointer to the driver's EvtFileCleanup callback function, or NULL.

AutoForwardCleanupClose

A WDF_TRI_STATE-typed value. For more information about this member, see the following Comments section.

FileObjectClass

A WDF_FILEOBJECT_CLASS-typed value that identifies whether the driver requires a framework file object to represent each file that an application or another driver creates or opens. Additionally, this value specifies where the framework can store the object's handle.

Remarks

The WDF_FILEOBJECT_CONFIG structure is used as input to the WdfDeviceInitSetFileObjectConfig method.

WDF_FILEOBJECT_CONFIG must be initialized by calling WDF_FILEOBJECT_CONFIG_INIT.

Framework Behavior for AutoForwardCleanupClose

If AutoForwardCleanupClose is set to WdfTrue, the framework does the following:

The framework forwards file creation requests to the next-lower driver if the driver does not provide an EvtDeviceFileCreate callback function and has not called WdfDeviceConfigureRequestDispatching to set an I/O queue to receive file creation requests. The framework does not forward file creation requests if the driver provides a callback function or a queue to handle the requests, so the driver must forward, complete, or cancel the requests.
The framework sends file cleanup and close requests to the next-lower driver after calling the driver's EvtFileCleanup and EvtFileClose callback functions.

If AutoForwardCleanupClose is set to WdfFalse, the framework does not forward file creation, cleanup, or close requests. Instead, the framework completes the requests for the driver.

If AutoForwardCleanupClose is set to WdfUseDefault, the framework uses WdfTrue behavior for filter drivers and WdfFalse behavior for function drivers.

Driver Behavior for AutoForwardCleanupClose

Your driver's local I/O target must always receive an equal number of I/O requests with request types of WdfRequestTypeCreate, WdfRequestTypeCleanup, and WdfRequestTypeClose. Therefore, if the driver provides either an EvtDeviceFileCreate callback function or an I/O queue that receives file creation requests, you must use the following rules:

If your driver sets AutoForwardCleanupClose to WdfTrue, the driver must forward all file creation requests to the local I/O target. You must follow this rule because the framework will forward all cleanup and close requests to the local target, whether or not your driver provides EvtFileCleanup and EvtFileClose callback functions.
If your driver sets AutoForwardCleanupClose to WdfFalse, the driver must not forward file creation requests to the local I/O target. You must follow this rule because the framework will not forward cleanup and close requests to the local target, whether or not your driver provides EvtFileCleanup and EvtFileClose callback functions.
If your driver sets AutoForwardCleanupClose to WdfDefault, the driver must follow the rule for WdfTrue if it is a filter driver. The driver must follow the rule for WdfFalse if it is a function driver.

Requirements

Requirement	Value
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfdevice.h (include Wdf.h)

Share via