modFltMgr module

Declarations for a file-system minifilter driver: the routines of the Filter Manager, fltmgr.sys, and the structures, enumerations and constants they take.

A minifilter is a driver that the Filter Manager calls before and after the I/O operations of the volumes it is attached to. It can look at an operation, change it, complete it itself or refuse it. In its DriverEntry a minifilter fills a FLT_REGISTRATION with the operations it filters and its callbacks, passes it to FltRegisterFilter, and calls FltStartFiltering. Its unload callback calls FltUnregisterFilter.

The module covers a part of the Filter Manager’s routines: registration, contexts, communication ports, file I/O, file names, volumes and instances, and cancellation. Its types of modWDM, such as FILE_OBJECT, UNICODE_STRING and NTSTATUS, are declared there.

A pointer to a filter, an instance, a volume, a context or a port is a LongPtr. A parameter with no ByVal is passed by reference: a structure, or the variable that receives a result.

Declares

Every routine is in Fltmgr.sys, and each declaration takes the routine’s parameters in the routine’s order.

Name Description
FltAllocateContext Allocates a context of the given type and size.
FltAllocatePoolAlignedWithTag Allocates a buffer aligned for the volume’s device, for noncached I/O.
FltBuildDefaultSecurityDescriptor Builds a default security descriptor for FltCreateCommunicationPort.
FltCancelFileOpen Closes a file that a create operation has just opened, from the post-create callback.
FltCancelIo Cancels an I/O operation the minifilter started.
FltClearCancelCompletion Clears the cancel routine set for an I/O operation.
FltClose Closes a handle that FltCreateFile or one of its variants opened.
FltCloseClientPort Closes a communication client port. ClientPort is the variable that holds the port.
FltCloseCommunicationPort Closes the minifilter’s communication server port.
FltCompareInstanceAltitudes Compares the altitudes of two instances: negative, zero or positive.
FltCreateCommunicationPort Creates the server port that user-mode programs connect to.
FltCreateFile Creates or opens a file, sending the request below the calling instance.
FltCreateFileEx As FltCreateFile, and also returns the file object.
FltCreateFileEx2 As FltCreateFileEx, with a driver create context.
FltDeleteContext Marks a context for deletion.
FltFlushBuffers Sends the file system a flush request for a file.
FltFreeCallbackData Frees a callback data structure that FltAllocateCallbackData allocated.
FltFreePoolAlignedWithTag Frees a buffer that FltAllocatePoolAlignedWithTag allocated.
FltFreeSecurityDescriptor Frees a security descriptor that FltBuildDefaultSecurityDescriptor built.
FltGetBottomInstance Returns the instance at the bottom of a volume’s instance stack.
FltGetContexts Fills a FLT_RELATED_CONTEXTS with the minifilter’s contexts for an operation’s objects.
FltGetDeviceObject Returns the Filter Manager’s volume device object for a volume.
FltGetDiskDeviceObject Returns the disk device object of a volume.
FltGetFileContext Returns the minifilter’s context for a file.
FltGetFileNameInformation Returns name information for the file of an operation, as a pointer to a FLT_FILE_NAME_INFORMATION.
FltGetFileNameInformationUnsafe Returns name information for an open file, from its file object and instance.
FltGetFilterFromInstance Returns the filter that created an instance.
FltGetIrpName Returns the name of a major function code, as a pointer to an ANSI string.
FltGetLowerInstance Returns the next instance below the given one on the same volume.
FltGetRequestorProcessId Returns the ID of the process that requested an I/O operation.
FltGetRequestorProcessIdEx As FltGetRequestorProcessId, as a LongPtr, the size of a handle.
FltGetRoutineAddress Returns the address of a Filter Manager routine by name, or 0 where this Windows has none.
FltGetStreamContext Returns the minifilter’s context for a file stream.
FltGetStreamHandleContext Returns the minifilter’s context for a stream handle.
FltGetTopInstance Returns the instance at the top of a volume’s instance stack.
FltGetUpperInstance Returns the next instance above the given one on the same volume.
FltGetVolumeFromDeviceObject Returns the volume that a volume device object stands for.
FltGetVolumeFromFileObject Returns the volume that a file stream is on.
FltGetVolumeFromInstance Returns the volume that an instance is attached to.
FltGetVolumeName Gets a volume’s name, or with no VolumeName the buffer size the name needs.
FltGetVolumeProperties Fills a FLT_VOLUME_PROPERTIES for a volume.
FltIsDirectory Tells whether a file object is a directory.
FltIsFltMgrVolumeDeviceObject Tells whether a device object is one of the Filter Manager’s volume device objects.
FltIsIoCanceled Tells whether an IRP-based operation has been canceled.
FltObjectDereference Removes a rundown reference from a filter, instance or volume. Pass the pointer as ByVal.
FltObjectReference Adds a rundown reference to a filter, instance or volume. FltObject is As Any: pass the pointer as ByVal, or the routine is given the variable’s address.
FltOpenVolume Returns a handle and a file object for the volume an instance is attached to.
FltParseFileNameInformation Parses the name in a FLT_FILE_NAME_INFORMATION into its extension, stream, final component and parent directory.
FltQueryInformationFile Retrieves information about a file.
FltReadFile Reads from an open file, stream or device.
FltReadFileEx As FltReadFile, with a byte-range lock key and an MDL.
FltReferenceContext Adds a reference to a context.
FltRegisterFilter Registers the minifilter with the Filter Manager, from a FLT_REGISTRATION, and returns its filter pointer.
FltReleaseContext Releases a reference to a context.
FltReleaseContexts Releases every context in a FLT_RELATED_CONTEXTS.
FltReleaseFileNameInformation Releases a file name information structure.
FltSendMessage Sends a message to the user-mode program connected to a client port, and can wait for its reply.
FltSetCancelCompletion Sets a cancel routine for an I/O operation.
FltSetFileContext Sets the minifilter’s context for a file.
FltSetInformationFile Sets information about a file.
FltSetStreamContext Sets the minifilter’s context for a file stream.
FltSetStreamHandleContext Sets the minifilter’s context for a stream handle.
FltStartFiltering Starts filtering: from this call on the Filter Manager calls the minifilter’s callbacks.
FltTagFile Sets a reparse point on a file or directory.
FltTagFileEx As FltTagFile, replacing an existing reparse point only when its tag and GUID match.
FltUnregisterFilter Unregisters the minifilter, from its unload callback.
FltUntagFile Removes a reparse point from a file or directory.
FltWriteFile Writes to an open file, stream or device.
FltWriteFileEx As FltWriteFile, with a byte-range lock key and an MDL.

Delegates

The callbacks a minifilter passes to the Filter Manager. A parameter or a field of one of these types takes AddressOf a procedure of the same signature.

Name Description
FLT_COMPLETE_CANCELED_CALLBACK The cancel routine of FltSetCancelCompletion.
FLT_COMPLETED_ASYNC_IO_CALLBACK Called when an asynchronous FltReadFile or FltWriteFile has finished.
FLT_CONNECT_NOTIFY Called when a user-mode program connects to the server port.
FLT_CONTEXT_ALLOCATE_CALLBACK Allocates a context and returns its address, for FLT_CONTEXT_REGISTRATION.ContextAllocateCallback.
FLT_CONTEXT_CLEANUP_CALLBACK Cleans a context up before it is freed.
FLT_CONTEXT_FREE_CALLBACK Frees a context that the minifilter’s own allocate routine allocated.
FLT_DISCONNECT_NOTIFY Called when the client port’s last handle is closed.
FLT_MESSAGE_NOTIFY Called when a user-mode program sends the minifilter a message.

Types

Each structure has the size of its C structure, and its fields are at the C fields’ offsets, in a 32-bit and in a 64-bit build.

Name Description
FLT_CALLBACK_DATA One I/O operation, as every pre-operation and post-operation callback receives it: its flags, thread, parameter block (Iopb, a pointer to a FLT_IO_PARAMETER_BLOCK), status and requestor mode. The C union of the four filter contexts and the queue links is the array FilterCtxOrQueueLnkCtx.
FLT_CONTEXT_REGISTRATION One context type the minifilter uses, with its size, pool tag and callbacks. FLT_REGISTRATION.ContextRegistration points to an array of them that ends with one of type FLT_CONTEXT_END.
FLT_FILE_NAME_INFORMATION A file’s name and, once parsed, its volume, share, extension, stream, final component and parent directory, each a UNICODE_STRING.
FLT_IO_PARAMETER_BLOCK The parameters of an I/O operation: the IRP flags, the major and minor function, the target file object and instance. The C union Parameters is a Byte array, 48 bytes in a 64-bit build and 28 in a 32-bit one, which a driver copies into the FLT_PARAMETERS_ type of the operation.
FLT_OPERATION_REGISTRATION One major function the minifilter filters, with its pre-operation and post-operation callbacks. FLT_REGISTRATION.OperationRegistration points to an array of them that ends with one whose MajorFunction is IRP_MJ_OPERATION_END.
FLT_PARAMETERS_Create The Create member of the C union FLT_PARAMETERS, for IRP_MJ_CREATE.
FLT_PARAMETERS_DeviceIoControl_Buffered The DeviceIoControl.Buffered member, for a device control request of METHOD_BUFFERED.
FLT_PARAMETERS_FsControl_Common The FileSystemControl.Common member, for IRP_MJ_FILE_SYSTEM_CONTROL.
FLT_PARAMETERS_Others The Others member: five pointer-sized arguments and a LARGE_INTEGER, for any other operation.
FLT_PARAMETERS_Read The Read member, for IRP_MJ_READ.
FLT_PARAMETERS_SetFileInformation The SetFileInformation member, for IRP_MJ_SET_INFORMATION. Its inner C union (ReplaceIfExists and AdvanceOnly, ClusterCount, DeleteHandle) is one LongPtr field named union.
FLT_PARAMETERS_SetVolumeInformation The SetVolumeInformation member, for IRP_MJ_SET_VOLUME_INFORMATION.
FLT_PARAMETERS_Write The Write member, for IRP_MJ_WRITE.
FLT_REGISTRATION What a minifilter registers with FltRegisterFilter: its size and version, flags, context and operation arrays, and callbacks. It is the structure of version FLT_REGISTRATION_VERSION_0202, which has no SectionNotificationCallback.
FLT_RELATED_CONTEXTS The minifilter’s contexts for the objects of an operation, as FltGetContexts fills it.
FLT_RELATED_CONTEXTS_EX As FLT_RELATED_CONTEXTS, with the section context.
FLT_RELATED_OBJECTS The filter, volume, instance, file object and transaction of an operation, as every callback receives them.
FLT_VOLUME_PROPERTIES A volume’s device type, characteristics, sector size and the names of its file system driver and devices, as FltGetVolumeProperties fills it.

Enumerations

Every member has the value of the Filter Manager’s constant of the same name, apart from FLT_ALL_CONTEXTS.

Name Description
FLT_ALLOCATE_CALLBACK_DATA_FLAGS The flag of FltAllocateCallbackDataEx, a routine the package does not declare.
FLT_CALLBACK_DATA_FLAGS The FLTFL_CALLBACK_DATA_ flags of FLT_CALLBACK_DATA.Flags: the kind of operation, whether it was generated or reissued, and whether its parameters were changed.
FLT_CONTEXT_REGISTRATION_FLAGS The flag of FLT_CONTEXT_REGISTRATION.Flags.
FLT_CONTEXT_TYPE The context types, FLT_VOLUME_CONTEXT to FLT_TRANSACTION_CONTEXT, with FLT_CONTEXT_END and FLT_ALL_CONTEXTS. It has no FLT_SECTION_CONTEXT, and FLT_ALL_CONTEXTS is &H3F, without it.
FLT_FILE_NAME_OPTIONS The name format (FLT_FILE_NAME_NORMALIZED, _OPENED, _SHORT), query method and flags that FltGetFileNameInformation takes, combined with Or.
FLT_FILE_NAME_PARSED_FLAGS The bits of FLT_FILE_NAME_INFORMATION.NamesParsed: which parts of the name have been parsed.
FLT_FILESYSTEM_TYPE The file system of a volume, as the instance setup callback receives it: FLT_FSTYPE_NTFS, FLT_FSTYPE_FAT and the others.
FLT_FILTER_UNLOAD_FLAGS The flag the unload callback receives: the unload is mandatory.
FLT_INSTANCE_QUERY_TEARDOWN_FLAGS The flags the instance query teardown callback receives. None is defined.
FLT_INSTANCE_SETUP_FLAGS The flags the instance setup callback receives: an automatic or a manual attachment, a newly mounted or a detached volume.
FLT_IO_OPERATION_FLAGS The flags of FltReadFile and FltWriteFile: noncached, paging, without updating the file’s byte offset.
FLT_POST_OPERATION_FLAGS The flag a post-operation callback receives: the instance is being torn down, and the operation is being drained.
FLT_POSTOP_CALLBACK_STATUS What a post-operation callback returns.
FLT_PREOP_CALLBACK_STATUS What a pre-operation callback returns: pass the operation on with or without a post-operation callback, pend it, complete it.
FLT_REGISTRATION_FLAGS The flags of FLT_REGISTRATION.Flags.
FLT_SET_CONTEXT_OPERATION What FltSetFileContext and the other set routines do when a context is already set: replace it or keep it.
FltPortAccessRights The access rights of a communication port: FLT_PORT_CONNECT and FLT_PORT_ALL_ACCESS.
FltVolumePropertyFlags The flag of FLT_VOLUME_PROPERTIES.Flags: a DAX volume.

Constants

Each constant has the value of the Filter Manager’s constant of the same name.

Name Value Description
FLT_REGISTRATION_VERSION FLT_REGISTRATION_VERSION_0202 The version a FLT_REGISTRATION of this package states.
FLT_REGISTRATION_VERSION_0200 &H0200 The registration version of Windows XP SP2 and Windows Server 2003 SP1.
FLT_REGISTRATION_VERSION_0201 &H0201 The registration version of Windows Vista Beta 2.
FLT_REGISTRATION_VERSION_0202 &H0202 The registration version of Windows Vista.
FLT_REGISTRATION_VERSION_0203 &H0203 The registration version of Windows 8, which adds SectionNotificationCallback.
FLT_VARIABLE_SIZED_CONTEXTS (-1) For FLT_CONTEXT_REGISTRATION.Size: the contexts of this type differ in size.
IRP_MJ_ACQUIRE_FOR_CC_FLUSH &HFB The cache manager acquires a file for a flush.
IRP_MJ_ACQUIRE_FOR_MOD_WRITE &HFD The modified page writer acquires a file.
IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION &HFF A file is acquired to create a section.
IRP_MJ_FAST_IO_CHECK_IF_POSSIBLE &HF3 A check whether fast I/O is possible on a file.
IRP_MJ_MDL_READ &HF1 A fast I/O MDL read.
IRP_MJ_MDL_READ_COMPLETE &HF0 The completion of an MDL read.
IRP_MJ_MDL_WRITE_COMPLETE &HEE The completion of an MDL write.
IRP_MJ_NETWORK_QUERY_OPEN &HF2 A fast I/O query of a file’s network open information.
IRP_MJ_OPERATION_END &H80 Ends the array of FLT_OPERATION_REGISTRATION.
IRP_MJ_PREPARE_MDL_WRITE &HEF A fast I/O MDL write.
IRP_MJ_QUERY_OPEN &HF9 A query of an open file’s information.
IRP_MJ_RELEASE_FOR_CC_FLUSH &HFA The release after a cache manager flush.
IRP_MJ_RELEASE_FOR_MOD_WRITE &HFC The release by the modified page writer.
IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION &HFE The release after a section is created.
IRP_MJ_VOLUME_DISMOUNT &HEC A volume is dismounted.
IRP_MJ_VOLUME_MOUNT &HED A volume is mounted.

The IRP_MJ_ constants are the major function codes that the Filter Manager adds to those of an IRP, for fast I/O and file-system callbacks. Each is a Byte, for FLT_OPERATION_REGISTRATION.MajorFunction.

Example

The operations a minifilter registers: a pre-operation callback for IRP_MJ_CREATE, and the entry that ends the array.

Module MiniFilter
    Private Operations(0 To 1) As FLT_OPERATION_REGISTRATION
    Private Registration As FLT_REGISTRATION
    Private Filter As LongPtr

    Private Function PreCreate(Data As FLT_CALLBACK_DATA, FltObjects As FLT_RELATED_OBJECTS, CompletionContext As LongPtr) As FLT_PREOP_CALLBACK_STATUS
        Return FLT_PREOP_SUCCESS_NO_CALLBACK
    End Function

    Private Function FilterUnload(ByVal Flags As FLT_FILTER_UNLOAD_FLAGS) As Long
        FltUnregisterFilter Filter
        Return 0    ' STATUS_SUCCESS
    End Function

    Public Function RegisterMiniFilter(DriverObject As DRIVER_OBJECT) As Long
        Operations(0).MajorFunction = 0    ' IRP_MJ_CREATE
        Operations(0).PreOperation = AddressOf PreCreate
        Operations(1).MajorFunction = IRP_MJ_OPERATION_END

        Registration.Size = LenB(Registration)
        Registration.Version = FLT_REGISTRATION_VERSION
        Registration.OperationRegistration = VarPtr(Operations(0))
        Registration.FilterUnloadCallback = AddressOf FilterUnload

        Dim status As Long
        status = FltRegisterFilter(DriverObject, Registration, Filter)
        If status >= 0 Then
            status = FltStartFiltering(Filter)
            If status < 0 Then FltUnregisterFilter Filter
        End If
        Return status
    End Function
End Module

See Also