S.l.e!ep.￠%

??????? 04、注冊FsFilter回調例程：

??????? FsFilter通知回調例程在下層文件系統執行某些操作之前或之后調用。如果需要獲取更多有關于FsFilter回調例程相關信息，可參見FsRtlRegisterFileSystemFilterCallbacks例程
??????? 為了注冊FsFilter的通知回調例程必須分配并初始化FS_FILTER_CALLBACKS結構體，然后向該結構體中促出FsFilter回調例 程，并將存儲有Callbacks parameter到FsRtlRegisterFileSystemFilterCallbacks中。
??????? 例如：FileSpy驅動范例按如下方式注冊FsFilter回調。

fsFilterCallbacks.SizeOfFsFilterCallbacks = sizeof(FS_FILTER_CALLBACKS);
fsFilterCallbacks.PreAcquireForSectionSynchronization = SpyPreFsFilterOperation;
fsFilterCallbacks.PostAcquireForSectionSynchronization = SpyPostFsFilterOperation;
fsFilterCallbacks.PreReleaseForSectionSynchronization = SpyPreFsFilterOperation;
fsFilterCallbacks.PostReleaseForSectionSynchronization = SpyPostFsFilterOperation;
fsFilterCallbacks.PreAcquireForCcFlush = SpyPreFsFilterOperation;
fsFilterCallbacks.PostAcquireForCcFlush = SpyPostFsFilterOperation;
fsFilterCallbacks.PreReleaseForCcFlush = SpyPreFsFilterOperation;
fsFilterCallbacks.PostReleaseForCcFlush = SpyPostFsFilterOperation;
fsFilterCallbacks.PreAcquireForModifiedPageWriter = SpyPreFsFilterOperation;
fsFilterCallbacks.PostAcquireForModifiedPageWriter = SpyPostFsFilterOperation;
fsFilterCallbacks.PreReleaseForModifiedPageWriter = SpyPreFsFilterOperation;
fsFilterCallbacks.PostReleaseForModifiedPageWriter = SpyPostFsFilterOperation;

status = FsRtlRegisterFileSystemFilterCallbacks(DriverObject, &fsFilterCallbacks);

MSDN的詳細解釋

File system filter drivers call the FsRtlRegisterFileSystemFilterCallbacks routine to register notification callback routines to be invoked when the underlying file system performs certain operations.

文件系統過濾驅動調用 FsRtlRegisterFileSystemFilterCallbacks 函數注冊需通知回調函數，這些回調函數將在文件系統的相關操作之前被調用

				
						
NTSTATUS
				
??FsRtlRegisterFileSystemFilterCallbacks(
????IN?PDRIVER_OBJECT??FilterDriverObject,
????IN?PFS_FILTER_CALLBACKS??Callbacks
????);?

Parameters

FilterDriverObject

Pointer to the driver object for the filter driver.

Callbacks

Pointer to a structure that contains the entry points of caller-supplied notification callback routines.

This structure is defined as follows.

Note: All of the callback entry points are optional and can be NULL.

typedef?struct?_FS_FILTER_CALLBACKS?{
????ULONG?SizeOfFsFilterCallbacks;
????ULONG?Reserved;
????PFS_FILTER_CALLBACK?PreAcquireForSectionSynchronization;
????PFS_FILTER_COMPLETION_CALLBACK?PostAcquireForSectionSynchronization;
????PFS_FILTER_CALLBACK?PreReleaseForSectionSynchronization;
????PFS_FILTER_COMPLETION_CALLBACK?PostReleaseForSectionSynchronization;
????PFS_FILTER_CALLBACK?PreAcquireForCcFlush;
????PFS_FILTER_COMPLETION_CALLBACK?PostAcquireForCcFlush;
????PFS_FILTER_CALLBACK?PreReleaseForCcFlush;
????PFS_FILTER_COMPLETION_CALLBACK?PostReleaseForCcFlush;
????PFS_FILTER_CALLBACK?PreAcquireForModifiedPageWriter;
????PFS_FILTER_COMPLETION_CALLBACK?PostAcquireForModifiedPageWriter;
????PFS_FILTER_CALLBACK?PreReleaseForModifiedPageWriter;
????PFS_FILTER_COMPLETION_CALLBACK?PostReleaseForModifiedPageWriter;
}?FS_FILTER_CALLBACKS,?*PFS_FILTER_CALLBACKS;

The filter callback routine and its parameters are defined as follows:

typedef
NTSTATUS?(*PFS_FILTER_CALLBACK)?(
??????????????IN?PFS_FILTER_CALLBACK_DATA?Data,
??????????????OUT?PVOID?*CompletionContext
??????????????);

Parameter	Meaning
Data	Pointer to the callback data structure for this operation.? 指向這個操作的回調數據結構
CompletionContext	Context information to be passed to the filter completion callback routine. Set to NULL if no context information is to be passed or if there is no corresponding filter completion callback routine.??傳給過濾器完成回調函數的上下文信息

The filter completion callback routine and its parameters are defined as follows:

typedef
VOID?(*PFS_FILTER_COMPLETION_CALLBACK)?(
??????????IN?PFS_FILTER_CALLBACK_DATA?Data,
??????????IN?NTSTATUS?OperationStatus,
??????????IN?PVOID?CompletionContext
??????????);

Parameter	Meaning
Data	Pointer to the callback data structure for this operation.
OperationStatus	Status of the operation. If the file system successfully performed the operation, this parameter is set to STATUS_SUCCESS. Otherwise, it is set to an appropriate error status value.
CompletionContext	Context information that was set in the filter callback routine. This is set to NULL if no information is passed or if there is no corresponding filter callback routine.

The callback data structure and its members are defined as follows:

typedef?struct?_FS_FILTER_CALLBACK_DATA?{
????ULONG?SizeOfFsFilterCallbackData;
????UCHAR?Operation;
????UCHAR?Reserved;
????struct?_DEVICE_OBJECT?*DeviceObject;
????struct?_FILE_OBJECT?*FileObject;
????FS_FILTER_PARAMETERS?Parameters;
}?FS_FILTER_CALLBACK_DATA,?*PFS_FILTER_CALLBACK_DATA;

Member	Meaning
SizeOfFsFilterCallbackData	Size of the callback data structure.
Operation	File system operation for which the callback routine is to be invoked. This operation can be of the following: FS_FILTER_ACQUIRE_FOR_SECTION_SYNCHRONIZATION FS_FILTER_RELEASE_FOR_SECTION_SYNCHRONIZATION FS_FILTER_ACQUIRE_FOR_MOD_WRITE FS_FILTER_RELEASE_FOR_MOD_WRITE FS_FILTER_ACQUIRE_FOR_CC_FLUSH FS_FILTER_RELEASE_FOR_CC_FLUSH
Reserved	Reserved for system use.
DeviceObject	Device object for this operation.
FileObject	File object for this operation.
Parameters	Union containing any operation-specific parameters.

The filter parameter union is defined as follows:

typedef?union?_FS_FILTER_PARAMETERS?{
????struct?{
????????PLARGE_INTEGER?EndingOffset;
????????PERESOURCE?*ResourceToRelease;
????}?AcquireForModifiedPageWriter;
????struct?{
????????PERESOURCE?ResourceToRelease;
????}?ReleaseForModifiedPageWriter;
????struct?{
????????FS_FILTER_SECTION_SYNC_TYPE?SyncType;
????????ULONG?PageProtection;
????}?AcquireForSectionSynchronization;
????struct?{
????????PVOID?Argument1;
????????PVOID?Argument2;
????????PVOID?Argument3;
????????PVOID?Argument4;
????????PVOID?Argument5;
????}?Others;
}?FS_FILTER_PARAMETERS,?*PFS_FILTER_PARAMETERS;

Parameter	Meaning
EndingOffset	Offset of the last byte being written plus one.
ResourceToRelease	Resource to be released.
SyncType	Type of synchronization requested for the section: SyncTypeCreateSection if a section is being created, SyncTypeOther otherwise.
PageProtection	Type of page protection requested for the section. Must be zero if SyncType is SyncTypeOther. Otherwise, one of the following flags, possibly ORed with PAGE_NOCACHE: PAGE_READONLY PAGE_READWRITE PAGE_WRITECOPY PAGE_EXECUTE
Argument1	Reserved for future use.
Argument2	Reserved for future use.
Argument3	Reserved for future use.
Argument4	Reserved for future use.
Argument5	Reserved for future use.

Return Value

FsRtlRegisterFileSystemFilterCallbacks can return one of the following status values:

STATUS_SUCCESS

The callback routines were successfully registered.

STATUS_INSUFFICIENT_RESOURCES

FsRtlRegisterFileSystemFilterCallbacks encountered a pool allocation failure when allocating memory to store the callback information.

STATUS_INVALID_PARAMETER

One of the parameters is invalid.

Comments

FsRtlRegisterFileSystemFilterCallbacks should only be called by file system filter drivers, and only from the filter's DriverEntry routine.

FsRtlRegisterFileSystemFilterCallbacks registers the notification callback routines that were specified in the Callbacks parameter to be invoked when requests for certain file operations are sent to the underlying file system.

Callback routines are currently defined for the following operations:

Operation	Notification Callback Routine and Callback Completion Routine
The memory manager acquires a file exclusively before creating a memory-mapped section for a portion of the file. Note: For this operation, SyncType is set to SyncTypeCreateSection.	PreAcquireForSectionSynchronization PostAcquireForSectionSynchronization
The memory manager releases a file after creating a memory-mapped section for a portion of the file.	PreReleaseForSectionSynchronization PostReleaseForSectionSynchronization
A kernel component (such as the cache manager) acquires a file exclusively before temporarily disabling section creation for a portion of the file. Note: For this operation, SyncType is set to SyncTypeOther.	PreAcquireForSectionSynchronization PostAcquireForSectionSynchronization Note: PreAcquireForSectionSynchronization should always return a success status code (such as STATUS_SUCCESS) for this operation. Returning any other type of status code causes the system to ASSERT on a checked build. (On free builds, the status code is ignored.)
A kernel component (such as the cache manager) releases a file after temporarily disabling section creation for a portion of the file.	PreReleaseForSectionSynchronization PostReleaseForSectionSynchronization
The cache manager acquires a file exclusively before flushing a portion of the file from the cache.	PreAcquireForCcFlush PostAcquireForCcFlush
The cache manager releases a file after flushing a portion of the file from the cache.	PreReleaseForCcFlush PostReleaseForCcFlush
The modified page writer acquires a file exclusively before writing a portion of the file to disk.	PreAcquireForModifiedPageWriter PostAcquireForModifiedPageWriter
The modified page writer releases a file after writing a portion of the file to disk.	PreReleaseForModifiedPageWriter PostReleaseForModifiedPageWriter

The filter notification callback routine is invoked before the operation request is passed to lower-level filter drivers and the underlying file system. In the callback routine, the filter driver should perform any needed processing and immediately return STATUS_SUCCESS. If a filter driver's callback routine returns a status value other than STATUS_SUCCESS, this causes the operation request to fail. Repeated failure of certain requests, such as locking requests, can halt system progress. Thus, filter drivers should fail such a request only when absolutely necessary. When failing these requests, the filter driver should return an error status value that describes the error as completely and accurately as possible.

Note??A filter driver's notification callback routine cannot fail a request to release a file system resource. If a filter driver returns a status value other than STATUS_SUCCESS from any of the following notification callback routines, the status value is ignored.

• PreReleaseForSectionSynchronization
• PreReleaseForCcFlush
• PreReleaseForModifiedPageWriter

The filter completion callback routine is invoked after the operation request is passed to lower-level filter drivers and the underlying file system. In the completion callback routine, the filter driver must perform any needed processing and immediately return.

The callback routines defined by FsRtlRegisterFileSystemFilterCallbacks supersede the following fast I/O callback routines, which are obsolete and should not be used by file system filter drivers:

• AcquireForCcFlush
• AcquireFileForNtCreateSection
• AcquireForModWrite
• ReleaseForCcFlush
• ReleaseFileForNtCreateSection
• ReleaseForModWrite

Requirements

Versions: This routine is available on Update Rollup for Windows 2000 Service Pack 4 (SP4) and on Microsoft Windows XP and later.

IRQL:?Any level

Headers: Declared in Ntifs.h. Include Ntifs.h.