Microsoft KB Archive/319447

= How To Implement Reparsing in a File System Filter Driver =

Article ID: 319447

Article Last Modified on 2/12/2007

-

APPLIES TO


 * Microsoft Win32 Device Driver Kit for Windows 2000
 * Microsoft Windows XP Driver Development Kit

-



This article was previously published under Q319447



SUMMARY
The IO manager offers a convenient way to reparse a file object. Typically, this method is used in file system filter drivers to redirect a file-open or file-creation operation to another file.



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.
 * 1) Sets the status field of the IoStatus block to STATUS_REPARSE, and then sets the Information field to IO_REPARSE.
 * 2) Completes the request.
 * 3) 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:
 * &quot;\??\UNC\HostName\Share\File&quot;

-or-
 * &quot;\Device\Mup\HostName\Share\File&quot;

-or-
 * &quot;\Device\LanmanagerRedirector\HostName\Share\File&quot; (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 &quot;as is&quot; 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 ); } }

Additional query words: STATUS_REPARSE IO_REPARSE reparsing

Keywords: kbhowto kbifs kbkmode KB319447

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.