MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 9: Row and Stream Objects

Stream Objects

It is a common scenario for a consumer to bind to a row object, access its columns, and open its default stream, if it has one. This can be done using an OLE DB stream object, which is an OLE DB object that exposes the COM IStream interface. A row object can contain more than one stream object, one of which can be designated as the default stream for the row.

The OLE DB stream object cotype is defined as follows. (For more information about cotypes, see "OLE DB Objects" in Chapter 1, "Overview of OLE DB.")

Note   ADO 2.5 requires support for the IStream interface.

CoType TStream {
   [mandatory]   interface ISequentialStream;
   [optional]    interface IConnectionPointContainer;
   [optional]    interface IDBAsynchStatus;
   [optional]    interface IDBInitialize;
   [optional]    interface IGetSourceRow;
   [optional]    interface ISupportErrorInfo;
   [optional]    interface IStream;
}

All stream objects must expose the ISequentialStream interface, which is a subset of the COM IStream interface that provides forward-only reading and writing of data.

The provider can designate one stream-valued column as the default stream of the row object. DBROWCOL_DEFAULTSTREAM is provided as a shortcut column ID (DBID) on a row object to identify the column, if any, that is the default stream of that row. For more information about the default stream column and DBROWCOL_DEFAULTSTREAM, see "Special Row Column DBIDs," earlier in this chapter.

To obtain the source row object for a default stream object, the consumer calls IGetSourceRow::GetSourceRow on the default stream object. To open the default stream object for a row object, the consumer calls IRow::Open on the row object, passing in either the column ID (DBID) of the default stream column or the shortcut value DBROWCOL_DEFAULTSTREAM.

When binding to a row, the default behavior of IBindResource::Bind, ICreateRow::CreateRow, and IScopedOperations::Bind is to fetch the default stream as well as the columns of the row object. To override this behavior, the consumer can specify bind flag DBBINDURLFLAG_DELAYFETCHSTREAM to delay access to the default stream until it is explicitly opened, or the consumer can specify DBBINDURLFLAG_DELAYFETCHCOLUMNS to delay access to row columns until they are explicitly accessed. The absence of either bind flag signals the consumer's intent to immediately open the default stream or access the columns of the row. To minimize network round-trips, the provider should immediately instantiate the default stream object and fetch its contents or download the columns of the row.