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
- modWDM module – the types and routines every driver uses
- Filter Manager concepts – Microsoft’s introduction to minifilters
- fltkernel.h – Microsoft’s reference for the Filter Manager’s routines
- fafalone/FsMinifilter – a minifilter written with this package, by its author