diff -r 5cc91383ab1e -r 7333d7932ef7 installationservices/swcomponentregistry/inc_private/scrdatabase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/installationservices/swcomponentregistry/inc_private/scrdatabase.h Tue Aug 31 15:21:33 2010 +0300 @@ -0,0 +1,310 @@ +/* +* Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* SCR Data Layer API which performs all interaction with the underlying database. +* +*/ + + +/** + @file + @internalComponent + @released +*/ + +#ifndef SCRSCRDATABASE_H +#define SCRSCRDATABASE_H + +#include +#include + +namespace Usif + { + // Forward declarations + class CDatabaseImplementation; + class CStatementImplementation; + class CStatement; + + NONSHARABLE_CLASS(CDatabase) : public CBase + /** + This class provides the means to connect the SCR database and execute all SQL statements. + It is intended to be used as a singleton instance by the SCR sessions. + */ + { + friend class CStatement; // CStatement class needs to access CheckSqlErrCodeL + public: + /** + Creates a new database object with an handle to the given database file. + + @param aDatabaseFile The database file handle. + @param aJournalNameZ The journal file handle. + @leave KErrNotFound The file opened is not a database file. + @leave KErrUnknown The database file is missing. + @leave KErrCorrupt The database disk image is malformed. + @leave KErrNoMemory An attempt to allocate memory has failed. + @leave KErrInUse The database file is locked by another thread. + @leave KErrAccessDenied Unable to open the database file. Access permission may be denied. + @leave Or other system wide error codes + */ + IMPORT_C static CDatabase* NewL(RFile& aDatabaseFile, RFile& aJournalFile); + + /** + Creates a new database object with an handle to the given database file and leaves + the newly created object on the cleanup stack. + + @param aDatabaseFile The database file handle. + @param aJournalNameZ The journal file handle. + @see CDatabase::NewL + */ + IMPORT_C static CDatabase* NewLC(RFile& aDatabaseFile, RFile& aJournalFile); + + /** + Destructor. The handle to the database file is closed. + */ + IMPORT_C ~CDatabase(); + + /** + Prepares the provided SQL statement for execution and returns + the prepared statement object which can be executed later. + + The SQL statement must contain a single statement and end with semicolon(;). + + @param aStatementStr The satement which will be prepared. + @return A pointer to the statement object which has got a handle to the result rows set. + The returned object is left on the cleanup stack. + @leave KErrNotFound The database file could not be opened for some reason OR the table + or the requested record could not be found OR the database is empty. + @leave KErrCorrupt The database schema has changed. + @leave KErrNoMemory An attempt to allocate memory has failed OR some kind of disk I/O + operation couldn't be performed (probably no space left on the disk) + OR the database is too big (larger than 2GB in size). + @leave KErrInUse A table in the database is locked. + @leave KErrOverflow Too much data(probably more than 1 megabyte in a single row). + @leave KErrCancel The operation in progress has been terminated externally. + @leave KErrNotSupported The library has been used incorrectly, + @leave KErrAbort Abort due to constraint violation. + @leave KErrArgument This error value indicates that there was an error in the SQL + statement that was passed into. Data type mismatch may have been + occurred OR the provided SQL was badly constructed OR contains + more than one statement. + @leave KErrUnknown An internal error in the underlaying database engine occurred. + @leave KErrGeneral An unspecified error ocurred in the database engine. + */ + IMPORT_C CStatement* PrepareStatementLC(const TDesC& aStatementStr); + + /** + @return The row id of the most recent successful insert into the database from this connection. + @leave KErrNotFound If no successful inserts have ever occurred on this database connection. + */ + IMPORT_C TInt LastInsertedIdL(); + + private: + CDatabase(); + void ConstructL(RFile& aDatabaseFile, RFile& aJournalFile); + void CheckSqlErrCodeL(TInt aErr); + + private: + CDatabaseImplementation* iDbImpl; ///< Pointer to the database implementation object. + }; + + + + NONSHARABLE_CLASS(CStatement) : public CBase + /** + An instance of this class is used to execute all types of SQL statements with or without + parameters. + */ + { + friend class CDatabase; // Only CDatabase can construct an object of this class. + public: + IMPORT_C ~CStatement(); + + /** + If the SQL statement being executed returns any data, this function makes + a new row of data ready for processing. The values may be accessed using + the column access functions (@see CStatement::StrColumnL and @see CStatement::IntColumnL). + + When this function is called again to retrieve the next row of data, the previous row data + is not accessible any more. + + If the caller wants to close the statement before retrieving all the rows, it needs to + just destroy the CStatement object. + + @return Returns EFalse if no more rows are available. + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C TBool ProcessNextRowL(); + + /** + Eexecutes the prepared SQL statement. This function is appropriate to execute + SQL statements which do NOT return a result row set (e.g. INSERT and UPDATE). + If the SQL satetement contains parameters, the prepared statement can be bound + and executed many times. + + @param aStatement The satement which will be executed. + @leave Leaves with one of the leave codes given in @see CStatement::PrepareStatementLC. + */ + IMPORT_C void ExecuteStatementL(); + + /** + Sets the parameter given with the index value to the specified 32-bit integer value. + A parameter value can be set: + - immediately after this object has been created + - after a call to @see CStatement::Reset + @param aParameterIndex The index value identifying the parameter; the first parameter + has an index of 1. + @param The 32-bit integer value to be assigned to the parameter. + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C void BindIntL(TInt aParameterIndex, TInt aParameterValue); + + /** + Sets the parameter given with the index value to the specified 64-bit integer value. + A parameter value can be set: + - immediately after this object has been created + - after a call to @see CStatement::Reset + @param aParameterIndex The index value identifying the parameter; the first parameter + has an index of 1. + @param The 64-bit integer value to be assigned to the parameter. + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C void BindInt64L(TInt aParameterIndex, TInt64 aParameterValue); + + /** + Sets the parameter given with the index value to the specified 16-bit descriptor. + A parameter value can be set: + - immediately after this object has been created + - after a call to @see CStatement::Reset + @param aParameterIndex The index value identifying the parameter; the first parameter + has an index of 1. + @param aParameterStr The 16-bit descriptor whose content is to be assigned to the parameter. + @leave KErrArgument If the input string's length is more than 512 characters + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C void BindStrL(TInt aParameterIndex, const TDesC &aParameterStr); + + /** + Sets the parameter given with the index value to the specified 8-bit descriptor. + A parameter value can be set: + - immediately after this object has been created + - after a call to @see CStatement::Reset + @param aParameterIndex The index value identifying the parameter; the first parameter + has an index of 1. + @param aParameterStr The 8-bit descriptor whose content is to be assigned to the parameter. + @leave KErrArgument If the input string's length is more than 512 characters + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C void BindBinaryL(TInt aParameterIndex, const TDesC8 &aParameterStr); + + /** + Sets the parameter given with the index value to the specified 8-bit descriptor. + A parameter value can be set: + - immediately after this object has been created + - after a call to @see CStatement::Reset + + @param aParameterIndex The index value identifying the parameter; the first parameter + has an index of 1. + @param aParameterStr The 8-bit descriptor whose content is to be assigned to the parameter. + @param aCustomLength The maximum characters allowed + + @leave KErrArgument If the input string's length is more than aCustomLength + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C void BindBinaryL(TInt aParameterIndex, const TDesC8 &aParameterStr, TUint aCustomLength); + + /** + Retrieves the value of a string column. The caller must know the string column index. + In addition, the caller must make the copy if they want to process multiple rows at once. + + @param aColIdx The index of the column in the result set. + @return The string value of the column given. + @leave KErrArgument The supplied column index is not valid or its type is not string. + @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C TPtrC StrColumnL(TInt aColIdx) const; + + /** + Retrieves the value of a raw binary data column. The caller must know the column index. + In addition, the caller must make the copy if they want to process multiple rows at once. + + @param aColIdx The index of the column in the result set. + @return The binary value of the column given. + @leave KErrArgument The supplied column index is not valid or its type is not string. + @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C TPtrC8 BinaryColumnL(TInt aColIdx) const; + + /** + Retrieves the value of a integer column. The caller must know the integer column index. + The return value is 64-bit integer. + + @param aColIdx The index of the column in the result set. + @return The integer value of the column given. + @leave KErrArgument The supplied column index is not valid or its type is not integer. + @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C TInt64 Int64ColumnL(TInt aColIdx) const; + + /** + Retrieves the value of an integer column. The caller must know the integer column index. + The return value is 32-bit integer. + + @param aColIdx The index of the column in the result set. + @return The integer value of the column given. + @leave KErrArgument The supplied column index is not valid or its type is not integer. + @leave Or one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C TInt IntColumnL(TInt aColIdx) const; + + /** + Resets this SQL statement object to its initial state and makes it ready to be executed again. + Any SQL statement parameters that had values bound to them, retain their values. + If this object processes a parameterised SQL statement, then the parameter values + can be bound after the call to Reset(). + @leave Leaves with one of the error codes listed in @see CDatabase::PerformStatementLC + */ + IMPORT_C void ResetL(); + + /** + Returns whether the specified field (column) of a row is NULL. + Note that if the field is NULL, it does NOT mean that the corresponding fields of + other rows are NULL as well. + @param aColIdx The index of the column in the result set. + @return ETrue, if the field is NULL, otherwise EFalse. + @leave KErrArgument The supplied column index is not valid. + */ + IMPORT_C TBool IsFieldNullL(TInt aColIdx) const; + + private: + /** + Creates a new CStatement object on the heap. + + @param aDb Refrence to the database object. + @param aStmtImpl Pointer to the statement implementation. The ownership is also passed + to the CStatement object. + @return The newly created CStatement object. + + */ + static CStatement* NewL(const CDatabase& aDb, CStatementImplementation* aStmtImpl); + + CStatement(const CDatabase& aDb, CStatementImplementation* aStmtImpl); + void ValidateRequestedColumnL(TInt aColIdx, TInt& aColumnType) const; + + private: + const CDatabase& iDb; ///< Reference to the database object which creates this statement object. + CStatementImplementation* iStmtImpl; ///< Pointer to the SQL statement implementation + }; + } // namespace Usif + +#endif // SCRSCRDATABASE_H