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