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         * @cond OSPDEPREC
 294         * Initializes this instance of %Database with the specified parameters. @n
 295         * This method creates a new database file or opens an existing database file in the read-write mode.
 296         *
 297         * @if OSPCOMPAT
 298         * @brief                        <i> [Deprecated] [Compatibility] </i>
 299         * @endif
 300         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 301         *                                       bool createParentDirectories=false) and Database::Construct(const Tizen::Base::String& dbPath, const Tizen::Base::String& openMode).
 302         * @since                        2.0
 303         * @if OSPCOMPAT
 304         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 305         *                                       For more information, see @ref CompIoPathPage "here".
 306         * @endif
 307         *
 308         * @return               An error code
 309         * @param[in]    dbPath                                  The path of the database file to open
 310         * @param[in]    createIfNotExist                Set to @c true to create a database file, @n
 311         *                                                                               else @c false to open an existing database file
 312         * @exception    E_SUCCESS                               The method is successful.
 313         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 314         *                                                                               - The length of the specified @c dbPath is invalid. @n
 315         *                                                                               - The specified @c dbPath is invalid or the path ends with '/'. @n
 316         *                                                                               - The directory name path is missing. @n
 317         *                                                                               - The parent directory does not exist. @n
 318         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 319         * @exception    E_FILE_ALREADY_EXIST    The specified database file already exists. @n
 320         *                                                                               Creation of database file has failed because the destination file already exists. @n
 321         *                                                                               Creation of the database file is attempted if the file does not exist and
 322         *                                                                               the specified @c createIfNotExist is @c true.
 323         *                                                                               However, at this moment another thread has been already created the database file
 324         *                                                                               with the same file path.
 325         *                                                                               This is a rare case, however, it is possible if a race condition is present between several threads.
 326         * @exception    E_FILE_NOT_FOUND                The specified database file cannot be found or accessed.
 327         * @exception    E_DATABASE                              Either of the following conditions has occurred: @n
 328         *                                                                               - The method has failed to open or create a file. @n
 329         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 330         *                                                                               - %File corruption is detected.
 331         * @remarks      To open the database file in the read-only mode,
 332         *                       use the Database::Construct(const Tizen::Base::String& dbPath, const char* pOpenMode) method
 333         *                       with "r" as the value for the open mode flag.
 334         * @endcond
 335         */
 336         result Construct(const Tizen::Base::String& dbPath, bool createIfNotExist);
 337
 338         /**
 339         * @cond OSPDEPREC
 340         * Initializes this instance of %Database with the specified parameters. @n
 341         * This method creates a new database file or opens an existing database file in the read-only or the read-write mode.
 342         *
 343         * @if OSPCOMPAT
 344         * @brief                        <i> [Deprecated] [Compatibility] </i>
 345         * @endif
 346         * @deprecated           This method is deprecated. Instead of using this method, use Directory::Create(const Tizen::Base::String &dirPath,
 347         *                                       bool createParentDirectories=false) and Database::Construct(const Tizen::Base::String& dbPath, const Tizen::Base::String& openMode).
 348         * @since                        2.0
 349         * @if OSPCOMPAT
 350         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 351         *                                       For more information, see @ref CompIoPathPage "here".
 352         * @endif
 353         *
 354         * @return               An error code
 355         * @param[in]    dbPath                                  The path of the database file to open
 356         * @param[in]    openMode                                An open mode flag @n
 357         *                                                                               Currently, the following flags can be used in combination with the logical OR operator: @n
 358         *                                                                                (1) DB_OPEN_READ_ONLY @n
 359         *                                                                                (2) DB_OPEN_READ_WRITE @n
 360         *                                                                                (3) DB_OPEN_READ_WRITE | DB_OPEN_CREATE
 361         * @param[in]    option                                  This argument is reserved for further use
 362         * @exception    E_SUCCESS                               The method is successful.
 363         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 364         *                                                                               - The length of the specified @c dbPath is invalid. @n
 365         *                                                                               - The specified @c openMode is invalid. @n
 366         *                                                                               - The specified @c dbPath is invalid or the path ends with '/'. @n
 367         *                                                                               - The directory name path is missing. @n
 368         *                                                                               - The parent directory does not exist. @n
 369         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 370         * @exception    E_FILE_ALREADY_EXIST    The specified database file already exists.
 371         * @exception    E_FILE_NOT_FOUND                The specified database file cannot be found or accessed.
 372         * @exception    E_DATABASE                              Either of the following conditions has occurred: @n
 373         *                                                                               - The method has failed to open or create a file. @n
 374         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 375         *                                                                               - %File corruption is detected.
 376         * @endcond
 377         */
 378         result Construct(const Tizen::Base::String& dbPath, long openMode, long option);
 379
 380         /**
 381         * Initializes this instance of %Database with the specified parameters. @n
 382         * This method opens an existing database file or creates a new database file according to the specified file opening mode.
 383         *
 384         * @since                2.0
 385         *
 386         * @return               An error code
 387         * @param[in]    dbPath                          The path of the database file to open or create
 388         * @param[in]    pOpenMode                       The file opening mode @n
 389         *                                                                       It can be one of the following:
 390         *                                                                       - r : Open for reading.
 391         *                                                                       - r+: Open for reading and writing.
 392         *                                                                       - a+: Open for writing and reading. The database file is created if it does not exist.
 393         * @exception    E_SUCCESS                       The method is successful.
 394         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 395         *                                                                       - The overall length of the specified @c dbPath is equal to @c 0 or
 396         *                                                                         exceeds system limitations. @n
 397         *                                                                       - The specified @c dbPath ends with '/'. @n
 398         *                                                                       - The combination of the specified @c pOpenMode is not allowed. @n
 399         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 400         * @exception    E_FILE_NOT_FOUND        The specified @c dbPath cannot be found.
 401         * @exception    E_INVALID_FORMAT        The specified @c dbPath is not a database.
 402         * @exception    E_STORAGE_FULL          The disk space is full.
 403         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 404         * @exception    E_IO                            Either of the following conditions has occurred: @n
 405         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 406         *                                                                       - %File corruption is detected. @n
 407         */
 408         result Construct(const Tizen::Base::String& dbPath, const char* pOpenMode);
 409
 410         /**
 411         * Initializes this instance of %Database with the specified parameters. @n
 412         * This method opens an existing secure database file or creates a new one according to the specified file opening mode.
 413         * The contents written to the secure database file is automatically encrypted and the contents read from the secure database
 414         * file is automatically decrypted by the platform. @n
 415         * Applications using this method can access the same secure database files that are created by other applications with the
 416         * identical key value in same device. However, the secure files created by this method cannot be accessed in other devices.
 417         *
 418         * @since                2.0
 419         * @feature              %http://tizen.org/feature/database.encryption
 420         *
 421         * @return               An error code
 422         * @param[in]    dbPath                                  The path of the database file to open or create
 423         * @param[in]    pOpenMode                               The file opening mode @n
 424         *                                                                               It can be one of the following: @n
 425         *                                                                               - r : Open for reading @n
 426         *                                                                               - r+: Open for reading and writing @n
 427         *                                                                               - a+: Open for writing and reading. The database file is created if it does not exist. @n
 428         * @param[in]    secretKey                               A key used to encrypt data of a database file or decrypt a secure database file @n
 429         *                                                                               If a secure database file is created with a specific key value,
 430         *                                                                               other applications can access the same secure database file with the identical key value.
 431         * @exception    E_SUCCESS                               The method is successful.
 432         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 433         *                                                                               - The overall length of the specified @c dbPath is equal to @c 0 or
 434         *                                                                                 exceeds system limitations. @n
 435         *                                                                               - The specified @c dbPath ends with '/'. @n
 436         *                                                                               - The combination of the specified @c pOpenMode is not allowed. @n
 437         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 438         * @exception    E_FILE_NOT_FOUND                The specified @c dbPath cannot be found.
 439         * @exception    E_INVALID_FORMAT                The specified @c dbPath is not a database.
 440         * @exception    E_STORAGE_FULL                  The disk space is full.
 441         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
 442         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 443         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 444         *                                                                               - %File corruption is detected. @n
 445         * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. For more information, see
 446         *                                                                               <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 447         * @remarks              Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 448         */
 449         result Construct(const Tizen::Base::String& dbPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
 450
 451         /**
 452         * Creates a SQL statement for the current database.
 453         *
 454         * @if OSPCOMPAT
 455         * @brief                        <i> [Compatibility] </i>
 456         * @endif
 457         * @since                        2.0
 458         * @if OSPCOMPAT
 459         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 460         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 461         * @endif
 462         *
 463         * @return               A pointer to the DbStatement instance, @n
 464         *               else @c null if an exception occurs
 465         * @param[in]    sqlStatement            The SQL statement to compile
 466         * @exception    E_SUCCESS                       The method is successful.
 467         * @exception    E_INVALID_ARG           The specified @c sqlStatement is invalid SQL.
 468         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 469         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 470         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 471         * @see                  ExecuteStatementN()
 472         */
 473         DbStatement* CreateStatementN(const Tizen::Base::String& sqlStatement);
 474
 475         /**
 476         * Executes a statement in the calling %Database instance. @n
 477         * If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
 478         * const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey),
 479         * the data set written by INSERT/UPDATE is automatically encrypted by the Tizen platform and
 480         * the data set read by SELECT is also decrypted by itself.
 481         *
 482         * @if OSPCOMPAT
 483         * @brief                        <i> [Compatibility] </i>
 484         * @endif
 485         * @since                        2.0
 486         * @if OSPCOMPAT
 487         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 488         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 489         * @endif
 490         *
 491         * @return               A pointer to the DbEnumerator instance, @n
 492         *                               else @c null if an exception occurs, if no result set is generated after the successful execution of the
 493         *                               SELECT query, or if one of INSERT, UPDATE, and DELETE queries is executed.
 494         * @param[in]    dbStatement                     The DbStatement instance to execute
 495         * @exception    E_SUCCESS                       The method is successful.
 496         * @exception    E_INVALID_ARG           The specified @c dbStatement includes invalid SQL.
 497         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 498         * @exception    E_INVALID_FORMAT        The database file is malformed.
 499         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 500         * @exception    E_IO                            Either of the following conditions has occurred: @n
 501         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 502         *                                                                       - %File corruption is detected.
 503         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 504         * @remarks              If @c dbStatement contains the SELECT query, the Reset() method of the DbEnumerator instance returned
 505         *                               from this method should be called. The Reset() method should be called before re-binding the dbStatement
 506         *                               with the bind methods of the DbStatement class.
 507         *                               This method returns an enumerator if the result set is generated by the SELECT query.
 508         *                               @c null is returned if no result set is available after the successful execution of the SELECT query.
 509         *                               Note that, a return value of @c null does not mean that the statement execution has failed.
 510         *                               The enumerator returned by the SELECT query does not indicate any row before it calls DbEnumerator::MoveNext().
 511         *                               The specific error code can be accessed using the GetLastResult() method.
 512         */
 513         DbEnumerator* ExecuteStatementN(const DbStatement& dbStatement);
 514
 515         /**
 516         * Executes SQL statement in this %Database instance. @n
 517         * Any SQL statement that does not give a result set can be run using this method; for example, CREATE, INSERT, UPDATE, DELETE.
 518         * The SELECT query cannot be executed using this method. @n
 519         * If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
 520         * const char* pOpenMode, const Tizen::Base::ByteBuffer& key),
 521         * the data set written by INSERT/UPDATE is automatically encrypted by the Tizen platform.
 522         *
 523         * @if OSPCOMPAT
 524         * @brief                        <i> [Compatibility] </i>
 525         * @endif
 526         * @since                        2.0
 527         * @if OSPCOMPAT
 528         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 529         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 530         * @endif
 531         *
 532         * @return               An error code
 533         * @param[in]    sqlStatement            The SQL statement to execute
 534         * @param[in]    option                  This argument is reserved for further use.
 535         * @exception    E_SUCCESS                       The method is successful.
 536         * @exception    E_INVALID_ARG           The specified @c sqlStatement is invalid SQL.
 537         * @exception    E_INVALID_OPERATION     The specified @c sqlStatement is a SELECT query.
 538         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 539         * @exception    E_INVALID_FORMAT        The database file is malformed.
 540         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 541         * @exception    E_IO                            Either of the following conditions has occurred: @n
 542         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 543         *                                                                       - %File corruption is detected.
 544         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 545         * @remarks              Use QueryN() to execute SELECT query.
 546         * @see                  QueryN()
 547         */
 548         result ExecuteSql(const Tizen::Base::String& sqlStatement, bool option);
 549
 550         /**
 551         * Executes a SELECT query in the calling %Database instance. @n
 552         * If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
 553         * const char* pOpenMode, const Tizen::Base::ByteBuffer& key),
 554         * the data set read by SELECT is automatically decrypted by the Tizen platform.
 555         *
 556         * @if OSPCOMPAT
 557         * @brief                        <i> [Compatibility] </i>
 558         * @endif
 559         * @since                        2.0
 560         * @if OSPCOMPAT
 561         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 562         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 563         * @endif
 564         *
 565         * @return               A pointer to the %DbEnumerator instance, @n
 566         *                               else @c null if an exception occurs or if no result set is generated after the successful execution of the SELECT query
 567         * @param[in]    sqlStatement            The SQL statement to execute
 568         * @exception    E_SUCCESS                       The method is successful.
 569         * @exception    E_INVALID_ARG           The specified @c sqlStatement is invalid SQL.
 570         * @exception    E_INVALID_OPERATION     The specified @c sqlStatement is not a SELECT query.
 571         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 572         * @exception    E_INVALID_FORMAT        The database file is malformed.
 573         * @exception    E_IO                            Either of the following conditions has occurred: @n
 574         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 575         *                                                                       - %File corruption is detected.
 576         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 577         * @remarks              This method returns an enumerator if the result set is generated by the SELECT query.
 578         *                               @c null is returned if no result set is available after the successful execution of the SELECT query.
 579         *                               Note that, a return value of @c null does not mean that the statement execution has failed.
 580         *                               The enumerator returned by the SELECT query does not indicate any row before it calls
 581         *                               DbEnumerator::MoveNext().
 582         *                               The specific error code can be accessed using the GetLastResult() method.
 583         * @see          ExecuteSql()
 584         */
 585         DbEnumerator* QueryN(const Tizen::Base::String& sqlStatement);
 586
 587         /**
 588         * Begins a transaction within this %Database instance.
 589         *
 590         * @if OSPCOMPAT
 591         * @brief                        <i> [Compatibility] </i>
 592         * @endif
 593         * @since                        2.0
 594         * @if OSPCOMPAT
 595         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 596         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 597         * @endif
 598         *
 599         * @return               An error code
 600         * @exception    E_SUCCESS                       The method is successful.
 601         * @exception    E_INVALID_STATE         The transaction has already begun.
 602         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 603         * @see                  CommitTransaction()
 604     * @see              RollbackTransaction()
 605         */
 606         result BeginTransaction(void);
 607
 608         /**
 609         * Commits a transaction within this %Database instance.
 610         *
 611         * @if OSPCOMPAT
 612         * @brief                        <i> [Compatibility] </i>
 613         * @endif
 614         * @since                        2.0
 615         * @if OSPCOMPAT
 616         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 617         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 618         * @endif
 619         *
 620         * @return               An error code
 621         * @exception    E_SUCCESS                       The method is successful.
 622         * @exception    E_INVALID_STATE         The transaction mode is not activated.
 623         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 624         * @exception    E_INVALID_FORMAT        The database file is malformed.
 625         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 626         * @exception    E_IO                            Either of the following conditions has occurred: @n
 627         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 628         *                                                                       - %File corruption is detected.
 629         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 630         * @remarks              Database::CommitTransaction() automatically resets not only all the DbStatement instances
 631         *                               but also all the DbEnumerator instances obtained from the current %Database instance.
 632         *                               As a result, the prepared statement of the %DbStatement instances are reset to its initial state, ready to be re-executed,
 633         *                               and enumerator of the %DbEnumerator instances are reset to the first position.
 634         *                               Therefore, the user should be careful when the same instance of the %Database class is shared across multiple threads.
 635         *                               Further, access to the %DbStatement or %DbEnumerator instances resets due to commit operation. This will eventually lead to crash.
 636         *                               To avoid a crash, the user can use multiple database instances for each thread.
 637         *                               Sharing of the same database instance across multiple threads is not recommended.
 638         * @see                  BeginTransaction()
 639         * @see                  RollbackTransaction()
 640         */
 641         result CommitTransaction(void);
 642
 643         /**
 644         * Aborts a running transaction within this %Database instance.
 645         *
 646         * @if OSPCOMPAT
 647         * @brief                        <i> [Compatibility] </i>
 648         * @endif
 649         * @since                        2.0
 650         * @if OSPCOMPAT
 651         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 652         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 653         * @endif
 654         *
 655         * @return               An error code
 656         * @exception    E_SUCCESS                       The method is successful.
 657         * @exception    E_INVALID_STATE         The transaction mode is not activated.
 658         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 659         * @exception    E_INVALID_FORMAT        The database file is malformed.
 660         * @exception    E_STORAGE_FULL          The disk space or database image is full.
 661         * @exception    E_IO                            Either of the following conditions has occurred: @n
 662         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 663         *                                                                       - %File corruption is detected.
 664         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 665         * @see                  BeginTransaction()
 666     * @see              CommitTransaction()
 667         */
 668         result RollbackTransaction(void);
 669
 670         /**
 671         * Gets the database's filename.
 672         *
 673         * @since                2.0
 674         *
 675         * @return               The filename of this %Database instance
 676         */
 677         Tizen::Base::String GetName(void) const;
 678
 679         /**
 680         * Deletes the database file with the specified file name.
 681         *
 682         * @if OSPCOMPAT
 683         * @brief <i> [Compatibility] </i>
 684         * @endif
 685         * @since                2.0
 686         * @if OSPCOMPAT
 687         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 688         *                                       For more information, see @ref CompIoPathPage "here".
 689         * @endif
 690         *
 691         * @return               An error code
 692         * @param[in]    databasePath            The path of the database file to delete
 693         * @exception    E_SUCCESS                       The method is successful.
 694         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 695         *                                                                       - The length of the specified @c databasePath is invalid. @n
 696         *                                                                       - The specified @c databasePath parameter contains an invalid path or
 697         *                                                                         the path ends with '/'. @n
 698         *                                                                       - The directory name path is missing. @n
 699         *                                                                       - The parent directory does not exist. @n
 700         *                                                                       - An I/O security issue.
 701         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 702         * @exception    E_FILE_NOT_FOUND        The specified database file cannot be found.
 703         * @exception    E_IO                            Either of the following conditions has occurred: @n
 704         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 705         *                                                                       - %File corruption is detected. @n
 706         *                                                                       - A system error has occurred.
 707         */
 708         static result Delete(const Tizen::Base::String& databasePath);
 709
 710         /**
 711         * Checks whether the database file exists.
 712         *
 713         * @if OSPCOMPAT
 714         * @brief <i> [Compatibility] </i>
 715         * @endif
 716         * @since                2.0
 717         * @if OSPCOMPAT
 718         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 719         *                                       For more information, see @ref CompIoPathPage "here".
 720         * @endif
 721         *
 722         * @return               @c true if the database file exists, @n
 723         *                               else @c false
 724         * @param[in]    databasePath            The path of the database file to check
 725         * @exception    E_SUCCESS                       The method is successful.
 726         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 727         *                                                                       - The length of the specified @c databasePath is invalid. @n
 728         *                                                                       - The specified @c databasePath parameter contains an invalid path or
 729         *                                                                         the path ends with '/'. @n
 730         *                                                                       - The directory name path is missing. @n
 731         *                                                                       - The parent directory does not exist. @n
 732         *                                                                       - An I/O security issue.
 733         * @exception    E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 734         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 735         */
 736         static bool Exists(const Tizen::Base::String& databasePath);
 737
 738         /**
 739         * Converts a normal database file to a secure database file. @n
 740         * A secure database file, that is converted by this method, can be shared among applications with the same key value.
 741         *
 742         * @if OSPCOMPAT
 743         * @brief                        <i> [Compatibility] </i>
 744         * @endif
 745         * @since                        2.0
 746         * @if OSPCOMPAT
 747         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 748         *                                       For path compatibility, see @ref CompIoPathPage "here".
 749         *                                       For exception compatibility, see @ref CompDatabaseExceptionPage "here".
 750         * @endif
 751         * @feature                      %http://tizen.org/feature/database.encryption
 752         *
 753         * @return               An error code
 754         * @param[in]    normalDbPath                    The normal (non-encrypted) database file path
 755         * @param[in]    secureDbPath                    The secure (encrypted) database file path to create
 756         * @param[in]    secretKey                               A key to encrypt normal database file @n
 757         *                                                                               If the normal database file is converted with a specific key value,
 758         *                                                                               applications can access the same secure database file with the identical key value.
 759         * @exception    E_SUCCESS                               The method is successful.
 760         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 761         *                                                                               - The length of the specified path is @c 0 or exceeds system limitations. @n
 762         *                                                                               - The specified path is invalid. @n
 763         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 764         * @exception    E_FILE_NOT_FOUND                The specified @c normalDbPath does not exist.
 765         * @exception    E_FILE_ALREADY_EXIST    The specified @c secureDbPath already exists.
 766         * @exception    E_OBJECT_LOCKED                 The database instance is locked.
 767         * @exception    E_INVALID_FORMAlT               The database file is malformed.
 768         * @exception    E_STORAGE_FULL                  The disk space or database image is full.
 769         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 770         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 771         *                                                                               - %File corruption is detected.
 772         * @exception    E_SYSTEM                                The method cannot proceed due to a severe system error.
 773         * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. For more information, see
 774         *                                                                               <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 775         * @remarks              Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 776         */
 777         static result ConvertToSecureDatabase(const Tizen::Base::String& normalDbPath, const Tizen::Base::String& secureDbPath,
 778                         const Tizen::Base::ByteBuffer& secretKey);
 779
 780         /**
 781         * Gets the last inserted row ID.
 782         *
 783         * @since                2.0
 784         *
 785         * @return               Row ID of the most recent successful insert, @n
 786         *                               else @c -1 if no successful INSERT operations have ever occurred on
 787         *                               the current opened database.
 788         * @remarks              The row ID is always available as an undeclared column named ROWID, OID, or _ROWID_
 789         *                               as long as those names are not also used by explicitly declared columns.
 790         *                               If the table has a column of type INTEGER PRIMARY KEY then that column is another alias
 791         *                               for the row ID. @n
 792         *                               This method returns the row ID of the most recent successful INSERT operation
 793         *                               for current %Database.
 794         */
 795         long long GetLastInsertRowId(void) const;
 796
 797         /**
 798         * @if OSPCOMPAT
 799         * @page         CompDatabaseExceptionPage Compatibility for E_DATABASE exception
 800         * @section      CompDatabaseExceptionPageIssueSection Issues
 801         *                       Implementing this method in OSP compatible applications has the following issues: @n
 802         *
 803         * -# E_DATABASE exception includes many errors from underlying database engine.
 804         * -# If database is locked, E_SERVICE_BUSY is returned.
 805         *
 806         * @section      CompDatabaseExceptionPageSolutionSection Resolutions
 807         *                       The issue mentioned above is resolved in Tizen. @n
 808         *
 809         * @par          When working in Tizen:
 810         * -# E_DATABASE exception is divided into several exceptions. Refer to exception description of API reference.
 811         * -# E_SERVICE_BUSY is changed to E_OBJECT_LOCKED.
 812         *
 813         * @endif
 814         */
 815
 816 private:
 817         /**
 818         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 819         *
 820         * @since        2.0
 821         */
 822         Database(const Database& rhs);
 823
 824         /**
 825         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 826         * @since        2.0
 827         */
 828         Database& operator =(const Database& rhs);
 829
 830         /**
 831         * The implementation of this method is intentionally blank and declared as private to prohibit implicit conversion.
 832         *
 833         * @since        2.0
 834         */
 835         result Construct(const Tizen::Base::String& dbPath, const wchar_t* pOpenMode);
 836
 837         class _DatabaseImpl* __pDatabaseImpl;
 838
 839         friend class _DatabaseImpl;
 840
 841 }; // Database
 842
 843 }} // Tizen::Io
 844
 845 #endif //_FIO_DATABASE_H_
 846