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