IPersistFile
A version of this page is also available for
4/8/2010
This interface provides methods that permit an object to be loaded from or saved to a disk file, rather than a storage object or stream.
Because the information needed to open a file varies greatly from one application to another, the implementation of IPersistFile::Load on the object must also open its disk file.
The IPersistFile interface inherits its definition from IPersist, so all implementations must also include the GetClassID method of IPersist.
When to Implement
Implement IPersistFile when you want to read or write information from a separate file, which could be of any file format.
This interface should be implemented on any objects that support linking through a file moniker, including the following:
- Any object that supports links to its files or to pseudo-objects within its files
- A container application that supports links to objects within its compound file
Typically, you implement the IPersistFile interface as part of an aggregate object that includes other interfaces that are appropriate for the type of moniker binding that is supported.
For example, in either of the cases mentioned above, the moniker for the linked object can be a composite moniker. In the first case, a composite moniker identifies the pseudo-object contained within the file. In the second case, a composite moniker identifies the embedded object contained within the compound file.
In either case of composite monikers, you must implement the IPersistFile interface as part of the same object on which the IOleItemContainer interface is implemented. Then, when the application for the linked object is run, OLE queries for the IOleItemContainer interface to locate the embedded object or the pseudo-object contained in the file.
As another example, if the moniker is a simple file moniker (for example, the link is to the entire file), OLE queries for the interface that the initiator of the bind operation requested. Typically, this is one of the compound document interfaces, such as IOleObject or IPersistStorage.
When to Use
Call methods in the IPersistFile interface to load or save a linked object in a specified file.
When IPersistFile is implemented on an object that supports linking through a file moniker and the application for the linked object is run, OLE calls IPersistFile::Load. Once the file is loaded, OLE calls IPersistFile::QueryInterface to get another interface pointer to the loaded object. The IPersistFile interface is typically part of an aggregate object that offers other interfaces.
In this case, the only IPersistFile method that OLE calls is the Load method to load a file linked to a container, running the application associated with the file. It would also be unusual for applications to call other methods in this case, which support saving an object to a file.
Generally, it is left to the user and the application for the linked object to decide when to save the object. This differs from the situation for an embedded object, in which the container application uses the IPersistStorage interface to provide the storage and to tell the object when to save itself.
Methods in Vtable Order
| IUnknown method | Description |
|---|---|
Returns pointers to supported interfaces. |
|
Increments the reference count. |
|
Decrements the reference count. |
| IPersist method | Description |
|---|---|
Returns the class identifier (CLSID) for the component object. |
| IPersistFile method | Description |
|---|---|
Checks an object for changes since it was last saved to its current file. |
|
Opens the specified file and initializes an object from the file contents. |
|
Saves the object into the specified file. |
|
Notifies the object that it can revert from NoScribble mode to Normal mode. |
|
Gets the current name of the file associated with the object. |
Remarks
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Requirements
| Header | objidl.h, objidl.idl |
| Library | ole32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 3.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |