The IStream interface supports reading and writing data to stream objects. Stream objects contain the data in a structured storage object, where storages provide the structure. Simple data can be written directly to a stream, but most frequently, streams are elements nested within a storage object. They are similar to standard files.
The IStream interface defines methods similar to the MS-DOS FAT file functions. For example, each stream object has its own access rights and a seek pointer. The main difference between a stream object and a DOS file is that streams are not opened using a file handle, but through an IStream interface pointer.
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file system resources. The IStream::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous IMoniker::BindToStorage operation and for receiving asynchronous notifications.The table below compares the behavior of asynchronous ISequentialStream::Read and IStream::Seek calls returned in IBindStatusCallback::OnDataAvailable in these two download models:
| IStream method call | Behavior in data-pull model | Behavior in data-push model |
|---|---|---|
| Read is called to read partial data, (i.e. not all the available data) | Returns S_OK. The client must continue to read all available data before returning from IBindStatusCallback::OnDataAvailable or else the bind operation is blocked. (i.e. read until S_FALSE or E_PENDING is returned) | Returns S_OK. Even if the client returns from IBindStatusCallback::OnDataAvailable at this point the bind operation continues and IBindStatusCallback::OnDataAvailable will be called again repeatedly until the binding finishes. |
| Read is called to read all the available data | Returns E_PENDING if the bind operation has not completed, and IBindStatusCallback::OnDataAvailable will be called again when more data is available. | Same as data-pull model. |
| Read is called to read all the available data and the bind operation is over (end-of-file) | Returns S_FALSE. There will be a subsequent call to IBindStatusCallback::OnDataAvailable with the grfBSC flag set to BSCF_LASTDATANOTIFICATION. | Same as data-pull model. |
| Seek is called | Seek doesn't work in data-pull model | Seek doesn't work in data-push model. |
For general information on this topic, see Asynchronous Monikers and Data-Pull-Model versus Data Push-Model for more specific information. Also, see Managing Memory Allocation for details on COM's rules for managing memory.
Implement IStream on a container or object application when you require functionality not provided by the COM compound file implementation. The specification of IStream defines more functionality that the COM implementation supports. In addition, if you are creating a stream object that is larger than the heap in your machine's memory and you are using a global memory handle, the compound file implementation calls GlobalRealloc internally whenever it needs more memory, which can be extremely inefficient. In this case, the preferred solution is to implement an IStream that uses memory allocated by VirtualAlloc instead of GlobalAlloc. This can reserve a large chunk of virtual address space and then commit memory within that address space as required. No data copying occurs and memory is committed only as it is needed. For more information, refer to IStream - Compound File Implementation.
The IStream interface inherits Read and Write methods from ISequentialStream.
Note Most containers do not implement ISequentialStream as a separate interface, and you are not required to provide it separately even if you provide an IStream implementation. For example, the compound file implementation of structured storage does not succeed on a QueryInterface for ISequentialStream but it includes the Read and Write methods through the IStream interface pointer. The same is true for the NTFS Native Structured Storage implementation.
Call the methods of the IStream interface from a container or application to read and write the data for an object. Since stream objects can be marshaled to other processes, applications can share the data in storage objects without having to use global memory.
| IUnknown Methods | Description |
|---|---|
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| ISequentialStream Methods | Description |
|---|---|
| Read | Reads a specified number of bytes from the stream object into memory starting at the current seek pointer. |
| Write | Writes a specified number of bytes into the stream object starting at the current seek pointer. |
| IStream Methods | Description |
|---|---|
| Seek | Changes the seek pointer to a new location relative to the beginning of the stream, the end of the stream, or the current seek pointer. |
| SetSize | Changes the size of the stream object. |
| CopyTo | Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream. |
| Commit | Ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage object. |
| Revert | Discards all changes that have been made to a transacted stream since the last IStream::Commit call. |
| LockRegion | Restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it. |
| UnlockRegion | Removes the access restriction on a range of bytes previously restricted with IStream::LockRegion. |
| Stat | Retrieves the STATSTG structure for this stream. |
| Clone | Creates a new stream object that references the same bytes as the original stream but provides a separate seek pointer to those bytes. |
Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in objidl.h.
IStream - Compound File Implementation, ISequentialStream