ISequentialStream

OLE DB Programmer's Reference

ISequentialStream

ISequentialStream is the preferred minimal interface for reading and writing binary large object (BLOB) data in OLE DB. ISequentialStream is a subset of the COM IStream interface and provides forward-only reading and writing of data. The IStream interface inherits its Read and Write methods from ISequentialStream .

When to Implement

You can implement ISequentialStream on an object if you require simple sequential access to a stream object. If you implement IStream , you must provide an implementation of the Read and Write methods from ISequentialStream .

Note Most applications do not implement ISequentialStream as a separate interface, and it is not required to provide it separately even when an IStream implementation is provided. 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.

When to Call

Call the methods of the ISequentialStream interface from a container or application to perform sequential reads and writes of data. Most applications call the Read and Write methods through the IStream interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

ISequentialStream Methods	Description
ISequentialStream::Read	Reads a specified number of bytes from the stream object into memory, starting at the current seek pointer.
ISequentialStream::Write	Writes a specified number of bytes to the stream object, starting at the current seek pointer.

OLE DB Programmer's Reference

ISequentialStream : IUnknown

ISequentialStream is a simplified version of IStream that provides strictly sequential stream access to BLOB data. This class behaves as if it were the strict ancestor of IStream . In particular, any object that implements IStream can choose to identify itself as ISequentialStream because the first two slots in the IStream vtable and the definition of those methods exactly matches the vtable and methods of ISequentialStream .

Method	Description
ISequentialStream::Read	Reads a specified number of bytes from the stream.
ISequentialStream::Write	Writes a specified number of bytes to the stream.

OLE DB Programmer's Reference

ISequentialStream::Read

Reads a specified number of bytes from the stream object into memory starting at the current read/write location within the stream.

HRESULT Read(void *pv, ULONG cb, ULONG *pcbRead);

Parameters

pv: [in]
Points to the buffer into which the stream is read. If an error occurs, this value is NULL.
cb: [in]
Specifies the number of bytes of data to attempt to read from the stream object.
pcbRead: [out]
Pointer to a location where this method writes the actual number of bytes read from the stream object. You can set this pointer to NULL to indicate that you are not interested in this value. In this case, this method does not provide the actual number of bytes read.

Return Code

S_OK: Data was successfully read from the stream object.
S_FALSE: The data could not be read from the stream object.
E_PENDING: Asynchronous Storage only: Part or all of the data to be read is currently unavailable. For more information, see the documentation on the COM interface IFillLockBytes , and see "Asynchronous Storage" in the Structured Storage documentation.
STG_E_ACCESSDENIED: The caller does not have sufficient permissions for reading this stream object.
STG_E_INVALIDPOINTER: One of the pointer values is invalid.
STG_E_REVERTED: The object has been invalidated by a revert operation above it in the transaction tree.

Comments

This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the current read/write location within the stream by the actual number of bytes read.

The number of bytes actually read is returned in the pcbRead parameter.

The actual number of bytes read can be fewer than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation.

Some implementations might return an error if the end of the stream is reached during the read. You must be prepared to deal with the error return or S_OK return values on the end of stream reads.

Flylib.com

Category list

Similar pages

ISequentialStream

ISequentialStream

When to Implement

When to Call

Methods in Vtable Order

ISequentialStream : IUnknown

ISequentialStream::Read

Similar products