PIO_STACK_LOCATION irpSp = IoGetCurrentIrpStackLocation(Irp);

BOOLEAN IsRename = (irpSp->Parameters.SetFile.FileInformationClass ==                      FileRenameInformation);

if (IsRename) {
                ntStatus = FilterProcessRenameOperation(Irp, irpSp);
}

But Wait, What Exactly Is A File System Rename Operation?

It may seem obvious that a rename operation changes the name of a file. For example you could change the file C:\frob\nicate.txt to C:\frob\etacin.txt. It is less obvious that you could also change the name of C:\frob\nicate.txt to C:\frobnicate.txt. Which is to say you can move a file from one location to another by renaming it.

A rename operation has four pieces of pathname data to deal with:

·         The source directory or pathname

·         The source filename

·         The target directory or pathname

·         The target filename

In addition, there are three different types of renaming that can occur:

·         Rename, change the name of the source file, not its location

·         Move - change a file?s location, not its name

·         Move and rename ? change the name of a file and its location

In addition, there may or may not be a conflict with an existing file that currently uses the rename target filename. A filter driver or a file system driver might have to understand what is the correct thing to do if a conflict occurs.

Windows NT file system documentation refers to three types of rename operations called Simple Rename, Fully Qualified Rename, and Relative Rename. These only roughly correspond to the 3 cases above. What these three NT types of rename really describe is how the target of the rename operation is described by the SetInformation operation, and therefore how the file system driver, and by extension our file system filter driver, can understand it.

In the case of a Simple Rename, the source file object and the target file object are in fact the same objects. Only the name (not directory) of the file is being changed.

In the Fully Qualified Rename case, an absolute (fully qualified) pathname identifies the target of the rename operation. In this case the target filename may or may not be the same as the source filename, but we can be sure that the fully qualified source pathname is not the same as the fully qualified target pathname.

In the case of a Relative Rename, the target file name is specified as a filename relative to a directory. Once again we can be sure that the two fully qualified pathnames are not the same.

Yes But Why Do I Care?

File System Filter Driver that is performing replication services might wish to track all rename operations so that these operations can be replayed on another file system, perhaps even on another system. To do so the filter driver would have to record the name of the file being renamed (the source file) and the new name of the file (the target file.)

For example, if I were to rename C:\frob\nicate.txt to C:\frobnicate.txt, my replication filter driver would create the log record:

And my replication agent, in communication with my filter driver, would read this log record and then perform whatever miracle is required to replicate the rename elsewhere.

All the filter driver has to do is produce a simple record containing three values:

·         The operation (RENAME)

·         The fully qualified pathname of the source file

·         The fully qualified pathname of the target file

Should be simple eh? Well, nothing is ever as simple as it should be.

Step 2. Getting at the Parameters

The NT DDK defines the parameters relevant to an IRP_MJ_SET_INFORMATION in one of the fields in the union IO_STACK.Parameters (shown below).

//
// System service parameters for: NtSetInformationFile
//

struct {

        ULONG Length;
        FILE_INFORMATION_CLASS FileInformationClass;
        PFILE_OBJECT FileObject;

        union {

        struct {

        BOOLEAN ReplaceIfExists;
        BOOLEAN AdvanceOnly;

        };

        ULONG ClusterCount;
        HANDLE DeleteHandle;

        };

} SetFile; 

//
// assume that Irp is a pointer to an IRP and that
// irpSp is a pointer to our IO_STACK location in that IRP.
//

PFILE_RENAME_INFORMATION renameInfo;

renameInfo = (PFILE_RENAME_INFORMATION) Irp->AssociatedIrp.SystemBuffer;

if (!irpSp->Parameters.SetFile.FileObject) {

        //
        // simple rename case ? call function that handles this case
        //

        status = processSimpleRename(Irp, irpSp, renameInfo);

} else {

        //
        //

        if (renameInfo->RootDirectory == NULL) {

                //
                //fully qualified rename case ? call function for this
                //

                status = processFQRename(Irp, irpSp, renameInfo);

        } else {

                //
                // relative rename case ? call a function for this case.
                //

                status = processRelativeRename(Irp, irpSp, renameInfo);

        }

}

I mentioned earlier that you might need to know what to do if a rename target already exists. The SetFile.ReplaceIfExists field informs the driver about the correct action. This is a BOOLEAN, and if it has the value TRUE, a rename target can be deleted if it exists, otherwise, if it is FALSE, an existing rename target causes the rename operation to fail.

Starters

Build a fully qualified filename for the source file object. How you do that is not the subject of this article. Suffice it to say that one can always construct a fully qualified pathname for a file object by walking back through the file objects linked to the original file object and collecting each file object?s UNICODE_STRING name (i.e. FILE_OBJECT. FileName,) thus building the fully qualified pathname of the original file object.

Having done that, we still need the fully qualified target pathname in order to record the file operation. How we get the target fully qualified pathname depends on which type of rename operation we have: simple, fully qualified or relative. The remainder of this article demonstrates how for each rename type the target pathname can be constructed.

Simple Rename

Easy ? just copy the pathname component of the fully qualified source filename and append the target filename. The target filename is the WCHAR string at FILE_RENAME_INFORMATION.FileName.

The code for a simple rename might look like that below (note that the following code segments, while based on a functional filter driver are pseudo code only and will not compile without errors).

Fully Qualified Rename

In the Fully Qualified Rename case, RenameInfo.FileName is the fully qualified pathname of the rename target. This makes our task relatively simple.

I?ve introduced one other complexity here, the drive specification of the fully qualified pathname. In the simple rename case I ignored the drive specification portion of the fully qualified pathname. In other words I just left out the fact that to fully log a file system operation we need the fully qualified pathname to include the drive (e.g. "C:"). I left it out for the same reason I am omitting a discussion of exactly how one constructs a fully qualified pathname from a File Object: it is in and of itself a complicated enough subject to warrant its own article. In the simple rename case, just assume that the source file name included the drive letter and that the target file name will as well.

Since we are not just copying the source file name, this drive letter has to come from somewhere. In the following example, how we obtain the drive specification is undefined, and a global variable DriveLetter just magically has the correct value.