TSqlBlob Class Reference

#include <sqldb.h>

Link against: sqldb.lib

class TSqlBlob
Public Member Functions
IMPORT_C TIntGet(RSqlDatabase &, const TDesC &, const TDesC &, TDes8 &, TInt64, const TDesC &)
IMPORT_C HBufC8 *GetLC(RSqlDatabase &, const TDesC &, const TDesC &, TInt64, const TDesC &)
IMPORT_C voidSetL(RSqlDatabase &, const TDesC &, const TDesC &, const TDesC8 &, TInt64, const TDesC &)

Detailed Description

Utility class that provides methods for reading and writing the entire content of a blob in a single call.

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).

The behaviour of the RSqlBlobReadStream class and the recommendations for using it exist for the Get() and GetLC() methods of this class. Similarly, the behaviour of the RSqlBlobWriteStream class and the recommendations for using it exist for the SetL() method of this class.

In particular, it is strongly recommended to use this class or the RSqlBlobReadStream and RSqlBlobWriteStream classes for reading and writing the content of large blobs because it significantly reduces the amount of RAM that is used when compared to using the legacy streaming and RSqlStatement 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 or write to a blob using the legacy APIs (due to the server's finite RAM capacity), and this class or the RSqlBlobReadStream and RSqlBlobWriteStream classes may provide the only way to achieve this.

It is strongly recommended to execute calls to the SetL() method within a transaction. If a leave occurs during a call to SetL() then the current state of the blob object is undefined and a ROLLBACK should be executed to return the blob object to its previous state. Note that in order for a ROLLBACK to execute successfully all open RSqlBlobReadStream and RSqlBlobWriteStream handles and all open RSqlStatement objects must be closed before the ROLLBACK is executed.

When using SetL() to update the content of a zeroblob it is recommended, where possible, to create the zeroblob and then call SetL() within the same transaction. Otherwise the zeroblob will have to be journalled before being written to.

The following code illustrates typical use cases of this class:

CASE 1 - retrieving the entire content of a large blob.

RSqlDatabase db;
CleanupClosePushL(db);
<open/create "db" object>;
HBufC8* wholeBlob = TSqlBlob::GetLC(db, <table_name>, <column_name>, <rowid>);
<do something with the blob data>
CleanupStack::PopAndDestroy(2); // wholeBlob, db

CASE 2 - creating a 4Mb blob.

RSqlDatabase db;
CleanupClosePushL(db);
<open/create "db" object>;
CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function
TInt err = db.Exec(_L("BEGIN"));
<check err>
err = db.Exec(_L("INSERT INTO table1 VALUES(99, zeroblob(4194304))"));
<check err>
<fill a buffer 'buf' with 4Mb of blob data>
TSqlBlob::SetL(db, <table_name>, <column_name>, buf);
CleanupStack::Pop(); // TCleanupItem
err = db.Exec(_L("COMMIT")); // blob data committed to disk
<check err>
CleanupStack::PopAndDestroy(&db);

See also: RSqlBlobReadStream RSqlBlobWriteStream RSqlDatabase::LastInsertedRowId() RSqlStatement::BindZeroBlob()

Member Function Documentation

Get ( RSqlDatabase &, const TDesC &, const TDesC &, TDes8 &, TInt64, const TDesC & )

IMPORT_C TIntGet(RSqlDatabase &aDb,
const TDesC &aTableName,
const TDesC &aColumnName,
TDes8 &aBuffer,
TInt64aRowId =  KSqlLastInsertedRowId ,
const TDesC &aDbName =  KNullDesC
)[static]

Retrieves the entire content of a blob into a client specified buffer.

panic
SqlDb 2 The database object is not yet created
panic
SqlDb 3 Server failed to create a handle to the blob
panic
SqlDb 4 In _DEBUG mode. Bad parameter value
panic
SqlDb 7 In _DEBUG mode. NULL blob handle or miscalculation of remaining data to be read
capability
None, if the aDb parameter represents a handle which operates on a non-secure database; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the blob belongs to a secure database;
ParameterDescription
aDbA connection to the database that contains the blob
aTableNameThe name of the table that contains the blob
aColumnNameThe name of the column that contains the blob
aRowIdThe ROWID of the record that contains the blob, or KSqlLastInsertedRowId if the last inserted ROWID of the specified database connection is to be used
aDbNameThe name of the attached database if the blob is contained in an attached database

Returns: KSqlErrGeneral, Invalid database connection or table name or column name or column type or ROWID or database name; KErrNoMemory, An out of memory condition occurred; KErrArgument, The ROWID is zero or negative or a UTF-16 to UTF-8 string conversion failed; KErrOverflow, The specified buffer is not big enough to hold the entire blob; KErrBadName, The table name, column name or database name has an invalid length; KErrPermissionDenied, The client does not have the required security capabilites for this operation; Note that the function may also leave with some other system wide errors or database specific errors categorised as ESqlDbError.

GetLC ( RSqlDatabase &, const TDesC &, const TDesC &, TInt64, const TDesC & )

IMPORT_C HBufC8 *GetLC(RSqlDatabase &aDb,
const TDesC &aTableName,
const TDesC &aColumnName,
TInt64aRowId =  KSqlLastInsertedRowId ,
const TDesC &aDbName =  KNullDesC
)[static]

Retrieves the entire content of a blob and returns it to the client in a heap allocated buffer which has been placed on the cleanup stack. It is the responsibility of the client to destroy the returned buffer.

leave
KSqlErrGeneral, Invalid database connection or table name or column name or column type or ROWID or database name; KErrNoMemory, An out of memory condition occurred; KErrArgument, The ROWID is zero or negative or a UTF-16 to UTF-8 string conversion failed; KErrBadName, The table name, column name or database name has an invalid length; KErrPermissionDenied, The client does not have the required security capabilites for this operation; Note that the function may also leave with some other system wide errors or database specific errors categorised as ESqlDbError.
panic
SqlDb 2 The database object is not yet created
panic
SqlDb 3 Server failed to create a handle to the blob
panic
SqlDb 4 In _DEBUG mode. Bad parameter value
panic
SqlDb 7 In _DEBUG mode. NULL blob handle or miscalculation of remaining data to be read
capability
None, if the aDb parameter represents a handle which operates on a non-secure database; RSqlSecurityPolicy::EReadPolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the blob belongs to a secure database;
ParameterDescription
aDbA connection to the database that contains the blob
aTableNameThe name of the table that contains the blob
aColumnNameThe name of the column that contains the blob
aRowIdThe ROWID of the record that contains the blob, or KSqlLastInsertedRowId if the last inserted ROWID of the specified database connection is to be used
aDbNameThe name of the attached database if the blob is contained in an attached database

SetL ( RSqlDatabase &, const TDesC &, const TDesC &, const TDesC8 &, TInt64, const TDesC & )

IMPORT_C voidSetL(RSqlDatabase &aDb,
const TDesC &aTableName,
const TDesC &aColumnName,
const TDesC8 &aData,
TInt64aRowId =  KSqlLastInsertedRowId ,
const TDesC &aDbName =  KNullDesC
)[static]

Writes the data in a client specified buffer to a blob.

leave
KSqlErrGeneral, Invalid database connection or table name or column name or column type or ROWID or database name, or the specified column is indexed; KErrNoMemory, An out of memory condition occurred; KErrArgument, The ROWID is zero or negative or a UTF-16 to UTF-8 string conversion failed; KErrEof, The data in the specified buffer is larger in size than the blob object; KErrBadName, The table name, column name or database name has an invalid length; KErrPermissionDenied, The client does not have the required security capabilites for this operation; Note that the function may also leave with some other system wide errors or database specific errors categorised as ESqlDbError.
panic
SqlDb 2 The database object is not yet created
panic
SqlDb 3 Server failed to create a handle to the blob
panic
SqlDb 4 In _DEBUG mode. Bad parameter value
panic
SqlDb 7 In _DEBUG mode. NULL blob handle or miscalculation of remaining data to be written
capability
None, if the aDb parameter represents a handle which operates on a non-secure database; RSqlSecurityPolicy::EWritePolicy or RSqlSecurityPolicy::ESchemaPolicy database policy type, if the blob belongs to a secure database;
ParameterDescription
aDbA connection to the database that contains the blob
aTableNameThe name of the table that contains the blob
aColumnNameThe name of the column that contains the blob
aRowIdThe ROWID of the record that contains the blob, or KSqlLastInsertedRowId if the last inserted ROWID of the specified database connection is to be used
aDbNameThe name of the attached database if the blob is contained in an attached database