How To Implement Reparsing in a File System Filter Driver (319447)

MORE INFORMATION

To redirect a file-open or file-creation operation to another file, a file system filter driver does the following:

1. In the handler of IRP_MJ_CREATE, obtains the file name (FileName field) from the FILE_OBJECT.
2. Replaces this name with the full name of the destination file.
   
   This full name includes the name of the volume device object (for example, Device\HardDiskVolume0\Directory\MyFile.txt). You can substitute your own buffer to the existing FileName.Buffer present in the FILE_OBJECT. In this case, allocate your buffer from NonPaged pool memory, free the original FileName.Buffer by using ExFreePool, and then replace FileName.Buffer with your buffer.
3. Sets the status field of the IoStatus block to STATUS_REPARSE, and then sets the Information field to IO_REPARSE.
4. Completes the request.
5. Returns STATUS_REPARSE.

The IO Manager then triggers another file-open operation and sends an IRP_MJ_CREATE, taking into account the particular file name.

The destination file can be local or on a remote computer. To redirect the file-open operation to a remote file, use the following syntax for the file name:

• "\??\UNC\HostName\Share\File"
  
  -or-
• "\Device\Mup\HostName\Share\File"
  
  -or-
• "\Device\LanmanagerRedirector\HostName\Share\File" (assuming you are targeting a file on CIFS/SMB/LanManager)

The fact that the first create-file operation is performed relative to another file object does not matter. Do not modify the RelatedFileObject field of the FILE_OBJECT. To perform the reparse operation, the IO Manager considers only the FileName field and not the RelatedFileObject. Additionally, the IO Manager frees the RelatedFileObject, as appropriate, when it handles the STATUS_REPARSE status returned by the filter. Therefore, it is not the responsibility of the filter to free that file object.

There is a fixed limit concerning the number of nested reparse operations that the IO Manager can perform. This limit has been introduced to avoid infinite loops. The maximum number of nested reparse operations the system can perform is 32.

This reparsing method performed by the IO Manager has to be disassociated from reparse points. Reparse points have been introduced in NTFS, starting with Microsoft Windows 2000. Reparse points permit you to store information together with a file.

Sample Code

NTSTATUS
SfCreate (
    IN PDEVICE_OBJECT DeviceObject,
    IN PIRP Irp
    )
{
	PIO_STACK_LOCATION		IrpSp;
	PUNICODE_STRING		FileName;
	PVOID			FileNameBuffer;
	UNICODE_STRING		NewFileName;
	BOOLEAN			bRedirectFileOpen = FALSE;

	// 
	//  If the device being opened is the primary device object instead of a
	//  filter device object, just indicate that the operation worked.
	// 

	if (DeviceObject == FsDeviceObject)
	{
		// 
		//  Allow users to open the device that represents our driver.
		// 

		Irp->IoStatus.Status = STATUS_SUCCESS;
		Irp->IoStatus.Information = FILE_OPENED;

		IoCompleteRequest( Irp, IO_NO_INCREMENT );
		return STATUS_SUCCESS;
	}
	
	IrpSp = IoGetCurrentIrpStackLocation(Irp);

	// 
	// At this point, you must determine whether you want to redirect
	// the file open/create for this particular file.
	// Beware that the file name from the FILE_OBJECT in the current
	// IRP stack location is not always the file name with the full
	// path, nor the long file name or even a name. The way the file is
 	// opened (with full path, relatively to another file, with short 
	// or long file name, by ID, ...) affects this name.
	// 
	// TODO: Put your code here to check whether you have to redirect the operation.
	// If so, set bRedirectFileOpen to TRUE and initialize the NewFileName
	// UNICODE_STRING to the full file name of the destination file.
	// 

	if ( bRedirectFileOpen )
	{
		FileName = &(IrpSp->FileObject->FileName);

		FileNameBuffer = ExAllocatePool( NonPagedPool, NewFileName.MaximumLength );
		if (!FileNameBuffer)
		{
			// 
			// Not enough resources. Complete the IRP with the appropriate status.
			// 

			Irp->IoStatus.Status = STATUS_INSUFFICIENT_RESOURCES;
			Irp->IoStatus.Information = 0;

			IoCompleteRequest( Irp, IO_NO_INCREMENT );
			return STATUS_INSUFFICIENT_RESOURCES;
		}

		ExFreePool( FileName->Buffer );
		FileName->Buffer = FileNameBuffer;
		FileName->MaximumLength = NewFileName.MaximumLength;

		RtlCopyUnicodeString( FileName, &NewFileName );

		// 
		// Instruct the IO Manager to reparse this file.
		// 

		Irp->IoStatus.Status = STATUS_REPARSE;
		Irp->IoStatus.Information = IO_REPARSE;

		IoCompleteRequest( Irp, IO_NO_INCREMENT );
		return STATUS_REPARSE;
	}
	else
	{
		// 
		// Pass the request "as is" down the device stack.
		// 

		// 
		// The next driver will get the IO_STACK_LOCATION
		// that you received.
		// 

		IoSkipCurrentIrpStackLocation( Irp );
    
    		// 
		// Call the appropriate file system driver with the request.
		// 
		// TODO: Replace AttachedToDeviceObject by the device
		// object pointer your device object is attached to (the
		// lower device object in the stack).
		// Typically, this device object pointer is saved by your
		// filter in your device extension.
		// 

		return IoCallDriver( AttachedToDeviceObject, Irp );
	}
}