WdfFileObjectGetFileName function (wdffileobject.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfFileObjectGetFileName method returns the file name that a specified framework file object contains.

Syntax

PUNICODE_STRING WdfFileObjectGetFileName(
  [in] WDFFILEOBJECT FileObject
);

Parameters

[in] FileObject

A handle to a framework file object.

Return value

WdfFileObjectGetFileName returns a pointer to a UNICODE_STRING structure that contains the file name. The method returns NULL if there is no WDM file object for the specified framework file object, or if it is called at an IRQL higher than PASSIVE_LEVEL.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

If a driver specified a reference string when it called WdfDeviceCreateDeviceInterface, WdfFileObjectGetFileName returns the reference string prepended by a backslash. To determine the reference string, remove the backslash.

The returned string can contain a file name or a reference string. The string does not contain the device name. If an application or kernel-mode component has opened the device instead of a file, with no reference string, the Length member of the returned UNICODE_STRING structure is zero.

Your driver should only call WdfFileObjectGetFileName while it is processing a file creation request (WdfRequestTypeCreate request type). Your driver might process WdfRequestTypeCreate-typed I/O requests in an EvtDeviceFileCreate callback function.

Or, instead of providing an EvtDeviceFileCreate callback function, the driver can call WdfDeviceConfigureRequestDispatching to set an I/O queue to receive all file creation requests (WdfRequestTypeCreate request type). The driver will subsequently receive file creation requests in the queue's EvtIoDefault request handler.

For more information about framework file objects, see Framework File Objects.

For more information about file names, see Controlling Device Namespace Access.

For more information about reference strings, see IoRegisterDeviceInterface.

Examples

The following code example shows how an EvtDeviceFileCreate callback function can obtain the name of the file that an application has opened.

VOID
MyEvtDeviceFileCreate (
    IN WDFDEVICE  Device,
    IN WDFREQUEST  Request,
    IN WDFFILEOBJECT  FileObject
    )
{
    PUNICODE_STRING  fileName;

    fileName = WdfFileObjectGetFileName(FileObject);
...

}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdffileobject.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)