mozIStorageService Interface Reference

import "mozIStorageService.idl";

Inheritance diagram for mozIStorageService:

[legend]

Collaboration diagram for mozIStorageService:

[legend]

List of all members.

---

Detailed Description

This is the only way to open a database connection.

Public Member Functions
mozIStorageConnection	openSpecialDatabase (in string aStorageKey)
	Get a connection to a named special database storage.
mozIStorageConnection	openDatabase (in nsIFile aDatabaseFile)
	Open a connection to the specified file.
mozIStorageConnection	openUnsharedDatabase (in nsIFile aDatabaseFile)
	Open a connection to the specified file that doesn't share a sqlite cache.
nsIFile	backupDatabaseFile (in nsIFile aDBFile, in AString aBackupFileName,[optional] in nsIFile aBackupParentDirectory)
	Copies the specified database file to the specified parent directory with the specified file name.

---

Member Function Documentation

mozIStorageConnection mozIStorageService::openSpecialDatabase

(

in string

aStorageKey

)

Parameters:

aStorageKey

a string key identifying the type of storage requested. Valid values include: "profile", "memory".

See also:

openDatabase for restrictions on how database connections may be used. For the profile database, you should only access it from the main thread since other callers may also have connections.

Returns:

a new mozIStorageConnection for the requested storage database.

Exceptions:

NS_ERROR_INVALID_ARG

if aStorageKey is invalid.

mozIStorageConnection mozIStorageService::openDatabase

(

in nsIFile

aDatabaseFile

)

Consumers should check mozIStorageConnection::connectionReady to ensure that they can use the database. If this value is false, it is strongly recommended that the database be backed up with mozIStorageConnection::backupDB so user data is not lost.

========== DANGER ==========

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 compare to see if there is already a connection. Opening a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.

The connection object returned by this function is not threadsafe. You must use it only from the thread you created it from.

If your database contains virtual tables (f.e. for full-text indexes), you must open it with openUnsharedDatabase, as those tables are incompatible with a shared cache. If you attempt to use this method to open a database containing virtual tables, it will think the database is corrupted and throw NS_ERROR_FILE_CORRUPTED.

Parameters:

aDatabaseFile

A nsIFile that represents the database that is to be opened..

Returns:

a mozIStorageConnection for the requested database file.

Exceptions:

	NS_ERROR_OUT_OF_MEMORY	If allocating a new storage object fails.
	NS_ERROR_FILE_CORRUPTED	If the database file is corrupted.

mozIStorageConnection mozIStorageService::openUnsharedDatabase

(

in nsIFile

aDatabaseFile

)

Each connection uses its own sqlite cache, which is inefficient, so you should use openDatabase instead of this method unless you need a feature of SQLite that is incompatible with a shared cache, like virtual table and full text indexing support.

Consumers should check mozIStorageConnection::connectionReady to ensure that they can use the database. If this value is false, it is strongly recommended that the database be backed up with mozIStorageConnection::backupDB so user data is not lost.

========== DANGER ==========

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 compare to see if there is already a connection. Opening a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.

The connection object returned by this function is not threadsafe. You must use it only from the thread you created it from.

Parameters:

aDatabaseFile

A nsIFile that represents the database that is to be opened..

Returns:

a mozIStorageConnection for the requested database file.

Exceptions:

	NS_ERROR_OUT_OF_MEMORY	If allocating a new storage object fails.
	NS_ERROR_FILE_CORRUPTED	If the database file is corrupted.

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

If the parent directory is not specified, it places the backup in the same directory as the current file. This function ensures that the file being created is unique.

Parameters:

	aDBFile	The database file that will be backed up.
	aBackupFileName	The name of the new backup file to create.
	[optional]	aBackupParentDirectory The directory you'd like the backup file to be placed.

Returns:

The nsIFile representing the backup file.

---

The documentation for this interface was generated from the following file:

• storage/public/mozIStorageService.idl