 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. |
The IStreaminterface 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 IStreaminterface 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 IStreaminterface 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::Releasemethod 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-pullor data-pushmodel for driving an asynchronous IMoniker::BindToStorageoperation and for receiving asynchronous notifications.
The following table shows a comparison between the behavior of the asynchronous ISequentialStream::Readmethod and IStream::Seekcalls returned in IBindStatusCallback::OnDataAvailablein these two download models.
| IStream method call | Behavior in data-pullmodel | Behavior in data-pushmodel |
|---|---|---|
|
Readis 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 the IBindStatusCallback::OnDataAvailablemethod 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::OnDataAvailableat this point the bind operation continues and IBindStatusCallback::OnDataAvailablewill be called again repeatedly until the binding finishes. |
|
Readis called to read all the available data. |
Returns E_PENDING if the bind operation has not completed, and IBindStatusCallback::OnDataAvailablewill be called again when more data is available. |
Same as data-pull model. |
|
Readis 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::OnDataAvailablewith the grfBSCflag set to BSCF_LASTDATANOTIFICATION. |
Same as data-pull model. |
|
Seekis called. |
Seekdoes not work in data-pull model. |
Seekdoes not work in data-push model. |
When to Implement
Implement IStreamon a container or object application when you require functionality not provided by the COM compound file implementation.
The specification of IStreamdefines more functionality that the COM implementation supports.
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 the GlobalReallocfunction internally whenever it needs more memory, which can be extremely inefficient.
In this case, the preferred solution is to implement an IStreamthat uses memory allocated by the VirtualAllocfunction 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, see IStream - Compound File Implementation.
 Note: |
|---|
| Most containers do not implement the ISequentialStreaminterface as a separate interface, and you are not required to provide it separately even if you provide an IStreamimplementation. |
|
Note: |
|---|
| For example, the compound file implementation of structured storage does not succeed on a QueryInterfacefor ISequentialStreambut it includes the Readand Writemethods through the IStreaminterface pointer. |
|
Note: |
|---|
| The same is true for the NTFS Native Structured Storage implementation. |
When to Use
Call the methods of the IStreaminterface from a container or application to read and write the data for an object. Because stream objects can be marshaled to other processes, applications can share the data in storage objects without having to use global memory.
Methods
The following table shows the methods for this interface in alphabetical order.
| Method | Description |
|---|---|
|
Creates a new stream object with its own seek pointer that references the same bytes as the original stream. |
|
|
Ensures that any changes made to a stream object opened in transacted mode are reflected in the parent storage object. If the stream object is opened in direct mode, this method has no effect other than flushing all memory buffers to the next level storage object. The OLE compound file implementation of streams does not support opening streams in transacted mode. |
|
|
Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream. |
|
|
Restricts access to a specified range of bytes in the stream. Supporting this functionality is optional because some file systems do not provide it. |
|
|
Reads a specified number of bytes from the stream object into memory, starting at the current seek pointer. |
|
|
Discards all changes that have been made to a transacted stream since the last IStream::Commitcall. This method has no effect on streams open in direct mode and streams using the OLE compound file implementation of IStream::Revert. |
|
|
Changes the seek pointer to a new location relative to the current seek pointer or the beginning or end of the stream. |
|
|
Resizes of the stream object. |
|
|
Retrieves the STATSTGstructure for this stream object. |
|
|
Removes the access restriction on a range of bytes previously restricted with IStream::LockRegion. |
|
|
Writes a specified number of bytes into the stream object starting at the current seek pointer. |
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 2.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |