Expand Minimize

FsRtlChangeBackingFileObject routine

The FsRtlChangeBackingFileObject routine replaces the current file object with a new file object.

Syntax


NTSTATUS FsRtlChangeBackingFileObject(
  _In_opt_  PFILE_OBJECT CurrentFileObject,
  _In_      PFILE_OBJECT NewFileObject,
  _In_      FSRTL_CHANGE_BACKING_TYPE ChangeBackingType,
  _In_      ULONG Flags
);

Parameters

CurrentFileObject [in, optional]

The current file object. If this object does not belong to the stream, the operation fails.

NewFileObject [in]

The new file object.

ChangeBackingType [in]

An FSRTL_CHANGE_BACKING_TYPE enumeration value that indicates which internal memory area the new file object will designate.

Flags [in]

Reserved for future use.

Return value

The FsRtlChangeBackingFileObject routine returns STATUS_SUCCESS if the operation succeeds. Otherwise, FsRtlChangeBackingFileObject returns the appropriate error code.The following table contains error codes that FsRtlChangeBackingFileObject might return.

Return codeDescription
STATUS_INVALID_PARAMETER_2

The change operation failed because the file object that NewFileObject specifies does not represent the same stream as CurrentFileObject.

STATUS_INVALID_PARAMETER_3

The change operation failed because the caller specified an invalid backing type in ChangeBackingType.

STATUS_INVALID_PARAMETER_4

The change operation failed because the caller specified an invalid value in Flags.

STATUS_NOT_SUPPORT

The change operation failed because the caller obtained the file object in a way that does not allow subsequent swapping of the file object. For example, if the caller obtained the file object with a call to CcGetFileObjectFromSectionPtrs, it is not safe to swap the file object.

 

Remarks

The FsRtlChangeBackingFileObject routine changes the file object for one of the following:

  • One of the memory manager's image control areas for the stream

  • The memory manager's data control area for the stream

  • The cache manager's shared cache map for the stream

The FsRtlChangeBackingFileObject routine is not synchronous. It processes the request for a change of file object and returns immediately. The cache manager and the memory manager synchronize the change of the file object and will not free the old file object until all incomplete operations that are associated with the old file object have finished. A return status of STATUS_SUCCESS from FsRtlChangeBackingFileObject does not mean that the operating system has already changed the file object.

However, after FsRtlChangeBackingFileObject runs successfully, the operating system associates all future operations with the new file object.

To change the file object for more than one backing type, the caller must call FsRtlChangeBackingFileObject multiple times, one time for each backing type to change.

Requirements

Version

The FsRtlChangeBackingFileObject routine is available starting with Windows Vista.

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

See also

FSRTL_CHANGE_BACKING_TYPE

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft