Copies the current file associated with the storage object to a new file. The new file is then used for the storage object and any uncommitted changes.
HRESULT SwitchToFile(
LPOLESTR pszFile //Filename for the new file
);
The IRootStorage::SwitchToFile method copies the file associated with the storage object. A COM container calls SwitchToFile to perform a full save on a file in a low-memory situation. Typically, this is done only after a normal full save operation (i.e., save to temporary file, delete original file, rename temporary file) has failed with an E_OUTOFMEMORY error.
It is illegal to call SwitchToFile if the storage object or anything contained within it has been marshalled to another process. As a consequence, before calling SwitchToFile, the container must call the IPersistStorage::HandsOffStorage method for any element within the storage object that is loaded or running. The HandsOffStorage method forces the element to release its storage pointers and enter the hands-off storage mode. The container must also release all pointers to streams or storages that are contained in this root storage. After the full save operation is completed, the container returns the contained elements to normal storage mode.
When storing storage objects on NTFS systems in native structured storage format, the files are automatically converted for all non-NTFS partitions, for example FAT partitions. The IRootStorage::SwitchToFile method is not supported for NTFS native structured storage files.
If you are implementing your own storage objects, the IRootStorage methods (including QueryInterface, AddRef, and Release) must not consume additional memory or file handles.
Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in objidl.h.
IPersistStorage::HandsOffStorage, IPersistStorage::SaveCompleted, IStorage::Commit, IStorage::Stat