inc/FIoDatabase.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file        FIoDatabase.h
  19  * @brief       This is the header file for the %Database class.
  20  *
  21  * This header file contains the declarations of the %Database class.
  22  */
  23
  24 #ifndef _FIO_DATABASE_H_
  25 #define _FIO_DATABASE_H_
  26
  27 #include <FBaseObject.h>
  28 #include <FBaseString.h>
  29 #include <FBaseColArrayList.h>
  30 #include <FBaseRtMutex.h>
  31
  32 namespace Tizen { namespace Base
  33 {
  34 class ByteBuffer;
  35 }}
  36
  37 namespace Tizen { namespace Io
  38 {
  39
  40 class DbStatement;
  41 class DbEnumerator;
  42
  43 /**
  44  * @class       Database
  45  * @brief       This class provides the basic database and database entry management methods.
  46  *
  47  * @since       2.0
  48  *
  49  * @final       This class is not intended for extension.
  50  *
  51  * The %Database class provides the basic database and database entry management methods.
  52  * All members of this class are guaranteed to be thread-safe.
  53  *
  54  * For more information on the class features,
  55  * see <a href="../org.tizen.native.appprogramming/html/guide/io/database_operations.htm">Database Operations</a>.
  56  *
  57  * @see Tizen::Io::DbStatement
  58  * @see Tizen::Io::DbEnumerator
  59  *
  60  * The following example demonstrates how to use the %Database class.
  61  *
  62  * @code
  63 #include <FIo.h>
  64 #include <FApp.h>
  65
  66 using namespace Tizen::Io;
  67 using namespace Tizen::App;
  68
  69 result
  70 MyTest::UsingDatabase(void)
  71 {
  72         Database* pDatabase;
  73         DbStatement* pStmt;
  74         DbEnumerator* pEnum;
  75         String dbName;
  76         String sql, sql2, sql3;
  77         String statement;
  78         String stringItem;
  79         result r = E_SUCCESS;
  80
  81         dbName = App::GetInstance()->GetAppDataPath() + L"sample.db");
  82
  83         pDatabase = new Database();
  84         if (!pDatabase)
  85         {
  86                 goto CATCH;
  87         }
  88
  89         r = pDatabase->Construct(dbName, "a+");
  90         if (IsFailed(r))
  91         {
  92                 goto CATCH;
  93         }
  94
  95         AppLog("Create database table:");
  96         sql.Append(L"CREATE TABLE IF NOT EXISTS myTable1 ( column0 INTEGER PRIMARY KEY, column1 DOUBLE, column2 TEXT )");
  97
  98         r = pDatabase->ExecuteSql(sql, true);
  99         if (IsFailed(r))
 100         {
 101                 goto CATCH;
 102         }
 103
 104         AppLog("Insert rows:");
 105         pDatabase->BeginTransaction();
 106
 107         statement.Append(L"INSERT INTO myTable1 (column0, column1, column2) VALUES (?, ?, ?)");
 108         pStmt = pDatabase->CreateStatementN(statement);
 109
 110         stringItem.Append(L"Initial Data");
 111         for (int i = 0; i < 10; i++)
 112         {
 113                 pStmt->BindInt(0, i);
 114                 pStmt->BindDouble(1, i * 0.1);
 115                 pStmt->BindString(2, stringItem);
 116
 117                 pEnum = pDatabase->ExecuteStatementN(*pStmt);
 118                 AppAssert(!pEnum);
 119         }
 120
 121         pDatabase->CommitTransaction();
 122
 123         delete pStmt;
 124
 125         AppLog("Select query using Database::QueryN() wrapper API:");
 126         pEnum = pDatabase->QueryN(L"SELECT * FROM myTable1 WHERE column0 < 5");
 127         if (pEnum)
 128         {
 129                 int nRows = 0;
 130                 int iVal;
 131                 double fVal;
 132                 String strVal;
 133                 while (pEnum->MoveNext() == E_SUCCESS)
 134                 {
 135                         r = pEnum->GetIntAt(0, iVal);
 136                         if (IsFailed(r))
 137                         {
 138                                 goto CATCH;
 139                         }
 140
 141                         r = pEnum->GetDoubleAt(1, fVal);
 142                         if (IsFailed(r))
 143                         {
 144                                 goto CATCH;
 145                         }
 146
 147                         r = pEnum->GetStringAt(2, strVal);
 148                         if (IsFailed(r))
 149                         {
 150                                 goto CATCH;
 151                         }
 152
 153                         AppLog("[%d] column0=%d, column1=%f, column2=%ls", nRows++, iVal, fVal, strVal.GetPointer());
 154                 }
 155         delete pEnum;
 156         }
 157
 158         AppLog("Select query using statement:");
 159         pStmt = pDatabase->CreateStatementN(L"SELECT * FROM myTable1 WHERE column0 > ? AND column0 < ?");
 160         r = GetLastResult();
 161         if (IsFailed(r))
 162         {
 163                 goto CATCH;
 164         }
 165         AppAssert(pStmt);
 166
 167         r = pStmt->BindInt(0, 3);
 168         if (IsFailed(r))
 169         {
 170                 goto CATCH;
 171         }
 172
 173         r = pStmt->BindInt(1, 8);
 174         if (IsFailed(r))
 175         {
 176                 goto CATCH;
 177         }
 178
 179         pEnum = pDatabase->ExecuteStatementN(*pStmt);
 180         r = GetLastResult();
 181         if (IsFailed(r))
 182         {
 183                 goto CATCH;
 184         }
 185
 186         if (pEnum)
 187         {
 188                 int nRows = 0;
 189                 int iVal;
 190                 double fVal;
 191                 String strVal;
 192                 while (pEnum->MoveNext() == E_SUCCESS)
 193                 {
 194                         r = pEnum->GetIntAt(0, iVal);
 195                         if (IsFailed(r))
 196                         {
 197                                 goto CATCH;
 198                         }
 199
 200                         r = pEnum->GetDoubleAt(1, fVal);
 201                         if (IsFailed(r))
 202                         {
 203                                 goto CATCH;
 204                         }
 205
 206                         r = pEnum->GetStringAt(2, strVal);
 207                         if (IsFailed(r))
 208                         {
 209                                 goto CATCH;
 210                         }
 211
 212                         AppLog("[%d] column0=%d, column1=%f, column2=%ls", nRows++, iVal, fVal, strVal.GetPointer());
 213                 }
 214                 delete pEnum;
 215         }
 216
 217         AppLog("Delete rows:");
 218         pDatabase->BeginTransaction();
 219
 220         sql2.Append(L"DELETE FROM myTable1 WHERE column0 = 1");
 221         r = pDatabase->ExecuteSql(sql2, true);
 222
 223         if (r != E_SUCCESS)
 224         {
 225                 goto CATCH;
 226         }
 227
 228         pDatabase->CommitTransaction();
 229
 230         AppLog("Update rows:");
 231         pDatabase->BeginTransaction();
 232
 233         sql3.Append(L"UPDATE myTable1 SET column2 = 'Converted Data' WHERE column2 = 'Initial Data'");
 234         r = pDatabase->ExecuteSql(sql3, true);
 235
 236         if (r != E_SUCCESS)
 237         {
 238                 goto CATCH;
 239         }
 240
 241         pDatabase->CommitTransaction();
 242
 243         // Resource cleanup
 244         delete pDatabase;
 245         pDatabase = null;
 246
 247         r = Database::Delete(dbName);
 248         if (IsFailed(r))
 249         {
 250                 goto CATCH;
 251         }
 252
 253         AppLog("Finished successfully...");
 254         return E_SUCCESS;
 255
 256 CATCH:
 257         if (pDatabase)
 258         {
 259                 delete pDatabase;
 260                 pDatabase = null;
 261         }
 262
 263         if (Database::Exists(dbName))
 264         {
 265                 Database::Delete(dbName);
 266         }
 267
 268         return r;
 269 }
 270  * @endcode
 271  */
 272
 273 class _OSP_EXPORT_ Database
 274         : public Tizen::Base::Object
 275 {
 276
 277 public:
 278         /**
 279         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 280         *
 281         * @since        2.0
 282         */
 283         Database(void);
 284
 285         /**
 286         * This destructor overrides Tizen::Base::Object::~Object().
 287         *
 288         * @since        2.0
 289         */
 290         virtual ~Database(void);
 291
 292         /**
 293         * @{
 294         * @if OSPDEPREC
 295         * Initializes this instance of %Database with the specified parameters. @n
 296         * This method creates a new database file or opens an existing database file in the read-write mode.
 297         *
 298         * @if OSPCOMPAT
 299         * @brief                        <i> [Deprecated] [Compatibility] </i>
 300         * @endif
 301         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 302         *                                       bool createParentDirectories=false) and Database::Construct(const Tizen::Base::String& dbPath, const Tizen::Base::String& openMode).
 303         * @since                        2.0
 304         * @if OSPCOMPAT
 305         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 306         *                                       For more information, see @ref CompIoPathPage "here".
 307         * @endif
 308         *
 309         * @return               An error code
 310         * @param[in]    dbPath                                  The path of the database file to open
 311         * @param[in]    createIfNotExist                Set to @c true to create a database file, @n
 312         *                                                                               else @c false to open an existing database file
 313         * @exception    E_SUCCESS                               The method is successful.
 314         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 315         *                                                                               - The length of the specified @c dbPath is invalid. @n
 316         *                                                                               - The specified @c dbPath is invalid or the path ends with '/'. @n
 317         *                                                                               - The directory name path is missing. @n
 318         *                                                                               - The parent directory does not exist. @n
 319         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 320         * @exception    E_FILE_ALREADY_EXIST    The specified database file already exists. @n
 321         *                                                                               Creation of database file has failed because the destination file already exists. @n
 322         *                                                                               Creation of the database file is attempted if the file does not exist and
 323         *                                                                               the specified @c createIfNotExist is @c true.
 324         *                                                                               However, at this moment another thread has been already created the database file
 325         *                                                                               with the same file path.
 326         *                                                                               This is a rare case, however, it is possible if a race condition is present between several threads.
 327         * @exception    E_FILE_NOT_FOUND                The specified database file cannot be found or accessed.
 328         * @exception    E_DATABASE                              Either of the following conditions has occurred: @n
 329         *                                                                               - The method has failed to open or create a file. @n
 330         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 331         *                                                                               - %File corruption is detected.
 332         * @remarks      To open the database file in the read-only mode,
 333         *                       use the Database::Construct(const Tizen::Base::String& dbPath, const char* pOpenMode) method
 334         *                       with "r" as the value for the open mode flag.
 335         * @endif
 336         * @}
 337         */
 338         result Construct(const Tizen::Base::String& dbPath, bool createIfNotExist);
 339
 340         /**
 341         * @{
 342         * @if OSPDEPREC
 343         * Initializes this instance of %Database with the specified parameters. @n
 344         * This method creates a new database file or opens an existing database file in the read-only or the read-write mode.
 345         *
 346         * @if OSPCOMPAT
 347         * @brief                        <i> [Deprecated] [Compatibility] </i>
 348         * @endif
 349         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 350         *                                       bool createParentDirectories=false) and Database::Construct(const Tizen::Base::String& dbPath, const Tizen::Base::String& openMode).
 351         * @since                        2.0
 352         * @if OSPCOMPAT
 353         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 354         *                                       For more information, see @ref CompIoPathPage "here".
 355         * @endif
 356         *
 357         * @return               An error code
 358         * @param[in]    dbPath                                  The path of the database file to open
 359         * @param[in]    openMode                                An open mode flag @n
 360         *                                                                               Currently, the following flags can be used in combination with the logical OR operator: @n
 361         *                                                                                (1) DB_OPEN_READ_ONLY @n
 362         *                                                                                (2) DB_OPEN_READ_WRITE @n
 363         *                                                                                (3) DB_OPEN_READ_WRITE | DB_OPEN_CREATE
 364         * @param[in]    option                                  This argument is reserved for further use
 365         * @exception    E_SUCCESS                               The method is successful.
 366         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 367         *                                                                               - The length of the specified @c dbPath is invalid. @n
 368         *                                                                               - The specified @c openMode is invalid. @n
 369         *                                                                               - The specified @c dbPath is invalid or the path ends with '/'. @n
 370         *                                                                               - The directory name path is missing. @n
 371         *                                                                               - The parent directory does not exist. @n
 372         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 373         * @exception    E_FILE_ALREADY_EXIST    The specified database file already exists.
 374         * @exception    E_FILE_NOT_FOUND                The specified database file cannot be found or accessed.
 375         * @exception    E_DATABASE                              Either of the following conditions has occurred: @n
 376         *                                                                               - The method has failed to open or create a file. @n
 377         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 378         *                                                                               - %File corruption is detected.
 379         * @endif
 380         * @}
 381         */
 382         result Construct(const Tizen::Base::String& dbPath, long openMode, long option);
 383
 384         /**
 385         * Initializes this instance of %Database with the specified parameters. @n
 386         * This method opens an existing database file or creates a new database file according to the specified file opening mode.
 387         *
 388         * @since                2.0
 389         *
 390         * @return               An error code
 391         * @param[in]    dbPath                          The path of the database file to open or create
 392         * @param[in]    pOpenMode                       The file opening mode @n
 393         *                                                                       It can be one of the following:
 394         *                                                                       - r : Open for reading.
 395         *                                                                       - r+: Open for reading and writing.
 396         *                                                                       - a+: Open for writing and reading. The database file is created if it does not exist.
 397         * @exception    E_SUCCESS                       The method is successful.
 398         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 399         *                                                                       - The overall length of the specified @c dbPath is equal to @c 0 or
 400         *                                                                         exceeds system limitations. @n
 401         *                                                                       - The specified @c dbPath ends with '/'. @n
 402         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 403         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 404         * @exception    E_FILE_NOT_FOUND        The specified @c dbPath cannot be found.
 405         * @exception    E_INVALID_FORMAT        The specified @c dbPath is not a database.
 406         * @exception    E_STORAGE_FULL          The disk space is full.
 407         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 408         * @exception    E_IO                            Either of the following conditions has occurred: @n
 409         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 410         *                                                                       - %File corruption is detected. @n
 411         */
 412         result Construct(const Tizen::Base::String& dbPath, const char* pOpenMode);
 413
 414         /**
 415         * Initializes this instance of %Database with the specified parameters. @n
 416         * This method opens an existing secure database file or creates a new one according to the specified file opening mode.
 417         * The contents written to the secure database file is automatically encrypted and the contents read from the secure database
 418         * file is automatically decrypted by the platform. @n
 419         * Applications using this method can access the same secure database files that are created by other applications with the
 420         * identical key value in same device. However, the secure files created by this method cannot be accessed in other devices.
 421         *
 422         * @since                2.0
 423         * @feature              %http://tizen.org/feature/database.encryption
 424         *
 425         * @return               An error code
 426         * @param[in]    dbPath                                  The path of the database file to open or create
 427         * @param[in]    pOpenMode                               The file opening mode @n
 428         *                                                                               It can be one of the following: @n
 429         *                                                                               - r : Open for reading @n
 430         *                                                                               - r+: Open for reading and writing @n
 431         *                                                                               - a+: Open for writing and reading. The database file is created if it does not exist. @n
 432         * @param[in]    secretKey                               A key used to encrypt data of a database file or decrypt a secure database file @n
 433         *                                                                               If a secure database file is created with a specific key value,
 434         *                                                                               other applications can access the same secure database file with the identical key value.
 435         * @exception    E_SUCCESS                               The method is successful.
 436         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 437         *                                                                               - The overall length of the specified @c dbPath is equal to @c 0 or
 438         *                                                                                 exceeds system limitations. @n
 439         *                                                                               - The specified @c dbPath ends with '/'. @n
 440         *                                                                               - The combination of the specified @c pOpenMode is not allowed. @n
 441         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 442         * @exception    E_FILE_NOT_FOUND                The specified @c dbPath cannot be found.
 443         * @exception    E_INVALID_FORMAT                The specified @c dbPath is not a database.
 444         * @exception    E_STORAGE_FULL                  The disk space is full.
 445         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
 446         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 447         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 448         *                                                                               - %File corruption is detected. @n
 449         * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. For more information, see
 450         *                                                                               <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 451         * @remarks              Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 452         */
 453         result Construct(const Tizen::Base::String& dbPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
 454
 455         /**
 456         * Creates a SQL statement for the current database.
 457         *
 458         * @if OSPCOMPAT
 459         * @brief                        <i> [Compatibility] </i>
 460         * @endif
 461         * @since                        2.0
 462         * @if OSPCOMPAT
 463         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 464         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 465         * @endif
 466         *
 467         * @return               A pointer to the DbStatement instance, @n
 468         *               else @c null if an exception occurs
 469         * @param[in]    sqlStatement            The SQL statement to compile
 470         * @exception    E_SUCCESS                       The method is successful.
 471         * @exception    E_INVALID_ARG           The specified @c sqlStatement is invalid SQL.
 472         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 473         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 474         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 475         * @see                  ExecuteStatementN()
 476         */
 477         DbStatement* CreateStatementN(const Tizen::Base::String& sqlStatement);
 478
 479         /**
 480         * Executes a statement in the calling %Database instance. @n
 481         * If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
 482         * const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey),
 483         * the data set written by INSERT/UPDATE is automatically encrypted by the Tizen platform and
 484         * the data set read by SELECT is also decrypted by itself.
 485         *
 486         * @if OSPCOMPAT
 487         * @brief                        <i> [Compatibility] </i>
 488         * @endif
 489         * @since                        2.0
 490         * @if OSPCOMPAT
 491         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 492         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 493         * @endif
 494         *
 495         * @return               A pointer to the DbEnumerator instance, @n
 496         *                               else @c null if an exception occurs, if no result set is generated after the successful execution of the
 497         *                               SELECT query, or if one of INSERT, UPDATE, and DELETE queries is executed.
 498         * @param[in]    dbStatement                     The DbStatement instance to execute
 499         * @exception    E_SUCCESS                       The method is successful.
 500         * @exception    E_INVALID_ARG           The specified @c dbStatement includes invalid SQL.
 501         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 502         * @exception    E_INVALID_FORMAT        The database file is malformed.
 503         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 504         * @exception    E_IO                            Either of the following conditions has occurred: @n
 505         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 506         *                                                                       - %File corruption is detected.
 507         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 508         * @remarks              If @c dbStatement contains the SELECT query, the Reset() method of the DbEnumerator instance returned
 509         *                               from this method should be called. The Reset() method should be called before re-binding the dbStatement
 510         *                               with the bind methods of the DbStatement class.
 511         *                               This method returns an enumerator if the result set is generated by the SELECT query.
 512         *                               @c null is returned if no result set is available after the successful execution of the SELECT query.
 513         *                               Note that, a return value of @c null does not mean that the statement execution has failed.
 514         *                               The enumerator returned by the SELECT query does not indicate any row before it calls DbEnumerator::MoveNext().
 515         *                               The specific error code can be accessed using the GetLastResult() method.
 516         */
 517         DbEnumerator* ExecuteStatementN(const DbStatement& dbStatement);
 518
 519         /**
 520         * Executes SQL statement in this %Database instance. @n
 521         * Any SQL statement that does not give a result set can be run using this method; for example, CREATE, INSERT, UPDATE, DELETE.
 522         * The SELECT query cannot be executed using this method. @n
 523         * If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
 524         * const char* pOpenMode, const Tizen::Base::ByteBuffer& key),
 525         * the data set written by INSERT/UPDATE is automatically encrypted by the Tizen platform.
 526         *
 527         * @if OSPCOMPAT
 528         * @brief                        <i> [Compatibility] </i>
 529         * @endif
 530         * @since                        2.0
 531         * @if OSPCOMPAT
 532         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 533         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 534         * @endif
 535         *
 536         * @return               An error code
 537         * @param[in]    sqlStatement            The SQL statement to execute
 538         * @param[in]    option                  This argument is reserved for further use.
 539         * @exception    E_SUCCESS                       The method is successful.
 540         * @exception    E_INVALID_ARG           The specified @c sqlStatement is invalid SQL.
 541         * @exception    E_INVALID_OPERATION     The specified @c sqlStatement is a SELECT query.
 542         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 543         * @exception    E_INVALID_FORMAT        The database file is malformed.
 544         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 545         * @exception    E_IO                            Either of the following conditions has occurred: @n
 546         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 547         *                                                                       - %File corruption is detected.
 548         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 549         * @remarks              Use QueryN() to execute SELECT query.
 550         * @see                  QueryN()
 551         */
 552         result ExecuteSql(const Tizen::Base::String& sqlStatement, bool option);
 553
 554         /**
 555         * Executes a SELECT query in the calling %Database instance. @n
 556         * If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
 557         * const char* pOpenMode, const Tizen::Base::ByteBuffer& key),
 558         * the data set read by SELECT is automatically decrypted by the Tizen platform.
 559         *
 560         * @if OSPCOMPAT
 561         * @brief                        <i> [Compatibility] </i>
 562         * @endif
 563         * @since                        2.0
 564         * @if OSPCOMPAT
 565         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 566         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 567         * @endif
 568         *
 569         * @return               A pointer to the %DbEnumerator instance, @n
 570         *                               else @c null if an exception occurs or if no result set is generated after the successful execution of the SELECT query
 571         * @param[in]    sqlStatement            The SQL statement to execute
 572         * @exception    E_SUCCESS                       The method is successful.
 573         * @exception    E_INVALID_ARG           The specified @c sqlStatement is invalid SQL.
 574         * @exception    E_INVALID_OPERATION     The specified @c sqlStatement is not a SELECT query.
 575         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 576         * @exception    E_INVALID_FORMAT        The database file is malformed.
 577         * @exception    E_IO                            Either of the following conditions has occurred: @n
 578         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 579         *                                                                       - %File corruption is detected.
 580         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 581         * @remarks              This method returns an enumerator if the result set is generated by the SELECT query.
 582         *                               @c null is returned if no result set is available after the successful execution of the SELECT query.
 583         *                               Note that, a return value of @c null does not mean that the statement execution has failed.
 584         *                               The enumerator returned by the SELECT query does not indicate any row before it calls
 585         *                               DbEnumerator::MoveNext().
 586         *                               The specific error code can be accessed using the GetLastResult() method.
 587         * @see          ExecuteSql()
 588         */
 589         DbEnumerator* QueryN(const Tizen::Base::String& sqlStatement);
 590
 591         /**
 592         * Begins a transaction within this %Database instance.
 593         *
 594         * @if OSPCOMPAT
 595         * @brief                        <i> [Compatibility] </i>
 596         * @endif
 597         * @since                        2.0
 598         * @if OSPCOMPAT
 599         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 600         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 601         * @endif
 602         *
 603         * @return               An error code
 604         * @exception    E_SUCCESS                       The method is successful.
 605         * @exception    E_INVALID_STATE         The transaction has already begun.
 606         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 607         * @see                  CommitTransaction()
 608     * @see              RollbackTransaction()
 609         */
 610         result BeginTransaction(void);
 611
 612         /**
 613         * Commits a transaction within this %Database instance.
 614         *
 615         * @if OSPCOMPAT
 616         * @brief                        <i> [Compatibility] </i>
 617         * @endif
 618         * @since                        2.0
 619         * @if OSPCOMPAT
 620         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 621         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 622         * @endif
 623         *
 624         * @return               An error code
 625         * @exception    E_SUCCESS                       The method is successful.
 626         * @exception    E_INVALID_STATE         The transaction mode is not activated.
 627         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 628         * @exception    E_INVALID_FORMAT        The database file is malformed.
 629         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 630         * @exception    E_IO                            Either of the following conditions has occurred: @n
 631         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 632         *                                                                       - %File corruption is detected.
 633         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 634         * @remarks              Database::CommitTransaction() automatically resets not only all the DbStatement instances
 635         *                               but also all the DbEnumerator instances obtained from the current %Database instance.
 636         *                               As a result, the prepared statement of the %DbStatement instances are reset to its initial state, ready to be re-executed,
 637         *                               and enumerator of the %DbEnumerator instances are reset to the first position.
 638         *                               Therefore, the user should be careful when the same instance of the %Database class is shared across multiple threads.
 639         *                               Further, access to the %DbStatement or %DbEnumerator instances resets due to commit operation. This will eventually lead to crash.
 640         *                               To avoid a crash, the user can use multiple database instances for each thread.
 641         *                               Sharing of the same database instance across multiple threads is not recommended.
 642         * @see                  BeginTransaction()
 643         * @see                  RollbackTransaction()
 644         */
 645         result CommitTransaction(void);
 646
 647         /**
 648         * Aborts a running transaction within this %Database instance.
 649         *
 650         * @if OSPCOMPAT
 651         * @brief                        <i> [Compatibility] </i>
 652         * @endif
 653         * @since                        2.0
 654         * @if OSPCOMPAT
 655         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 656         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 657         * @endif
 658         *
 659         * @return               An error code
 660         * @exception    E_SUCCESS                       The method is successful.
 661         * @exception    E_INVALID_STATE         The transaction mode is not activated.
 662         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 663         * @exception    E_INVALID_FORMAT        The database file is malformed.
 664         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 665         * @exception    E_IO                            Either of the following conditions has occurred: @n
 666         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 667         *                                                                       - %File corruption is detected.
 668         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 669         * @see                  BeginTransaction()
 670     * @see              CommitTransaction()
 671         */
 672         result RollbackTransaction(void);
 673
 674         /**
 675         * Gets the database's filename.
 676         *
 677         * @since                2.0
 678         *
 679         * @return               The filename of this %Database instance
 680         */
 681         Tizen::Base::String GetName(void) const;
 682
 683         /**
 684         * Deletes the database file with the specified file name.
 685         *
 686         * @if OSPCOMPAT
 687         * @brief <i> [Compatibility] </i>
 688         * @endif
 689         * @since                2.0
 690         * @if OSPCOMPAT
 691         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 692         *                                       For more information, see @ref CompIoPathPage "here".
 693         * @endif
 694         *
 695         * @return               An error code
 696         * @param[in]    databasePath            The path of the database file to delete
 697         * @exception    E_SUCCESS                       The method is successful.
 698         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 699         *                                                                       - The length of the specified @c databasePath is invalid. @n
 700         *                                                                       - The specified @c databasePath parameter contains an invalid path or
 701         *                                                                         the path ends with '/'. @n
 702         *                                                                       - The directory name path is missing. @n
 703         *                                                                       - The parent directory does not exist. @n
 704         *                                                                       - An I/O security issue.
 705         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 706         * @exception    E_FILE_NOT_FOUND        The specified database file cannot be found.
 707         * @exception    E_IO                            Either of the following conditions has occurred: @n
 708         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 709         *                                                                       - %File corruption is detected. @n
 710         *                                                                       - A system error has occurred.
 711         */
 712         static result Delete(const Tizen::Base::String& databasePath);
 713
 714         /**
 715         * Checks whether the database file exists.
 716         *
 717         * @if OSPCOMPAT
 718         * @brief <i> [Compatibility] </i>
 719         * @endif
 720         * @since                2.0
 721         * @if OSPCOMPAT
 722         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 723         *                                       For more information, see @ref CompIoPathPage "here".
 724         * @endif
 725         *
 726         * @return               @c true if the database file exists, @n
 727         *                               else @c false
 728         * @param[in]    databasePath            The path of the database file to check
 729         * @exception    E_SUCCESS                       The method is successful.
 730         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 731         *                                                                       - The length of the specified @c databasePath is invalid. @n
 732         *                                                                       - The specified @c databasePath parameter contains an invalid path or
 733         *                                                                         the path ends with '/'. @n
 734         *                                                                       - The directory name path is missing. @n
 735         *                                                                       - The parent directory does not exist. @n
 736         *                                                                       - An I/O security issue.
 737         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 738         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 739         */
 740         static bool Exists(const Tizen::Base::String& databasePath);
 741
 742         /**
 743         * Converts a normal database file to a secure database file. @n
 744         * A secure database file, that is converted by this method, can be shared among applications with the same key value.
 745         *
 746         * @if OSPCOMPAT
 747         * @brief                        <i> [Compatibility] </i>
 748         * @endif
 749         * @since                        2.0
 750         * @if OSPCOMPAT
 751         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 752         *                                       For path compatibility, see @ref CompIoPathPage "here".
 753         *                                       For exception compatibility, see @ref CompDatabaseExceptionPage "here".
 754         * @endif
 755         * @feature                      %http://tizen.org/feature/database.encryption
 756         *
 757         * @return               An error code
 758         * @param[in]    normalDbPath                    The normal (non-encrypted) database file path
 759         * @param[in]    secureDbPath                    The secure (encrypted) database file path to create
 760         * @param[in]    secretKey                               A key to encrypt normal database file @n
 761         *                                                                               If the normal database file is converted with a specific key value,
 762         *                                                                               applications can access the same secure database file with the identical key value.
 763         * @exception    E_SUCCESS                               The method is successful.
 764         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 765         *                                                                               - The length of the specified path is @c 0 or exceeds system limitations. @n
 766         *                                                                               - The specified path is invalid. @n
 767         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 768         * @exception    E_FILE_NOT_FOUND                The specified @c normalDbPath does not exist.
 769         * @exception    E_FILE_ALREADY_EXIST    The specified @c secureDbPath already exists.
 770         * @exception    E_OBJECT_LOCKED                 The database instance is locked.
 771         * @exception    E_INVALID_FORMAlT               The database file is malformed.
 772         * @exception    E_STORAGE_FULL                  The disk space or database image is full.
 773         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 774         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 775         *                                                                               - %File corruption is detected.
 776         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
 777         * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. For more information, see
 778         *                                                                               <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 779         * @remarks              Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 780         */
 781         static result ConvertToSecureDatabase(const Tizen::Base::String& normalDbPath, const Tizen::Base::String& secureDbPath,
 782                         const Tizen::Base::ByteBuffer& secretKey);
 783
 784         /**
 785         * Gets the last inserted row ID.
 786         *
 787         * @since                2.0
 788         *
 789         * @return               Row ID of the most recent successful insert, @n
 790         *                               else @c -1 if no successful INSERT operations have ever occurred on
 791         *                               the current opened database.
 792         * @remarks              The row ID is always available as an undeclared column named ROWID, OID, or _ROWID_
 793         *                               as long as those names are not also used by explicitly declared columns.
 794         *                               If the table has a column of type INTEGER PRIMARY KEY then that column is another alias
 795         *                               for the row ID. @n
 796         *                               This method returns the row ID of the most recent successful INSERT operation
 797         *                               for current %Database.
 798         */
 799         long long GetLastInsertRowId(void) const;
 800
 801         /**
 802         * @if OSPCOMPAT
 803         * @page         CompDatabaseExceptionPage Compatibility for E_DATABASE exception
 804         * @section      CompDatabaseExceptionPageIssueSection Issues
 805         *                       Implementing this method in OSP compatible applications has the following issues: @n
 806         *
 807         * -# E_DATABASE exception includes many errors from underlying database engine.
 808         * -# If database is locked, E_SERVICE_BUSY is returned.
 809         *
 810         * @section      CompDatabaseExceptionPageSolutionSection Resolutions
 811         *                       The issue mentioned above is resolved in Tizen. @n
 812         *
 813         * @par          When working in Tizen:
 814         * -# E_DATABASE exception is divided into several exceptions. Refer to exception description of API reference.
 815         * -# E_SERVICE_BUSY is changed to E_OBJECT_LOCKED.
 816         *
 817         * @endif
 818         */
 819
 820 private:
 821         /**
 822         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 823         *
 824         * @since        2.0
 825         */
 826         Database(const Database& rhs);
 827
 828         /**
 829         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 830         * @since        2.0
 831         */
 832         Database& operator =(const Database& rhs);
 833
 834         /**
 835         * The implementation of this method is intentionally blank and declared as private to prohibit implicit conversion.
 836         *
 837         * @since        2.0
 838         */
 839         result Construct(const Tizen::Base::String& dbPath, const wchar_t* pOpenMode);
 840
 841         class _DatabaseImpl* __pDatabaseImpl;
 842
 843         friend class _DatabaseImpl;
 844
 845 }; // Database
 846
 847 }} // Tizen::Io
 848
 849 #endif //_FIO_DATABASE_H_
 850