IStream interface (objidl.h)
The IStream interface lets you read and write 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 DOS file and a stream object is that in the latter case, streams are opened using an IStream interface pointer rather than a file handle.
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 that are 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 IUnknown::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. See URL Monikers for more information. The following table 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 (that is, 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. (that is, 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 does not work in data-pull model | Seek does not 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.
Inheritance
The IStream interface inherits from the ISequentialStream interface. IStream also has these types of members:
Methods
The IStream interface has these methods.
| IStream::Clone The Clone method creates a new stream object with its own seek pointer that references the same bytes as the original stream. |
| IStream::Commit The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. |
| IStream::CopyTo Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream. |
| IStream::LockRegion The LockRegion method restricts access to a specified range of bytes in the stream. |
| IStream::Revert The Revert method discards all changes that have been made to a transacted stream since the last IStream::Commit call. On streams open in direct mode and streams using the COM compound file implementation of IStream::Revert, this method has no effect. |
| IStream::Seek Changes the seek pointer to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek pointer. |
| IStream::SetSize Changes the size of the stream object. |
| IStream::Stat The Stat method retrieves the STATSTG structure for this stream. |
| IStream::UnlockRegion The UnlockRegion method removes the access restriction on a range of bytes previously restricted with IStream::LockRegion. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps | UWP apps] |
| Minimum supported server | Windows 2000 Server [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | objidl.h |