RSqlBlobReadStream Class Reference

Detailed Description

A direct handle to a blob, used for reading the content of the blob via a streaming interface.

The target blob is identified using the relevant database connection, table name, column name and ROWID of the record to which the blob belongs (also the attached database name if the blob is contained in an attached database).

A blob in this context refers to the content of a BLOB or TEXT column, and a read handle can be opened on both types of column. For TEXT columns it is important to note that no conversions are performed on data retrieved using this class - the data is returned as a stream of bytes.

The class derives from RReadStream and provides all of its streaming methods. The SizeL() method can be used to check the total size of the blob, in bytes.

It is strongly recommended to use this class for reading the content of large blobs because it significantly reduces the amount of RAM that is used when compared to using the RSqlColumnReadStream, RSqlStatement::ColumnBinary(L) or RSqlStatement::ColumnText(L) APIs.

Specifically, it is recommended to use this class for blobs over 2Mb in size. Indeed, in some circumstances where very large blobs are in use it may be impossible to read the blob content using the legacy APIs (due to the server's finite RAM capacity), and this class may provide the only way to access the data.

The following code illustrates typical use cases of this class:

CASE 1 - reading large blob data from the last inserted record.

RSqlDatabase db;
CleanupClosePushL(db);
<open/create "db" object>;
RSqlBlobReadStream rdStrm;
CleanupClosePushL(rdStrm);
rdStrm.OpenL(db, <table_name>, <column_name>);
HBufC8* buffer = HBufC8::NewLC(KBlockSize);
TPtr8 bufPtr(buffer->Des());
TInt size = rdStrm.SizeL();
while(size)
	{
	TInt bytesToRead = (size >= KBlockSize) ? KBlockSize : size ;
	rdStrm.ReadL(bufPtr, bytesToRead); // read the next block of data		
	<do something with the block of data>
	size =- bytesToRead;
	}
CleanupStack::PopAndDestroy(3); // buffer, rdStrm, db

CASE 2 - reading large blob data from a selection of records.

RSqlDatabase db;
CleanupClosePushL(db);
<open/create "db" object>;
RSqlStatement stmt;
CleanupClosePushL(stmt);
<prepare "stmt" object to SELECT the ROWIDs of a collection of blob objects>;
TInt rc = 0;
while((rc = stmt.Next()) == KSqlAtRow)
	{
	TInt64 rowid = stmt.ColumnInt64(0);	
	RSqlBlobReadStream rdStrm;
	CleanupClosePushL(rdStrm);
	rdStrm.OpenL(db, <table_name>, <column_name>, rowid);
	
	HBufC8* buffer = HBufC8::NewLC(KBlockSize);
	TPtr8 bufPtr(buffer->Des());
	TInt size = rdStrm.SizeL();
	while(size)
		{
		TInt bytesToRead = (size >= KBlockSize) ? KBlockSize : size ;
		rdStrm.ReadL(bufPtr, bytesToRead); // read the next block of data		
		<do something with the block of data>
		size =- bytesToRead;
		}
	CleanupStack::PopAndDestroy(2); // buffer, rdStrm
	}
CleanupStack::PopAndDestroy(2); // stmt, db

See also: RSqlBlobWriteStream RSqlDatabase::LastInsertedRowId()