inc/FIoDatabase.h

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