4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     4 // under the terms of "Eclipse Public License v1.0"

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

   544 	ESqlBinary 

   589 	ESqlBinary

   828 The class is used for reading the content of a column containing a large

   885 The class is used for reading the content of a column containing either 

   829 amount of either binary data or text data.

   886 binary data or text data.

   905 The class is used to set a large amount of either binary data or text data

   970 The class is used to set binary data or text data into a parameter. 

   906 into a parameter. This is a also known as binding a parameter.

   971 This is a also known as binding a parameter.

   972 TSqlResourceTester class is used internally by the SQL server out of memory and resource leaking

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

   973 tests. 

  1046 

   974 It provides methods for heap allocation failure simulation and resource checking and counting.

  1047 The target blob is identified using the relevant database connection, table name, 

   975 

  1048 column name and ROWID of the record to which the blob belongs (also the attached

   976 @internalAll

  1049 database name if the blob is contained in an attached database).

   977 @released

  1050 

   978 */

  1051 A blob in this context refers to the content of a BLOB or TEXT column, 

   979 class TSqlResourceTester

  1052 and a read handle can be opened on both types of column.

   980 	{

  1053 For TEXT columns it is important to note that no conversions are performed on 

   981 public:	

  1054 data retrieved using this class - the data is returned as a stream of bytes.

   982 	IMPORT_C static void Mark();

  1055 

   983 	IMPORT_C static void Check();

  1056 The class derives from RReadStream and provides all of its streaming methods.

   984 	IMPORT_C static TInt Count();

  1057 The SizeL() method can be used to check the total size of the blob, in bytes.

   985 	IMPORT_C static void SetDbHeapFailure(TInt aAllocFailType,TInt aRate);

  1058 

   986 	IMPORT_C static void SetHeapFailure(TInt aAllocFailType,TInt aRate);

  1059 It is strongly recommended to use this class for reading the content of large blobs 

   987 

  1060 because it significantly reduces the amount of RAM that is used when compared to using the 

  1061 RSqlColumnReadStream, RSqlStatement::ColumnBinary(L) or RSqlStatement::ColumnText(L) APIs.

  1062 

  1063 Specifically, it is recommended to use this class for blobs over 2Mb in size.

  1064 Indeed, in some circumstances where very large blobs are in use it may be impossible

  1065 to read the blob content using the legacy APIs (due to the server's finite RAM capacity), 

  1066 and this class may provide the only way to access the data.

  1067 

  1068 The following code illustrates typical use cases of this class:

  1069 

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

  1071 

  1072 @code

  1073 RSqlDatabase db;

  1074 CleanupClosePushL(db);

  1075 <open/create "db" object>;

  1076 RSqlBlobReadStream rdStrm;

  1077 CleanupClosePushL(rdStrm);

  1078 rdStrm.OpenL(db, <table_name>, <column_name>);

  1079 HBufC8* buffer = HBufC8::NewLC(KBlockSize);

  1080 TPtr8 bufPtr(buffer->Des());

  1081 TInt size = rdStrm.SizeL();

  1082 while(size)

  1083 	{

  1084 	TInt bytesToRead = (size >= KBlockSize) ? KBlockSize : size ;

  1085 	rdStrm.ReadL(bufPtr, bytesToRead); // read the next block of data		

  1086 	<do something with the block of data>

  1087 	size =- bytesToRead;

  1088 	}

  1089 CleanupStack::PopAndDestroy(3); // buffer, rdStrm, db

  1090 @endcode

  1091 

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

  1093 

  1094 @code

  1095 RSqlDatabase db;

  1096 CleanupClosePushL(db);

  1097 <open/create "db" object>;

  1098 RSqlStatement stmt;

  1099 CleanupClosePushL(stmt);

  1100 <prepare "stmt" object to SELECT the ROWIDs of a collection of blob objects>;

  1101 TInt rc = 0;

  1102 while((rc = stmt.Next()) == KSqlAtRow)

  1103 	{

  1104 	TInt64 rowid = stmt.ColumnInt64(0);	

  1105 	RSqlBlobReadStream rdStrm;

  1106 	CleanupClosePushL(rdStrm);

  1107 	rdStrm.OpenL(db, <table_name>, <column_name>, rowid);

  1108 	

  1109 	HBufC8* buffer = HBufC8::NewLC(KBlockSize);

  1110 	TPtr8 bufPtr(buffer->Des());

  1111 	TInt size = rdStrm.SizeL();

  1112 	while(size)

  1113 		{

  1114 		TInt bytesToRead = (size >= KBlockSize) ? KBlockSize : size ;

  1115 		rdStrm.ReadL(bufPtr, bytesToRead); // read the next block of data		

  1116 		<do something with the block of data>

  1117 		size =- bytesToRead;

  1118 		}

  1119 	CleanupStack::PopAndDestroy(2); // buffer, rdStrm

  1120 	}

  1121 CleanupStack::PopAndDestroy(2); // stmt, db

  1122 @endcode

  1123 

  1124 @see RSqlBlobWriteStream

  1125 @see RSqlDatabase::LastInsertedRowId()

  1126 

  1127 @publishedAll

  1128 @released

  1129 */

  1130 class RSqlBlobReadStream : public RReadStream

  1131 	{

  1132 public:						

  1133 	IMPORT_C void OpenL(RSqlDatabase& aDb, const TDesC& aTableName, const TDesC& aColumnName, 

  1134 						TInt64 aRowId = KSqlLastInsertedRowId, const TDesC& aDbName = KNullDesC);

  1135 	IMPORT_C TInt SizeL();

  1136 	};

  1137 

  1138 /**

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

  1140 

  1141 The target blob is identified using the relevant database connection, table name, 

  1142 column name and ROWID of the record to which the blob belongs (also the attached

  1143 database name if the blob is contained in an attached database).

  1144 

  1145 A blob in this context refers to the content of a BLOB or TEXT column, 

  1146 and a write handle can be opened on both types of column, except if the

  1147 column is indexed, in which case the open call will fail with KSqlErrGeneral.

  1148 For TEXT columns it is important to note that no conversions are performed on data 

  1149 that is stored using this class - the data is simply stored as a stream of bytes.

  1150 

  1151 The class derives from RWriteStream and provides all of its streaming methods.

  1152 The SizeL() method can be used to check the total size of the blob, in bytes.

  1153 Note that this class cannot be used to increase the size of a blob, only to modify 

  1154 the existing contents of a blob. An attempt to write beyond the end of a blob will

  1155 fail with KErrEof.

  1156 

  1157 It is strongly recommended to use this class for writing the content of large blobs 

  1158 because it significantly reduces the amount of RAM that is used when compared to using 

  1159 the RSqlParamWriteStream, RSqlStatement::BindBinary or RSqlStatement::BindText APIs.

  1160 

  1161 Specifically, it is recommended to use this class for blobs over 2Mb in size.

  1162 Indeed, in some circumstances where very large blobs are required it may be impossible

  1163 to create a blob or update its content using the legacy APIs (due to the server's finite 

  1164 RAM capacity), and this class may provide the only way to achieve this.

  1165 

  1166 Using this class in combination with zeroblobs it is possible to create and manipulate 

  1167 blobs that are gigabytes in size. A zeroblob acts as a place-holder for a blob whose 

  1168 content is later written using this class and one can be created using an INSERT 

  1169 statement that either contains the SQLite 'zeroblob()' function or on which 

  1170 RSqlStatement::BindZeroBlob() has been executed.

  1171 Note that a zeroblob should be created in a column after which there are no columns 

  1172 that contain anything other than zeroblobs or NULLs, otherwise the zeroblob must be 

  1173 allocated in full in RAM.

  1174 

  1175 When creating a zeroblob it is recommended, where possible, to create the zeroblob and

  1176 then write the blob content within the same transaction. Otherwise the zeroblob will 

  1177 have to be journalled before being written to.

  1178 

  1179 It is also strongly recommended to execute calls to WriteL() within a transaction. 

  1180 If a leave occurs during a call to WriteL() then the current state of the blob object is

  1181 undefined and a ROLLBACK should be executed to return the blob object to its previous state.

  1182 Note that in order for a ROLLBACK to execute successfully all open RSqlBlobReadStream 

  1183 and RSqlBlobWriteStream handles and all open RSqlStatement objects must be closed 

  1184 before the ROLLBACK is executed.

  1185 

  1186 The following code illustrates typical use cases of this class:

  1187 

  1188 CASE 1 - creating a 5Mb blob.

  1189 

  1190 @code

  1191 RSqlDatabase db;

  1192 CleanupClosePushL(db);

  1193 <open/create "db" object>;

  1194 CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function

  1195 TInt err = db.Exec(_L("BEGIN"));

  1196 <check err>

  1197 err = db.Exec(_L("INSERT INTO table1 VALUES(35, zeroblob(5242880))"));

  1198 <check err>

  1199 RSqlBlobWriteStream wrStrm;

  1200 CleanupClosePushL(wrStrm);

  1201 wrStrm.OpenL(db, <table_name>, <column_name>);

  1202 TInt size = wrStrm.SizeL();

  1203 while(size)

  1204 	{

  1205 	TInt bytesToWrite = (size >= KBlockSize) ? KBlockSize : size ;

  1206 	<fill a buffer 'buf' with this amount of the blob data>

  1207 	wrStrm.WriteL(buf); // write the next block of data		

  1208 	size =- bytesToWrite;

  1209 	}

  1210 CleanupStack::PopAndDestroy(&wrStrm);

  1211 CleanupStack::Pop(); // TCleanupItem

  1212 err = db.Exec(_L("COMMIT")); // blob data committed to disk

  1213 <check err>

  1214 CleanupStack::PopAndDestroy(&db);

  1215 @endcode

  1216 

  1217 CASE 2 - updating a large blob in the last inserted record.

  1218 

  1219 @code

  1220 RSqlDatabase db;

  1221 CleanupClosePushL(db);

  1222 <open/create "db" object>;

  1223 CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function

  1224 TInt err = db.Exec(_L("BEGIN"));

  1225 <check err>

  1226 RSqlBlobWriteStream wrStrm;

  1227 CleanupClosePushL(wrStrm);

  1228 wrStrm.OpenL(db, <table_name>, <column_name>);

  1229 <fill a buffer 'buf' with the changed blob data>

  1230 wrStrm.WriteL(buf); // update the blob

  1231 CleanupStack::PopAndDestroy(&wrStrm);

  1232 CleanupStack::Pop(); // TCleanupItem

  1233 err = db.Exec(_L("COMMIT")); // blob data committed to disk

  1234 <check err>

  1235 CleanupStack::PopAndDestroy(&db);

  1236 @endcode

  1237 

  1238 @see RSqlBlobReadStream

  1239 @see RSqlDatabase::LastInsertedRowId()

  1240 @see RSqlStatement::BindZeroBlob()

  1241 

  1242 @publishedAll

  1243 @released

  1244 */

  1245 class RSqlBlobWriteStream : public RWriteStream

  1246 	{

  1247 public:

  1248 	IMPORT_C void OpenL(RSqlDatabase& aDb, const TDesC& aTableName, const TDesC& aColumnName, 

  1249 						TInt64 aRowId = KSqlLastInsertedRowId, const TDesC& aDbName = KNullDesC);

  1250 	IMPORT_C TInt SizeL();

  1251 	};

  1252 

  1253 /**

  1254 Utility class that provides methods for reading and writing the entire content of 

  1255 a blob in a single call.

  1256 

  1257 The target blob is identified using the relevant database connection, table name, 

  1258 column name and ROWID of the record to which the blob belongs (also the attached

  1259 database name if the blob is contained in an attached database).

  1260 

  1261 The behaviour of the RSqlBlobReadStream class and the recommendations for using

  1262 it exist for the Get() and GetLC() methods of this class. Similarly, the behaviour 

  1263 of the RSqlBlobWriteStream class and the recommendations for using it exist for the 

  1264 SetL() method of this class.

  1265 

  1266 In particular, it is strongly recommended to use this class or the RSqlBlobReadStream

  1267 and RSqlBlobWriteStream classes for reading and writing the content of large blobs 

  1268 because it significantly reduces the amount of RAM that is used when compared to using 

  1269 the legacy streaming and RSqlStatement APIs.

  1270 

  1271 Specifically, it is recommended to use this class for blobs over 2Mb in size.

  1272 Indeed, in some circumstances where very large blobs are in use it may be impossible

  1273 to read or write to a blob using the legacy APIs (due to the server's finite 

  1274 RAM capacity), and this class or the RSqlBlobReadStream and RSqlBlobWriteStream classes 

  1275 may provide the only way to achieve this.

  1276 

  1277 It is strongly recommended to execute calls to the SetL() method within a transaction. 

  1278 If a leave occurs during a call to SetL() then the current state of the blob object is 

  1279 undefined and a ROLLBACK should be executed to return the blob object to its previous state.

  1280 Note that in order for a ROLLBACK to execute successfully all open RSqlBlobReadStream 

  1281 and RSqlBlobWriteStream handles and all open RSqlStatement objects must be closed 

  1282 before the ROLLBACK is executed.

  1283 

  1284 When using SetL() to update the content of a zeroblob it is recommended, where possible, 

  1285 to create the zeroblob and then call SetL() within the same transaction. 

  1286 Otherwise the zeroblob will have to be journalled before being written to.

  1287 

  1288 The following code illustrates typical use cases of this class:

  1289 

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

  1291 

  1292 @code

  1293 RSqlDatabase db;

  1294 CleanupClosePushL(db);

  1295 <open/create "db" object>;

  1296 HBufC8* wholeBlob = TSqlBlob::GetLC(db, <table_name>, <column_name>, <rowid>);

  1297 <do something with the blob data>

  1298 CleanupStack::PopAndDestroy(2); // wholeBlob, db

  1299 @endcode

  1300 

  1301 

  1302 CASE 2 - creating a 4Mb blob.

  1303 

  1304 @code

  1305 RSqlDatabase db;

  1306 CleanupClosePushL(db);

  1307 <open/create "db" object>;

  1308 CleanupStack::PushL(TCleanupItem(&DoRollback, &db)); // rollback function

  1309 TInt err = db.Exec(_L("BEGIN"));

  1310 <check err>

  1311 err = db.Exec(_L("INSERT INTO table1 VALUES(99, zeroblob(4194304))"));

  1312 <check err>

  1313 <fill a buffer 'buf' with 4Mb of blob data>

  1314 TSqlBlob::SetL(db, <table_name>, <column_name>, buf);

  1315 CleanupStack::Pop(); // TCleanupItem

  1316 err = db.Exec(_L("COMMIT")); // blob data committed to disk

  1317 <check err>

  1318 CleanupStack::PopAndDestroy(&db);

  1319 @endcode

  1320 

  1321 @see RSqlBlobReadStream

  1322 @see RSqlBlobWriteStream

  1323 @see RSqlDatabase::LastInsertedRowId()

  1324 @see RSqlStatement::BindZeroBlob()

  1325 

  1326 @publishedAll

  1327 @released

  1328 */

  1329 class TSqlBlob

  1330 	{

  1331 public:					  		  	  

  1332 	IMPORT_C static HBufC8* GetLC(RSqlDatabase& aDb, 	

  1333 					     		  const TDesC& aTableName, 

  1334 					     		  const TDesC& aColumnName, 	

  1335 					     		  TInt64 aRowId = KSqlLastInsertedRowId,

  1336 					     		  const TDesC& aDbName = KNullDesC);

  1337 								  		  	  

  1338 	IMPORT_C static TInt Get(RSqlDatabase& aDb, 	

  1339 					 		 const TDesC& aTableName, 

  1340 					 		 const TDesC& aColumnName, 	

  1341 					 		 TDes8& aBuffer,

  1342 					 		 TInt64 aRowId = KSqlLastInsertedRowId,

  1343 					 		 const TDesC& aDbName = KNullDesC);			 		 

  1344 

  1345 	IMPORT_C static void SetL(RSqlDatabase& aDb, 	

  1346 					  		  const TDesC& aTableName, 

  1347 					  		  const TDesC& aColumnName,

  1348 					  		  const TDesC8& aData,	

  1349 					  		  TInt64 aRowId = KSqlLastInsertedRowId,

  1350 					  		  const TDesC& aDbName = KNullDesC);