--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/installationservices/swcomponentregistry/inc_private/scrdatabase.h Fri Mar 19 09:33:35 2010 +0200
@@ -0,0 +1,294 @@
+/*
+* 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 <e32base.h>
+#include <f32file.h>
+
+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);
+
+ /**
+ 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