IStream
The
IStream interface supports reading and writing data to stream objects. Stream objects
are elements nested within a storage object. They are similar to standard
files. You use stream objects to store the data for your application.
The
IStream interface provides 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 open
using a file handle. Instead, you use the
IStream interface pointer.
The methods in this interface present your object data as a contiguous
sequence of bytes which 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.
When to Implement
OLE provides an implementation of the
IStream interface that you can use for saving object data. The specification of
IStream defines more functionality that the OLE implementation supports. For example,
the
IStream interface defines streams up to 2 (64) bytes in length requiring a 64-bit seek pointer. However, the OLE
implementation only supports streams up to 2 (32) bytes in length and read and write operations are always limited to 2 (32) bytes at a time. The OLE implementation also does not support stream
transactioning or region locking.
Container or object applications can implement their own stream objects
instead of using the OLE-provided implementation.
When to Use
If you are writing an object application, you can use the
IStream interface to store the data for your object.
Since stream objects can be marshaled to other processes, applications can
share the data in storage objects without having to use global memory. For the
OLE-provided implementation of stream objects, the custom marshaling facilities in
OLE create a remote version of the original object in the new process when the
two processes have shared memory access. Thus, the remote version does not
need to communicate with the original process to carry out its functions.
The remote version of the stream object shares the same seek pointer as the
original stream. If you do not want to share the seek pointer, you should use the
IStream::Clone method to provide a copy of the stream object for the remote process.
Note If you are creating a stream object that is larger than the heap in your
machine's memory and you are using an HGLOBAL, the stream object calls
GlobalRealloc internally whenever it needs more memory. Because
GlobalRealloc always copies data from the source to the destination, increasing a stream
object from 20M to 25M, for example, consumes immense amounts of time. This is
due to the size of the increments copied and is worsened if there is less than
45M of memory on the machine because of disk swapping.
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.
Another alternative is to call the
IStream::SetSize method on the stream object to increase the memory allocation in advance.
This is not, however, as efficient as using
VirtualAlloc as described above.
Methods in Vtable Order
IStream 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 from bytes into the stream object starting at the
current seek pointer.
|
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.
|
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database
