sl@0: // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Client incremental class
sl@0: // 
sl@0: //
sl@0: 
sl@0: #include "UD_STD.H"
sl@0: 
sl@0: // Class RDbIncremental
sl@0: 
sl@0: /** Releases the resources used by the incremental operations object. If the operation 
sl@0: is not yet complete, then the operation is abandoned and the database is rolled 
sl@0: back to its state before the operation started. */
sl@0: EXPORT_C void RDbIncremental::Close()
sl@0: 	{
sl@0: 	iState.Close();
sl@0: 	}
sl@0: 
sl@0: /** Performs the next step in the incremental operation, returning when the step 
sl@0: is complete.
sl@0: 
sl@0: @param aStep Initially, contains the value returned from any of the initiating 
sl@0: functions or the last call to perform an operational step. On return, contains 
sl@0: a value which is less than or equal to the initial value. If it equals 0, 
sl@0: then the operation has completed successfully and the incremental object should 
sl@0: be closed.
sl@0: @return KErrNone if successful, or one of the DBMS database error codes. If 
sl@0: this indicates an error, then the incremental object should be closed and 
sl@0: the operation aborted. */
sl@0: EXPORT_C TInt RDbIncremental::Next(TInt& aStep)
sl@0: 	{
sl@0: 	__ASSERT_ALWAYS(aStep>0,Panic(EDbInvalidIncrementalStep));
sl@0: 	TRAPD(r,iState->NextL(aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Performs the next step in the incremental operation, returning immediately 
sl@0: and signalling the request status when the step is complete. 
sl@0: 
sl@0: This function is most effectively used when the incremental operation is packaged 
sl@0: as an active object.
sl@0: 
sl@0: Note that the step parameter is packaged to enable this API to work for asynchronous 
sl@0: calls in client/server implementations of DBMS.
sl@0: 
sl@0: @param aStep Initially, contains the value returned from any of the initiating 
sl@0: functions or the last call to perform an operational step. On return, contains 
sl@0: a value which is less than or equal to the initial value. If it equals 0, 
sl@0: then the operation has completed successfully and the incremental object should 
sl@0: be closed.
sl@0: @param aStatus The request status used to contain completion information for 
sl@0: the function. On completion, contains the completion status or one of the 
sl@0: DBMS database error codes. If this indicates an error, then the incremental 
sl@0: object should be closed and the operation aborted.
sl@0: @see TPckgBuf */
sl@0: EXPORT_C void RDbIncremental::Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)
sl@0: 	{
sl@0: 	__ASSERT_ALWAYS(aStep.operator()()>0,Panic(EDbInvalidIncrementalStep));
sl@0: 	iState->Next(aStep,aStatus);
sl@0: 	}
sl@0: 
sl@0: LOCAL_C TInt Utility(RDbHandle<CDbIncremental>& aInc
sl@0: 						 ,RDbHandle<CDbDatabase>& aDb,TInt& aStep
sl@0: 						 ,CDbDatabase::TUtility aType)
sl@0: 	{
sl@0: 	TRAPD(r,aInc=aDb->UtilityL(aType,aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Initiates a database recovery operation.
sl@0: 
sl@0: This is the incremental version of RDbDatabase::Recover().
sl@0: Recover() will try to rebuild database indexes if they are broken.
sl@0: If the database data is corrupted, it cannot be recovered.
sl@0: 
sl@0: @param aDatabase The database to recover.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to NextL().
sl@0: 
sl@0: @return KErrNone if successful, or one of the DBMS database error codes. If 
sl@0: recovery fails with either KErrNoMemory or KErrDiskFull, then recovery may 
sl@0: be attempted again when more memory or disk space is available.
sl@0: 
sl@0: @see RDbDatabase::Recover() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::Recover(RDbDatabase& aDatabase,TInt& aStep)
sl@0: 	{
sl@0: 	return Utility(iState,aDatabase.iDatabase,aStep,CDbDatabase::ERecover);
sl@0: 	}
sl@0: 
sl@0: /** Initiates the operation of calculating and updating database statistics.
sl@0: 
sl@0: This is the incremental form of RDbDatabase::UpdateStats()
sl@0: 
sl@0: @param aDatabase The database whose statistics are to be updated.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to Next() to 
sl@0: continue the operation.
sl@0: @return KErrNone if successful, otherwise another of the system-wide error 
sl@0: codes.
sl@0: @see RDbDatabase::UpdateStats() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::UpdateStats(RDbDatabase& aDatabase,TInt& aStep)
sl@0: 	{
sl@0: 	return Utility(iState,aDatabase.iDatabase,aStep,CDbDatabase::EStats);
sl@0: 	}
sl@0: 
sl@0: /** Initiates the operation of compacting a database. This is the incremental form 
sl@0: of RDbDatabase::Compact().
sl@0: 
sl@0: @param aDatabase The database to compact.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to Next() to 
sl@0: continue the operation.
sl@0: @return KErrNone if successful, otherwise another of the system-wide error 
sl@0: codes.
sl@0: @see RDbDatabase::Compact() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::Compact(RDbDatabase& aDatabase,TInt& aStep)
sl@0: 	{
sl@0: 	return Utility(iState,aDatabase.iDatabase,aStep,CDbDatabase::ECompact);
sl@0: 	}
sl@0: 
sl@0: /** Initiates a table discard operation on a database. All indexes belonging to 
sl@0: the table are also discarded as part of this operation.
sl@0: 
sl@0: This is the incremental version of RDbDatabase::DropTable().
sl@0: 
sl@0: @param aDatabase The database from which to drop the table.
sl@0: @param aTable The name of the table to drop.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to NextL().
sl@0: @return KErrNone if successful, or one of the DBMS database error codes. The 
sl@0: Store database always returns KErrNotSupported for this function.
sl@0: @see RDbDatabase::DropTable() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::DropTable(RDbDatabase& aDatabase,const TDesC& aTable,TInt& aStep)
sl@0: 	{
sl@0: 	TRAPD(r,iState=aDatabase.iDatabase->DropTableL(aTable,aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Initiates a table alteration operation on a database. This is the incremental 
sl@0: form of RDbDatabase::AlterTable().
sl@0: 
sl@0: @param aDatabase The database which has the table to be altered.
sl@0: @param aTable The name of the table which is to be altered.
sl@0: @param aNewDef A column set describing the new definition for the table.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to NextL().
sl@0: @return KErrNone if successful, or one of the DBMS database error codes. Specifically, 
sl@0: the function returns: KErrNotFound, if the table does not exist in the database. 
sl@0: KErrBadName if a column name is invalid. KErrArgument if the new column set 
sl@0: is empty, or there are duplicate column names, or if a column's maximum length 
sl@0: is non-positive but not KDbUndefinedLength, or a non-numeric column has the 
sl@0: auto-increment attribute, or an indexed column has been dropped, or a column 
sl@0: has changed its type or attributes, or a not-null or auto-increment column 
sl@0: has been added to a table which is not empty. KErrNotSupported if a column 
sl@0: type is out of the recognised range, or an unknown attribute bit is set, or 
sl@0: the maximum length for a Text8, Text16 or Binary column is more than 255. 
sl@0: KErrTooBig if the resulting record size can be larger than 8200 bytes.
sl@0: @see RDbDatabase::AlterTable() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::AlterTable(RDbDatabase& aDatabase,const TDesC& aTable,const CDbColSet& aNewDef,TInt& aStep)
sl@0: 	{
sl@0: 	TRAPD(r,iState=aDatabase.iDatabase->AlterTableL(aTable,aNewDef,aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Initiates an index creation operation on a database. This is the incremental 
sl@0: form of RDbDatabase::CreateIndex().
sl@0: 
sl@0: @param aDatabase The database on which to create the index.
sl@0: @param aName A name for the created index.
sl@0: @param aTable The name of the table on which to create the index.
sl@0: @param aKey The key for the new index.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to NextL().
sl@0: @return KErrNone if successful, or one of the DBMS database error codes. Specifically, 
sl@0: the function returns: KErrNotFound if the table does not exist in the database 
sl@0: or a key column is not found in the table. KErrAlreadyExists if an index of 
sl@0: the same name already exists on table or a duplicate key is present when building 
sl@0: an index. Note that it is not possible to tell the difference between the 
sl@0: possible causes of this error if index creation is not carried out incrementally. 
sl@0: KErrBadName if an index or column name is invalid. KErrArgument if the key 
sl@0: has no key columns or a fixed width column has a truncation length specified, 
sl@0: or an invalid truncation length has been specified for a key column, or a 
sl@0: LongText8 or LongText16 key column has no truncation length specified, or 
sl@0: the key contains a Binary or LongBinary column. KErrNotSupported if a truncated 
sl@0: key column is not the last one. KErrTooBig if the resulting key size is too 
sl@0: big.
sl@0: @see RDbDatabase::CreateIndex() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::CreateIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,const CDbKey& aKey,TInt& aStep)
sl@0: 	{
sl@0: 	TRAPD(r,iState=aDatabase.iDatabase->CreateIndexL(aName,aTable,aKey,aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Initiates an index discard operation on the database. This is the incremental 
sl@0: form of RDbDatabase::DropIndex().
sl@0: 
sl@0: @param aDatabase The database from which to drop the index.
sl@0: @param aName The name of the index to drop.
sl@0: @param aTable The name of the table which has the index.
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to NextL().
sl@0: @return KErrNone if successful, or one of the DBMS database error codes. Specifically, 
sl@0: the function returns KErrNotFound if the table or index does not exist
sl@0: @see RDbDatabase::DropIndex() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy the schema 
sl@0:             access policy for the database.
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::DropIndex(RDbDatabase& aDatabase,const TDesC& aName,const TDesC& aTable,TInt& aStep)
sl@0: 	{
sl@0: 	TRAPD(r,iState=aDatabase.iDatabase->DropIndexL(aName,aTable,aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: //
sl@0: // Incremental SQL Data definition execution
sl@0: //
sl@0: LOCAL_C CDbIncremental* ExecuteDDLL(CDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aStep)
sl@0: 	{
sl@0: 	CDbIncremental* inc=aDatabase.ExecuteL(aSql,aComparison,aStep);
sl@0: 	if ((inc==NULL)!=(aStep==0))
sl@0: 		{
sl@0: 		CDbObject::Destroy(inc);
sl@0: 		__LEAVE(KErrArgument);
sl@0: 		}
sl@0: 	return inc;
sl@0: 	}
sl@0: 
sl@0: /** Initiates the execution of a DDL (SQL schema update) statement on the database, 
sl@0: specifing additional comparison operations for some SQL statements.
sl@0: 
sl@0: This is the incremental form of RDbDatabase::Execute().
sl@0: 
sl@0: Note that to begin executing a DML (SQL data update) statement incrementally, 
sl@0: use the RDbUpdate class.
sl@0: 
sl@0: @param aDatabase The database on which the DDL (SQL schema update) statement 
sl@0: is to execute.
sl@0: @param aSql The DDL SQL statement to be executed on the database.
sl@0: @param aComparison This argument is used in the execution of some SQL statements, 
sl@0: and is ignored in all other SQL statements. Specifically: in CREATE INDEX 
sl@0: statements, it specifies the comparison operation used for text columns in 
sl@0: the index key. In UPDATE and DELETE statements, it specifies the comparison 
sl@0: operation used to evaluate the WHERE clause. 
sl@0: @param aStep On return, contains the initial step count for the incremental 
sl@0: operation. This value should be passed in to subsequent calls to Next() to 
sl@0: continue the operation.
sl@0: @return KErrNone if successful, otherwise another of the system-wide error 
sl@0: codes.
sl@0: @see RDbDatabase::Execute()
sl@0: @see RDbUpdate 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy:
sl@0:             - the schema access policy for the database, if the SQL statement is 
sl@0: 			  CREATE/DROP/ALTER; 
sl@0:             - the write access policy for the table in the SQL, if the SQL statement is 
sl@0: 			  INSERT/UPDATE/DELETE; 
sl@0: */
sl@0: EXPORT_C TInt RDbIncremental::Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aStep)
sl@0: 	{
sl@0: 	TRAPD(r,iState=ExecuteDDLL(*aDatabase.iDatabase,aSql,aComparison,aStep));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: // Class RDbUpdate
sl@0: 
sl@0: //
sl@0: // Incremental SQL Data definition execution
sl@0: //
sl@0: LOCAL_C CDbIncremental* ExecuteDMLL(CDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison,TInt& aRows)
sl@0: 	{
sl@0: 	CDbIncremental* inc=aDatabase.ExecuteL(aSql,aComparison,aRows);
sl@0: 	if ((inc==NULL)==(aRows==0))
sl@0: 		{
sl@0: 		CDbObject::Destroy(inc);
sl@0: 		__LEAVE(KErrArgument);
sl@0: 		}
sl@0: 	return inc;
sl@0: 	}
sl@0: 
sl@0: /** Initiates the incremental execution of a DML (SQL data update) statement on 
sl@0: the database. This is similar to RDbDatabase::Execute().
sl@0: 
sl@0: Note that to begin executing a DDL (SQL schema update) statement incrementally, 
sl@0: use the RDbIncremental class.
sl@0: 
sl@0: @param aDatabase The database on which the DML (SQL data update) statement 
sl@0: is to execute.
sl@0: @param aSql A reference to a descriptor containing the DML statement to be 
sl@0: executed.
sl@0: @param aComparison This argument is only used in the execution of some SQL 
sl@0: statements. By default the comparison is EDbCompareNormal. For more information 
sl@0: see RDbDatabase::Execute().
sl@0: @return KErrNone, if the operation is complete or 1, if the operation requires 
sl@0: further incremental execution or another of the system-wide error codes.
sl@0: @see RDbIncremental
sl@0: @see RDbDatabase::Execute() 
sl@0: 
sl@0: @capability Note For a secure shared database, the caller must satisfy:
sl@0:             - the schema access policy for the database, if the SQL statement is 
sl@0: 			  CREATE/DROP/ALTER; 
sl@0:             - the write access policy for the table in the SQL, if the SQL statement is 
sl@0: 			  INSERT/UPDATE/DELETE; 
sl@0: */
sl@0: EXPORT_C TInt RDbUpdate::Execute(RDbDatabase& aDatabase,const TDesC& aSql,TDbTextComparison aComparison)
sl@0: 	{
sl@0: 	TRAPD(r,iUpdate=ExecuteDMLL(*aDatabase.iDatabase,aSql,aComparison,iRows()));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Releases the resources used by this incremental operation object. If the operation 
sl@0: is not yet complete, then the operation is abandoned and the database is rolled 
sl@0: back to its state before the operation started. */
sl@0: EXPORT_C void RDbUpdate::Close()
sl@0: 	{
sl@0: 	iUpdate.Close();
sl@0: 	}
sl@0: 
sl@0: /** Performs the next step in the incremental execution of the DML (SQL data update) 
sl@0: statement synchronously. The function returns when the step is complete.
sl@0: 
sl@0: Note that if the incremental step fails, then the incremental object should 
sl@0: be closed and the operation abandoned.
sl@0: 
sl@0: @return KErrNone if execution of the DML statement is complete or 1 if another 
sl@0: step in the execution of the DML statement is needed. or another of the system-wide 
sl@0: error codes is returned if the incremental step fails. */
sl@0: EXPORT_C TInt RDbUpdate::Next()
sl@0: 	{
sl@0: 	TRAPD(r,r=iUpdate->NextL(iRows()));
sl@0: 	return r;
sl@0: 	}
sl@0: 
sl@0: /** Performs the next step in the incremental execution of the DML (SQL data update) 
sl@0: statement asynchronously.
sl@0: 
sl@0: The function returns immediately and signals when the step is complete.
sl@0: 
sl@0: This function is most effectively used when the incremental operation is packaged 
sl@0: as an active object.
sl@0: 
sl@0: Note that if the incremental step fails, then the incremental object should 
sl@0: be closed, and the operation abandoned.
sl@0: 
sl@0: @param aStatus The request status used to contain completion information for 
sl@0: the operation. On completion, it contains:KErrNone, if execution of the DML 
sl@0: statement is complete or 1, if another step in the execution of the DML statement 
sl@0: is needed. or another of the system-wide error codes, if the incremental step 
sl@0: fails. */
sl@0: EXPORT_C void RDbUpdate::Next(TRequestStatus& aStatus)
sl@0: 	{
sl@0: 	iUpdate->Next(iRows,aStatus);
sl@0: 	}
sl@0: 
sl@0: /** Returns the number of rows currently affected by the execution of the DML (SQL 
sl@0: data update) statement on the database.
sl@0: 
sl@0: Once execution of the DML statement is complete, the value returned is the 
sl@0: final total number of rows affected.
sl@0: 
sl@0: @return The current/final number of rows affected by the execution of the 
sl@0: DML statement. */
sl@0: EXPORT_C TInt RDbUpdate::RowCount() const
sl@0: 	{
sl@0: 	return CONST_CAST(TPckgBuf<TInt>&,iRows)();
sl@0: 	}
sl@0: 
sl@0: // Class CDbSyncIncremental
sl@0: 
sl@0: //
sl@0: // Implement the asynchronous step in terms of the synchronous form
sl@0: //
sl@0: EXPORT_C void CDbSyncIncremental::Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus)
sl@0: 	{
sl@0: 	TRequestStatus* pStatus=&aStatus;
sl@0: 	TRAPD(r,r=NextL(aStep.operator()()));	// MSVC issue!!! cannot use aStep() directly
sl@0: 	User::RequestComplete(pStatus,r);
sl@0: 	}
sl@0: 
sl@0: // Class CDbAsyncIncremental
sl@0: 
sl@0: //
sl@0: // Implement the synchronous step in terms of the asynchronous form
sl@0: //
sl@0: EXPORT_C TBool CDbAsyncIncremental::NextL(TInt& aStep)
sl@0: 	{
sl@0: 	TRequestStatus status;
sl@0: 	TPckgBuf<TInt> step=aStep;
sl@0: 	Next(step,status);
sl@0: 	User::WaitForRequest(status);
sl@0: 	aStep=step();
sl@0: 	return __LEAVE_IF_ERROR(status.Int());
sl@0: 	}
sl@0: