 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This method copies the current file associated with the storage object to a new file, which is then used for the storage object and any uncommitted changes.
Syntax
HRESULT SwitchTofFile( LPOLESTR pszFile ); |
Parameters
- pszFile
-
Pointer to the null-terminated string that contains the name for the new file. It cannot be the name of an existing file.
If NULL, this method creates a temporary file with a unique name, and you can call the IStorage::Statmethod to retrieve the name of the temporary file.
Return Value
The following table shows the return values for this method.
| Value | Description |
|---|---|
|
S_OK |
The file was successfully copied. |
|
STG_E_MEDIUMFULL |
The file was not copied because of insufficient space on the storage device. |
|
STG_E_ACCESSDENIED |
The file was not copied because the caller does not have permission to access storage device. |
|
STG_E_INVALIDPOINTER |
The file was not copied because the pszFilepointer is invalid. |
|
STG_E_FILEALREADYEXISTS |
The file was not copied because the new file name ( pszFile) points to an existing file. |
Remarks
The IRootStorage::SwitchToFilemethod copies the file associated with the storage object.
A COM container calls SwitchToFileto perform a full save on a file in a low-memory situation. Typically, this is done only after a normal full save operation — save to temporary file, delete original file, and rename temporary file — has failed with an E_OUTOFMEMORY error.
It is illegal to call SwitchToFileif the storage object or anything contained within it has been marshaled to another process. As a consequence, before calling SwitchToFile, the container must call the IPersistStorage::HandsOffStoragemethod for any element within the storage object that is loaded or running.
The HandsOffStoragemethod 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 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::SwitchToFilemethod is not supported for NTFS native structured storage files.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Notes to Implementers
If you are implementing your own storage objects, the IRootStoragemethods (including QueryInterface, AddRef, and Release) must not consume additional memory or file handles.
Requirements
| Header | objidl.h, objidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 2.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |