mozIStorageService

From MDC

The mozIStorageService interface lets you open a mozIStorageConnection to a SQLite database file.

The connection object must be instantiated from the main thread, even if you intend to use it from other threads. This is the only way to open a database connection.

If you wish to use full-text indexing on a database, you must open it as an unshared database, using the openUnsharedDatabase() method.

mozIStorageService is defined in storage/public/mozIStorageService.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.8).

Inherits from: nsISupports

[edit] Method overview

[edit] Methods

[edit] backupDatabaseFile()

Makes a backup copy of a database file.

nsIFile backupDatabaseFile(
  in nsIFile aDBFile,
  in AString aBackupFileName,
  [optional] in nsIFile aBackupParentDirectory
);

[edit] Parameters

aDBFile

The database file to back up.

aBackupFileName

The filename to give to the new backup file.

aBackupParentDirectory

The directory to put the backup into. If this isn't specified, the backup is placed in the same directory as the original file.

[edit] Return value

An nsIFile object representing the newly-created backup file.

[edit] Remarks

This method ensures that the backup file being created has a unique name.

[edit] openSpecialDatabase()

Opens a connection to a named special database storage that identifies the type of storage requested.

 mozIStorageConnection openSpecialDatabase(
   in string aStorageKey
 );

[edit] Parameters

aStorageKey

A string key identifying the type of storage requested. Valid values are "profile" and "memory".

[edit] Return value

A new mozIStorageConnection providing access to the requested database.

[edit] Exceptions thrown

NS_ERROR_INVALID_ARG

aStorageKey is invalid.

[edit] openDatabase()

Opens a database connection to the specified file. After calling this method, you should check the value of mozIStorageConnection::connectionReady to ensure that the database is usable; if that value is false, the database failed to open properly. In that situation, it's recommended that you call mozIStorageService::backupDatabaseFile() to back up the database so that user data isn't lost.

Warning: If you have more than one connection to a file, you must use the exact same name for the file each time, including case. The sqlite code uses a simple string comparison to see if there is already a connection. Opening a connection to "Foo.sqlite" and "foo.sqlite" will corrupt your database.

If your database contains virtual tables (for example, for full-text indexes), you must use openUnsharedDatabase() to open it, since those tables aren't compatible with a shared cache. If you use this method to open a database containing virtual tables, it will think the database is corrupted and throw NS_ERROR_FILE_CORRUPTED.

 mozIStorageConnection openDatabase(
   in nsIFile aDatabaseFile
 );

[edit] Parameters

aDatabaseFile

An nsIFile indicating the database file to open.

[edit] Return value

A mozIStorageConnection representing the connection to the opened database file.

[edit] Exceptions thrown

NS_ERROR_FAILURE

An error occurred attempting to open the database.

NS_ERROR_FILE_CORRUPTED

The database file is corrupted, or contains virtual tables and is not compatible with this method.

NS_ERROR_OUT_OF_MEMORY

Allocating a new storage object failed.

[edit] openUnsharedDatabase()

Opens a database connection to the specified file without using the sqlite shared cache. After calling this method, you should check the value of mozIStorageConnection::connectionReady to ensure that the database is usable; if that value is false, the database failed to open properly. In that situation, it's recommended that you call mozIStorageService::backupDatabaseFile() to back up the database so that user data isn't lost.

Each connection uses its own sqlite cache, which isn't as efficient as using a shared cache, so you should use openDatabase() instead of this method unless you need a feature of sqlite that is incompatible with a shared cache, such a virtual table or full text indexing support.

Warning: If you have more than one connection to a file, you must use the exact same name for the file each time, including case. The sqlite code uses a simple string comparison to see if there is already a connection. Opening a connection to "Foo.sqlite" and "foo.sqlite" will corrupt your database.

 mozIStorageConnection openUnsharedDatabase(
   in nsIFile aDatabaseFile
 );

[edit] Parameters

aDatabaseFile

An nsIFile indicating the database file to open.

[edit] Return value

A mozIStorageConnection representing the connection to the opened database file.

[edit] Exceptions thrown

NS_ERROR_FAILURE

An error occurred attempting to open the database.

NS_ERROR_FILE_CORRUPTED

The database file is corrupted, or contains virtual tables and is not compatible with this method.

NS_ERROR_OUT_OF_MEMORY

Allocating a new storage object failed.

[edit] See also

• Storage
• mozIStorageConnection