Interface IStream

In this topic

Package com.ms.com Previous This
Package Next

Interface IStream

public interface IStream extends IUnknown
{
  // Fields
  public static final _Guid iid;
  public static final int LOCK_EXCLUSIVE;
  public static final int LOCK_ONLYONCE;
  public static final int LOCK_WRITE;
  public static final int STATFLAG_DEFAULT;
  public static final int STATFLAG_NONAME;
  public static final int STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE;
  public static final int STGC_DEFAULT;
  public static final int STGC_ONLYIFCURRENT;
  public static final int STGC_OVERWRITE;
  public static final int STREAM_SEEK_CUR;
  public static final int STREAM_SEEK_END;
  public static final int STREAM_SEEK_SET;

  // Methods
  public IStream Clone();
  public void Commit(int grfCommitFlags);
  public void CopyTo(IStream pstm, long cb, long[] pcbRead,
        long[] pcbWritten);
  public void LockRegion(long libOffset, long cb, int dwLockType);
  public int Read(byte buf[], int off, int len);
  public void Revert();
  public long Seek(long dlibMove, int dwOrigin);
  public void SetSize(long libNewSize);
  public void Stat(STATSTG pstatstg, int grfStatFlag);
  public void UnlockRegion(long libOffset, long cb, int dwLockType);
  public int Write(byte buf[], int off, int len);
}

This interface provides methods for reading and writing data to stream objects. Each stream has its own access rights and seek pointer. The main difference between a stream object and an MS-DOS file is that streams are opened through an IStream interface pointer instead of using a file handle. Simple data can be written directly to a stream. Usually, however, streams are elements nested within a storage object.

This interface wraps the Component Object Model (COM) IStream interface.

IUnknown
  |
  +--IStream

Methods

Clone

public IStream Clone();
Creates a new stream object with its own seek pointer that references the same bytes as the original stream.
Return Value:
Returns the new stream object.
Remarks:
Because both the original object and its clone access the same data, changes written to one object are immediately visible in the other.

Commit

public void Commit(int grfCommitFlags);
Ensures that any changes made to a stream object opened in transacted mode are reflected in the parent storage object.
Return Value:
No return value.

Parameter Description

grfCommitFlags Flags that indicate conditions for the commit operation; the value must be STGC_DEFAULT or some combination of the following: STGC_OVERWRITE, STGC_ONLYIFCURRENT, and STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE.

CopyTo

public void CopyTo(IStream pstm, long cb, long[] pcbRead,
        long[] pcbWritten);
Copies a specific number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.
Return Value:
No return value.

Parameter Description

pstm The stream that is copied to.
cb The number of bytes to copy.
pcbRead A pointer to the number of bytes actually read.
pcbWritten A pointer to the number of bytes actually written.

LockRegion

public void LockRegion(long libOffset, long cb, int dwLockType);
Restricts access to a range of bytes in the stream.
Return Value:
No return value.

Parameter Description

libOffset The offset of the current seek pointer (measured in bytes) that indicates where to start the restriction.
cb The number of bytes to restrict.
dwLocktype A flag that indicates the type of restriction that is placed; the value must be LOCK_WRITE, LOCK_EXCLUSIVE, or LOCK_ONLYONCE.

Read

public int Read(byte buf[], int off, int len);
Reads bytes from the stream object into a byte array, starting at a specified offset from the current seek pointer.
Return Value:
Returns the number of bytes actually read.

Parameter Description

buf The buffer that the bytes are read into.
off The offset in the stream to begin reading from.
len The number of bytes to read.

Revert

public void Revert();
Discards all changes made to a transacted stream since the last Commit call.
Return Value:
No return value.
Remarks:
This method has no effect on streams open in direct mode or streams using the OLE compound file Revert implementation.

Seek

public long Seek(long dlibMove, int dwOrigin);
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.
Return Value:
Returns the new seek pointer of the stream.

Parameter Description

dlibMove The offset relative to dwOrigin.
dwOrigin The origin of the offset; must be STREAM_SEEK_CUR, STREAM_SEEK_END, or STREAM_SEEK_SET.

SetSize

public void SetSize(long libNewSize);
Changes the size of the stream object.
Return Value:
No return value.

Parameter Description

libNewSize The new size of the stream, measured in bytes.

Stat

public void Stat(STATSTG pstatstg, int grfStatFlag);
Retrieves the STATSTG structure for the current stream. (This structure contains statistical information about the current stream.)
Return Value:
No return value.

Parameter Description

pstatstg A STATSTG structure that contains the returned statistical information.
grfStatFlag A flag that indicates whether to return a name in the STATSTG structure; the value must be STATFLAG_DEFAULT or STATFLAG_NONAME.

UnlockRegion

public void UnlockRegion(long libOffset, long cb, int dwLockType);
Removes the access restriction on a range of bytes that was previously restricted with the LockRegion method.
Return Value:
No return value.

Parameter Description

libOffset The offset of the current seek pointer (measured in bytes) that indicates where to start removing the restriction.
cb The number of bytes removed from the restriction.
dwlockType A flag that indicates the type of restriction removed; the value must be LOCK_WRITE, LOCK_EXCLUSIVE, or LOCK_ONLYONCE.

Write

public int Write(byte buf[], int off, int len);
Writes bytes from a byte array into the stream object, starting at a specified offset from the current seek pointer.
Return Value:
Returns The number of bytes actually written.

Parameter Description

buf The buffer to write from.
off The offset in the array to begin writing from.
len The number of bytes to write.

Fields

iid: The interface identifier.
LOCK_EXCLUSIVE: Indicates a type of locking for the LockRegion and UnlockRegion methods. If this type of lock is granted, writing to the specified range of bytes is prohibited to everyone except for the owner, who was granted the lock.
LOCK_ONLYONCE: Indicates a type of locking for the LockRegion and UnlockRegion methods. If this type of lock is granted, other LOCK_ONLYONCE locks cannot be obtained on the range.
LOCK_WRITE: Indicates a type of locking for the LockRegion and UnlockRegion methods. If this type of lock is granted, the specified range of bytes can be opened and read any number of times. Writing to the locked range, however, is prohibited to everyone except the owner, who was granted the lock.
STATFLAG_DEFAULT: Indicates that the name field should be included in the STATSTG structure returned by the Stat method.
STATFLAG_NONAME: Indicates that the name field should not be included in the STATSTG structure returned by the Stat method.
STGC_DANGEROUSLYCOMMITMERELYTODISKCACHE: Specifies that changes are committed to a write-behind disk cache, but that the cache is not saved to the disk.
Caution The cache is eventually written to disk, but usually not until after the write operation has already returned. You risk losing data if a problem occurs before the cache is saved and the data in the cache is lost.
STGC_DEFAULT: Specifies the default condition for the Commit method. This value indicates that none of the other values apply.
STGC_ONLYIFCURRENT: Specifies that the commit operation occurs only if there have been no changes to the saved storage object since the user most recently opened the storage object. Prevents multiple users of a storage object from overwriting one another's changes.
STGC_OVERWRITE: Specifies that the Commit method can overwrite existing data to reduce overall space requirements.
Caution This value is not recommended for typical use because it is not as robust as the default case. Data loss can occur when the STGC_OVERWRITE value is specified and the commit operation fails due to some reason other than lack of space.
STREAM_SEEK_CUR: Specifies that the origin of the offset in the Seek method is the location of the current seek pointer.
STREAM_SEEK_END: Specifies that the origin of the offset in the Seek method is the end of the stream.
STREAM_SEEK_SET: Specifies that the origin of the offset in the Seek method is the beginning of the stream.