/**
* @class Database
- * @brief This class provides the basic database and database entry management methods.
+ * @brief This class provides methods for database management.
*
* @since 2.0
*
* @final This class is not intended for extension.
*
- * The %Database class provides the basic database and database entry management methods.
+ * The %Database class provides methods for database management.
* All members of this class are guaranteed to be thread-safe.
*
* For more information on the class features,
public:
/**
- * 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.
+ * The object is not fully constructed after this constructor is called. @n
+ * For full construction, the Construct() method must be called right after calling this constructor.
*
* @since 2.0
*/
* @param[in] createIfNotExist Set to @c true to create a database file, @n
* else @c false to open an existing database file
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
- * - The length of the specified @c dbPath is invalid. @n
- * - The specified @c dbPath is invalid or the path ends with '/'. @n
- * - The directory name path is missing. @n
- * - The parent directory does not exist. @n
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
- * @exception E_FILE_ALREADY_EXIST The specified database file already exists. @n
- * Creation of database file has failed because the destination file already exists. @n
- * Creation of the database file is attempted if the file does not exist and
- * the specified @c createIfNotExist is @c true.
- * However, at this moment another thread has been already created the database file
- * with the same file path.
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The length of the specified @c dbPath is invalid.
+ * - The specified @c dbPath is invalid or the path ends with '/'.
+ * - The directory name path is missing.
+ * - The parent directory does not exist.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
+ * @exception E_FILE_ALREADY_EXIST Either of the following conditions has occurred:
+ * - The specified database file already exists.
+ * - The creation of the database file failed because the destination file already exists.
+ * - The creation of the database file is attempted if the file does not exist and the specified @c createIfNotExist is
+ * @c true. However, in this case, another thread has already created the database file with the same file path. @n
* This is a rare case, however, it is possible if a race condition is present between several threads.
* @exception E_FILE_NOT_FOUND The specified database file cannot be found or accessed.
- * @exception E_DATABASE Either of the following conditions has occurred: @n
- * - The method has failed to open or create a file. @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_DATABASE Either of the following conditions has occurred:
+ * - The method has failed to open or create a file.
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
- * @remarks To open the database file in the read-only mode,
- * use the Database::Construct(const Tizen::Base::String& dbPath, const char* pOpenMode) method
+ * @remarks To open the database file in the read-only mode, use the Database::Construct(const Tizen::Base::String&, const char*) method
* with "r" as the value for the open mode flag.
* @endcond
*/
*
* @return An error code
* @param[in] dbPath The path of the database file to open
- * @param[in] openMode An open mode flag @n
+ * @param[in] openMode The file opening mode flag @n
* Currently, the following flags can be used in combination with the logical OR operator: @n
* (1) DB_OPEN_READ_ONLY @n
* (2) DB_OPEN_READ_WRITE @n
* (3) DB_OPEN_READ_WRITE | DB_OPEN_CREATE
* @param[in] option This argument is reserved for further use
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
- * - The length of the specified @c dbPath is invalid. @n
- * - The specified @c openMode is invalid. @n
- * - The specified @c dbPath is invalid or the path ends with '/'. @n
- * - The directory name path is missing. @n
- * - The parent directory does not exist. @n
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The length of the specified @c dbPath is invalid.
+ * - The specified @c openMode is invalid.
+ * - The specified @c dbPath is invalid or the path ends with '/'.
+ * - The directory name path is missing.
+ * - The parent directory does not exist.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
* @exception E_FILE_ALREADY_EXIST The specified database file already exists.
* @exception E_FILE_NOT_FOUND The specified database file cannot be found or accessed.
- * @exception E_DATABASE Either of the following conditions has occurred: @n
- * - The method has failed to open or create a file. @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_DATABASE Either of the following conditions has occurred:
+ * - The method has failed to open or create a file.
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @endcond
*/
* - r+: Open for reading and writing.
* - a+: Open for writing and reading. The database file is created if it does not exist.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
* - The overall length of the specified @c dbPath is equal to @c 0 or
- * exceeds system limitations. @n
- * - The specified @c dbPath ends with '/'. @n
- * - The combination of the specified @c pOpenMode is not allowed. @n
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
+ * exceeds system limitations.
+ * - The specified @c dbPath ends with '/'.
+ * - The combination of the specified @c pOpenMode is not allowed.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
* @exception E_FILE_NOT_FOUND The specified @c dbPath cannot be found.
* @exception E_INVALID_FORMAT The specified @c dbPath is not a database.
* @exception E_STORAGE_FULL The disk space is full.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
- * - %File corruption is detected. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
+ * - %File corruption is detected.
*/
result Construct(const Tizen::Base::String& dbPath, const char* pOpenMode);
* This method opens an existing secure database file or creates a new one according to the specified file opening mode.
* The contents written to the secure database file is automatically encrypted and the contents read from the secure database
* file is automatically decrypted by the platform. @n
- * Applications using this method can access the same secure database files that are created by other applications with the
+ * Applications using this method can access the secure database files that are created by other applications with an
* identical key value in same device. However, the secure files created by this method cannot be accessed in other devices.
*
* @since 2.0
* @return An error code
* @param[in] dbPath The path of the database file to open or create
* @param[in] pOpenMode The file opening mode @n
- * It can be one of the following: @n
- * - r : Open for reading @n
- * - r+: Open for reading and writing @n
- * - a+: Open for writing and reading. The database file is created if it does not exist. @n
- * @param[in] secretKey A key used to encrypt data of a database file or decrypt a secure database file @n
- * If a secure database file is created with a specific key value,
- * other applications can access the same secure database file with the identical key value.
+ * It can be one of the following:
+ * - r : Open for reading
+ * - r+: Open for reading and writing
+ * - a+: Open for writing and reading. The database file is created if it does not exist.
+ * @param[in] secretKey The key used to encrypt the data of the database file or decrypt the secure database file @n
+ * If the secure database file is created with a specific key value,
+ * other applications can access the secure database file with an identical key value.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
* - The overall length of the specified @c dbPath is equal to @c 0 or
- * exceeds system limitations. @n
- * - The specified @c dbPath ends with '/'. @n
- * - The combination of the specified @c pOpenMode is not allowed. @n
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
+ * exceeds system limitations.
+ * - The specified @c dbPath ends with '/'.
+ * - The combination of the specified @c pOpenMode is not allowed.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
* @exception E_FILE_NOT_FOUND The specified @c dbPath cannot be found.
* @exception E_INVALID_FORMAT The specified @c dbPath is not a database.
* @exception E_STORAGE_FULL The disk space is full.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
- * - %File corruption is detected. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
+ * - %File corruption is detected.
* @exception E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. For more information, see
* <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
* @remarks Before calling this method, check whether the feature is supported by Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
result Construct(const Tizen::Base::String& dbPath, const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey);
/**
- * Creates a SQL statement for the current database.
+ * Creates an SQL statement for the current database.
*
* @if OSPCOMPAT
* @brief <i> [Compatibility] </i>
* else @c null if an exception occurs
* @param[in] sqlStatement The SQL statement to compile
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c sqlStatement is invalid SQL.
+ * @exception E_INVALID_ARG The specified @c sqlStatement is an invalid SQL.
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @remarks The specific error code can be accessed using the GetLastResult() method.
DbStatement* CreateStatementN(const Tizen::Base::String& sqlStatement);
/**
- * Executes a statement in the calling %Database instance. @n
+ * Executes a statement in the current %Database instance. @n
* If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
* const char* pOpenMode, const Tizen::Base::ByteBuffer& secretKey),
* the data set written by INSERT/UPDATE is automatically encrypted by the Tizen platform and
- * the data set read by SELECT is also decrypted by itself.
+ * the data set read by SELECT is decrypted.
*
* @if OSPCOMPAT
* @brief <i> [Compatibility] </i>
* SELECT query, or if one of INSERT, UPDATE, and DELETE queries is executed.
* @param[in] dbStatement The DbStatement instance to execute
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c dbStatement includes invalid SQL.
+ * @exception E_INVALID_ARG The specified @c dbStatement includes an invalid SQL.
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_INVALID_FORMAT The database file is malformed.
* @exception E_STORAGE_FULL The disk space or database image is full.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks If @c dbStatement contains the SELECT query, the Reset() method of the DbEnumerator instance returned
- * from this method should be called. The Reset() method should be called before re-binding the dbStatement
+ * @remarks
+ * - If @c dbStatement contains the SELECT query, the Reset() method of the DbEnumerator instance returned
+ * from this method should be called. The %Reset() method should be called before re-binding the dbStatement
* with the bind methods of the DbStatement class.
- * This method returns an enumerator if the result set is generated by the SELECT query.
- * @c null is returned if no result set is available after the successful execution of the SELECT query.
+ * - This method returns an enumerator if the result set is generated by the SELECT query.
+ * @c null is returned if no result set is available after the successful execution of the SELECT query. @n
* Note that, a return value of @c null does not mean that the statement execution has failed.
- * The enumerator returned by the SELECT query does not indicate any row before it calls DbEnumerator::MoveNext().
- * The specific error code can be accessed using the GetLastResult() method.
+ * - The enumerator returned by the SELECT query does not indicate any row before it calls DbEnumerator::MoveNext().
+ * - The specific error code can be accessed using the GetLastResult() method.
*/
DbEnumerator* ExecuteStatementN(const DbStatement& dbStatement);
/**
- * Executes SQL statement in this %Database instance. @n
+ * Executes the specified SQL statement in the current %Database instance. @n
* Any SQL statement that does not give a result set can be run using this method; for example, CREATE, INSERT, UPDATE, DELETE.
* The SELECT query cannot be executed using this method. @n
* If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
* @param[in] sqlStatement The SQL statement to execute
* @param[in] option This argument is reserved for further use.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c sqlStatement is invalid SQL.
+ * @exception E_INVALID_ARG The specified @c sqlStatement is an invalid SQL.
* @exception E_INVALID_OPERATION The specified @c sqlStatement is a SELECT query.
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_INVALID_FORMAT The database file is malformed.
* @exception E_STORAGE_FULL The disk space or database image is full.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @remarks Use QueryN() to execute SELECT query.
result ExecuteSql(const Tizen::Base::String& sqlStatement, bool option);
/**
- * Executes a SELECT query in the calling %Database instance. @n
+ * Executes the specified SELECT query in the current %Database instance. @n
* If an application opens a database file using Database::Construct(const Tizen::Base::String& dbPath,
* const char* pOpenMode, const Tizen::Base::ByteBuffer& key),
* the data set read by SELECT is automatically decrypted by the Tizen platform.
* else @c null if an exception occurs or if no result set is generated after the successful execution of the SELECT query
* @param[in] sqlStatement The SQL statement to execute
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c sqlStatement is invalid SQL.
+ * @exception E_INVALID_ARG The specified @c sqlStatement is an invalid SQL.
* @exception E_INVALID_OPERATION The specified @c sqlStatement is not a SELECT query.
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_INVALID_FORMAT The database file is malformed.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
- * @remarks This method returns an enumerator if the result set is generated by the SELECT query.
- * @c null is returned if no result set is available after the successful execution of the SELECT query.
+ * @remarks
+ * - This method returns an enumerator if the result set is generated by the SELECT query.
+ * @c null is returned if no result set is available after the successful execution of the SELECT query. @n
* Note that, a return value of @c null does not mean that the statement execution has failed.
- * The enumerator returned by the SELECT query does not indicate any row before it calls
+ * - The enumerator returned by the SELECT query does not indicate any row before it calls
* DbEnumerator::MoveNext().
- * The specific error code can be accessed using the GetLastResult() method.
+ * - The specific error code can be accessed using the GetLastResult() method.
* @see ExecuteSql()
*/
DbEnumerator* QueryN(const Tizen::Base::String& sqlStatement);
result BeginTransaction(void);
/**
- * Commits a transaction within this %Database instance.
+ * Commits a transaction within the current %Database instance.
*
* @if OSPCOMPAT
* @brief <i> [Compatibility] </i>
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_INVALID_FORMAT The database file is malformed.
* @exception E_STORAGE_FULL The disk space or database image is full.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @remarks Database::CommitTransaction() automatically resets not only all the DbStatement instances
- * but also all the DbEnumerator instances obtained from the current %Database instance.
- * As a result, the prepared statement of the %DbStatement instances are reset to its initial state, ready to be re-executed,
- * and enumerator of the %DbEnumerator instances are reset to the first position.
- * Therefore, the user should be careful when the same instance of the %Database class is shared across multiple threads.
- * Further, access to the %DbStatement or %DbEnumerator instances resets due to commit operation. This will eventually lead to crash.
- * To avoid a crash, the user can use multiple database instances for each thread.
- * Sharing of the same database instance across multiple threads is not recommended.
+ * but also all the DbEnumerator instances obtained from the current %Database instance. @n
+ * As a result, the prepared statement of the %DbStatement instances are reset to its initial state, ready to be
+ * re-executed, and enumerator of the DbEnumerator instances are reset to the first position. @n
+ * Therefore, you should be careful when the same instance of the %Database class is shared across multiple
+ * threads. Further, access to the %DbStatement or %DbEnumerator instances resets due to a commit operation. @n
+ * This will eventually lead to a crash. To avoid a crash, you can use multiple database instances for each
+ * thread. Sharing of the same database instance across multiple threads is not recommended.
* @see BeginTransaction()
* @see RollbackTransaction()
*/
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_INVALID_FORMAT The database file is malformed.
* @exception E_STORAGE_FULL The disk space or database image is full.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @see BeginTransaction()
result RollbackTransaction(void);
/**
- * Gets the database's filename.
+ * Gets the database file name.
*
* @since 2.0
*
- * @return The filename of this %Database instance
+ * @return The file name of the current %Database instance
*/
Tizen::Base::String GetName(void) const;
* @return An error code
* @param[in] databasePath The path of the database file to delete
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
- * - The length of the specified @c databasePath is invalid. @n
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The length of the specified @c databasePath is invalid.
* - The specified @c databasePath parameter contains an invalid path or
- * the path ends with '/'. @n
- * - The directory name path is missing. @n
- * - The parent directory does not exist. @n
+ * the path ends with '/'.
+ * - The directory name path is missing.
+ * - The parent directory does not exist.
* - An I/O security issue.
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
* @exception E_FILE_NOT_FOUND The specified database file cannot be found.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
- * - %File corruption is detected. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
+ * - %File corruption is detected.
* - A system error has occurred.
*/
static result Delete(const Tizen::Base::String& databasePath);
/**
- * Checks whether the database file exists.
+ * Checks whether the specified database file exists.
*
* @if OSPCOMPAT
* @brief <i> [Compatibility] </i>
* else @c false
* @param[in] databasePath The path of the database file to check
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
- * - The length of the specified @c databasePath is invalid. @n
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The length of the specified @c databasePath is invalid.
* - The specified @c databasePath parameter contains an invalid path or
- * the path ends with '/'. @n
- * - The directory name path is missing. @n
- * - The parent directory does not exist. @n
+ * the path ends with '/'.
+ * - The directory name path is missing.
+ * - The parent directory does not exist.
* - An I/O security issue.
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
* @remarks The specific error code can be accessed using the GetLastResult() method.
*/
static bool Exists(const Tizen::Base::String& databasePath);
/**
- * Converts a normal database file to a secure database file. @n
+ * Converts the specified normal database file to a secure database file. @n
* A secure database file, that is converted by this method, can be shared among applications with the same key value.
*
* @if OSPCOMPAT
* @return An error code
* @param[in] normalDbPath The normal (non-encrypted) database file path
* @param[in] secureDbPath The secure (encrypted) database file path to create
- * @param[in] secretKey A key to encrypt normal database file @n
+ * @param[in] secretKey The key to encrypt the normal database file @n
* If the normal database file is converted with a specific key value,
- * applications can access the same secure database file with the identical key value.
+ * applications can access the secure database file with an identical key value.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
- * - The length of the specified path is @c 0 or exceeds system limitations. @n
- * - The specified path is invalid. @n
- * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
+ * @exception E_INVALID_ARG Either of the following conditions has occurred:
+ * - The length of the specified path is @c 0 or exceeds system limitations.
+ * - The specified path is invalid.
+ * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
* @exception E_FILE_NOT_FOUND The specified @c normalDbPath does not exist.
* @exception E_FILE_ALREADY_EXIST The specified @c secureDbPath already exists.
* @exception E_OBJECT_LOCKED The database instance is locked.
* @exception E_INVALID_FORMAlT The database file is malformed.
* @exception E_STORAGE_FULL The disk space or database image is full.
- * @exception E_IO Either of the following conditions has occurred: @n
- * - An unexpected device failure has occurred as the media ejected suddenly. @n
+ * @exception E_IO Either of the following conditions has occurred:
+ * - An unexpected device failure has occurred as the media ejected suddenly.
* - %File corruption is detected.
* @exception E_SYSTEM The method cannot proceed due to a severe system error.
* @exception E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. For more information, see
*
* @since 2.0
*
- * @return Row ID of the most recent successful insert, @n
+ * @return The row ID of the most recent successful insert, @n
* else @c -1 if no successful INSERT operations have ever occurred on
* the current opened database.
- * @remarks The row ID is always available as an undeclared column named ROWID, OID, or _ROWID_
- * as long as those names are not also used by explicitly declared columns.
- * If the table has a column of type INTEGER PRIMARY KEY then that column is another alias
- * for the row ID. @n
- * This method returns the row ID of the most recent successful INSERT operation
- * for current %Database.
+ * @remarks
+ * - The row ID is always available as an undeclared column named ROWID, OID, or _ROWID_
+ * as long as those names are not used by explicitly declared columns.
+ * - If the table has a column of type ::INTEGER PRIMARY KEY then that column is another alias
+ * for the row ID.
+ * - This method returns the row ID of the most recent successful INSERT operation
+ * for the current %Database instance.
*/
long long GetLastInsertRowId(void) const;
projects / platform / framework / native / appfw.git / blobdiff