IStorage:IUnknown
This interface provides methods for creating and managing the root storage, child storage, and stream objects. These methods can create, open, enumerate, move, copy, rename, or delete the elements in the storage object.
The IStorage interface supports the creation and management of structured storage objects. Structured storage allows hierarchical storage of information within a single file, and is often referred to as a file system within a file. Elements of a structured storage object are storages and streams. Storages are analogous to directories, and streams are analogous to files. Within a structured storage there will be a primary storage object that may contain substorages, possibly nested, and streams. Storages provide the structure of the object, and streams contain the data, which is manipulated through the IStream interface.
The IStorage interface provides methods for creating and managing the root storage object, child storage objects, and stream objects. These methods can create, open, enumerate, move, copy, rename, or delete the elements in the storage object.
An application must release its IStorage pointers when it is done with the storage object to deallocate memory used. There are also methods for changing the date and time of an element.
There are a number of different modes in which a storage object and its elements can be opened, determined by setting values from the STGM enumeration. One aspect of this is how changes are committed. You can set direct mode, in which in which changes to an object are immediately written to it, or transacted mode, in which changes are written to a buffer until explicitly committed. The IStorage interface provides methods for committing changes and reverting to the last-committed version. Other storage modes set, for example, a stream can be opened in read only mode or read/write mode. For more information, refer to the STGM enumeration.
Other methods provide a means to gain access to information about a storage object and its elements through the STATSTG structure.
When to Implement
Generally, you would not implement this interface unless you were defining a new storage scheme for your system. COM provides a compound file implementation of the IStorage interface that supports transacted access. COM provides a set of helper APIs to facilitate using the compound file implementation of storage objects. Refer to IStorage - Compound File Implementation.
When to Use
Call the methods of IStorage to manage substorages or streams within the current storage. This management includes creating, opening, or destroying sub-storages or streams, as well as managing aspects such as time stamps and names. You can also commit changes or revert to previous version for storages opened in transacted mode. The methods of IStorage do not include means to read and write datathis is reserved for IStream, which manages the actual data. While the IStorage and IStream interfaces are used to manipulate the storage object and its elements, the IPersistStorage interface contains methods that are called to serialize the storage object and its elements to a disk file.
| Method | Description |
|---|---|
| IStorage::Commit | Reflects changes for a transacted storage object in the parent level. |
| IStorage::CopyTo | Copies the entire contents of this open storage object into another storage object. |
| IStorage::CreateStorage | Creates and opens a new storage object nested within this storage object. |
| IStorage::CreateStream | Creates and opens a stream object with the specified name contained in this storage object. All elements within a storage object, both streams and other storage objects, are kept in the same name space. |
| IStorage::DestroyElement | Removes the specified storage or stream object from this storage object. |
| IStorage::EnumElements | Retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object. |
| IStorage::MoveElementTo | Copies or moves a substorage or stream object from this storage object to another storage object. |
| IStorage::OpenStorage | Opens an existing storage object with the specified name according to the specified access mode. |
| IStorage::OpenStream | Opens an existing stream object within this storage object according to the specified access mode. |
| IStorage::RenameElement | Renames the specified storage or stream object in this storage object. |
| IStorage::Revert | Discards all changes that have been made to the storage object since the last commit operation. |
| IStorage::SetClass | Assigns the specified class idenitifier (CLSID) to this storage object. |
| IStorage::SetElementTimes | Sets the modification, access, and creation times of the indicated storage element, if supported by the underlying file system. |
| IStorage::SetStateBits | Stores up to 32 bits of state information in this storage object. |
| IStorage::Stat | Returns the STATSTG structure for this open storage object. |
Requirements
| Runs On | Versions | Defined in | Include | Link to |
|---|---|---|---|---|
| Windows CE OS | 2.0 and later | Objidl.h |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
Last updated on Tuesday, July 13, 2004
© 1992-2000 Microsoft Corporation. All rights reserved.