Public Member Functions | Public Attributes

mozIStorageConnection Interface Reference

mozIStorageConnection represents a database connection attached to a specific file or to the in-memory data storage. More...

import "mozIStorageConnection.idl";

Collaboration diagram for mozIStorageConnection:

List of all members.

Public Member Functions

void close ()
 Closes a database connection.
mozIStorageStatement createStatement (in AUTF8String aSQLStatement)
 Create a mozIStorageStatement for the given SQL expression.
void executeSimpleSQL (in AUTF8String aSQLStatement)
 Execute a SQL expression, expecting no arguments.
mozIStoragePendingStatement executeAsync ([array, size_is(aNumStatements)] in mozIStorageStatement aStatements, in unsigned long aNumStatements,[optional] in mozIStorageStatementCallback aCallback)
 Execute an array of queries created with this connection asynchronously using any currently bound parameters.
boolean tableExists (in AUTF8String aTableName)
 Check if the given table exists.
boolean indexExists (in AUTF8String aIndexName)
 Check if the given index exists.
void beginTransaction ()
 Begin a new transaction.
void beginTransactionAs (in PRInt32 transactionType)
void commitTransaction ()
 Commits the current transaction.
void rollbackTransaction ()
 Rolls back the current transaction.
void createTable (in string aTableName, in string aTableSchema)
 Create the table with the given name and schema.
void createFunction (in AUTF8String aFunctionName, in long aNumArguments, in mozIStorageFunction aFunction)
 Create a new SQL function.
void createAggregateFunction (in AUTF8String aFunctionName, in long aNumArguments, in mozIStorageAggregateFunction aFunction)
 Create a new SQL aggregate function.
void removeFunction (in AUTF8String aFunctionName)
 Delete custom SQL function (simple or aggregate one).
mozIStorageProgressHandler setProgressHandler (in PRInt32 aGranularity, in mozIStorageProgressHandler aHandler)
 Sets a progress handler.
mozIStorageProgressHandler removeProgressHandler ()
 Remove a progress handler.

Public Attributes

readonly attribute boolean connectionReady
 Indicates if the connection is open and ready to use.
readonly attribute nsIFile databaseFile
 The current database nsIFile.
readonly attribute long long lastInsertRowID
 lastInsertRowID returns the row ID from the last INSERT operation.
readonly attribute long lastError
 The last error SQLite error code.
readonly attribute AUTF8String lastErrorString
 The last SQLite error as a string (in english, straight from the sqlite library).
attribute long schemaVersion
 The schema version of the database.
readonly attribute boolean transactionInProgress
 Returns true if a transaction is active on this connection.
const PRInt32 TRANSACTION_DEFERRED = 0
 Begins a new transaction with the given type.
const PRInt32 TRANSACTION_IMMEDIATE = 1
const PRInt32 TRANSACTION_EXCLUSIVE = 2

Detailed Description

mozIStorageConnection represents a database connection attached to a specific file or to the in-memory data storage.

It is the primary interface for interacting with a database, including creating prepared statements, executing SQL, and examining database errors.


Member Function Documentation

void mozIStorageConnection::beginTransaction (  ) 

Begin a new transaction.

sqlite default transactions are deferred. If a transaction is active, throws an error.

void mozIStorageConnection::beginTransactionAs ( in PRInt32  transactionType  ) 
void mozIStorageConnection::close (  ) 

Closes a database connection.

C++ callers should simply set the database variable to NULL.

void mozIStorageConnection::commitTransaction (  ) 

Commits the current transaction.

If no transaction is active,

Exceptions:
NS_ERROR_STORAGE_NO_TRANSACTION. 
void mozIStorageConnection::createAggregateFunction ( in AUTF8String  aFunctionName,
in long  aNumArguments,
in mozIStorageAggregateFunction  aFunction 
)

Create a new SQL aggregate function.

If you use your connection on multiple threads, your function needs to be threadsafe, or it should only be called on one thread.

Parameters:
aFunctionName The name of aggregate function to create, as seen in SQL.
aNumArguments The number of arguments the function takes. Pass -1 for variable-argument functions.
aFunction The instance of mozIStorageAggreagteFunction, which implements the function in question.
void mozIStorageConnection::createFunction ( in AUTF8String  aFunctionName,
in long  aNumArguments,
in mozIStorageFunction  aFunction 
)

Create a new SQL function.

If you use your connection on multiple threads, your function needs to be threadsafe, or it should only be called on one thread.

Parameters:
aFunctionName The name of function to create, as seen in SQL.
aNumArguments The number of arguments the function takes. Pass -1 for variable-argument functions.
aFunction The instance of mozIStorageFunction, which implements the function in question.
mozIStorageStatement mozIStorageConnection::createStatement ( in AUTF8String  aSQLStatement  ) 

Create a mozIStorageStatement for the given SQL expression.

The expression may use ? to indicate sequential numbered arguments, ?1, ?2 etc. to indicate specific numbered arguments or :name and $var to indicate named arguments.

Parameters:
aSQLStatement The SQL statement to execute
Returns:
a new mozIStorageStatement
void mozIStorageConnection::createTable ( in string  aTableName,
in string  aTableSchema 
)

Create the table with the given name and schema.

If the table already exists, NS_ERROR_FAILURE is thrown. (XXX at some point in the future it will check if the schema is the same as what is specified, but that doesn't happen currently.)

Parameters:
aTableName the table name to be created, consisting of [A-Za-z0-9_], and beginning with a letter.
aTableSchema the schema of the table; what would normally go between the parens in a CREATE TABLE statement: e.g., "foo INTEGER, bar STRING".
Exceptions:
NS_ERROR_FAILURE if the table already exists or could not be created for any other reason.
mozIStoragePendingStatement mozIStorageConnection::executeAsync ( [array, size_is(aNumStatements)] in mozIStorageStatement  aStatements,
in unsigned long  aNumStatements,
[optional] in mozIStorageStatementCallback  aCallback 
)

Execute an array of queries created with this connection asynchronously using any currently bound parameters.

The statements are ran wrapped in a transaction. These statements can be reused immediately, and reset does not need to be called.

Note: If you have any custom defined functions, they must be re-entrant since they can be called on multiple threads.

Parameters:
aStatements The array of statements to execute asynchronously, in the order they are given in the array.
aNumStatements The number of statements in aStatements.
aCallback [optional] The callback object that will be notified of progress, errors, and completion.
Returns:
an object that can be used to cancel the statements execution.
void mozIStorageConnection::executeSimpleSQL ( in AUTF8String  aSQLStatement  ) 

Execute a SQL expression, expecting no arguments.

Parameters:
aSQLStatement The SQL statement to execute
boolean mozIStorageConnection::indexExists ( in AUTF8String  aIndexName  ) 

Check if the given index exists.

Parameters:
aIndexName The index to check
Returns:
TRUE if the index exists, FALSE otherwise.
void mozIStorageConnection::removeFunction ( in AUTF8String  aFunctionName  ) 

Delete custom SQL function (simple or aggregate one).

Parameters:
aFunctionName The name of function to remove.
mozIStorageProgressHandler mozIStorageConnection::removeProgressHandler (  ) 

Remove a progress handler.

Returns:
previous registered handler.
void mozIStorageConnection::rollbackTransaction (  ) 

Rolls back the current transaction.

If no transaction is active,

Exceptions:
NS_ERROR_STORAGE_NO_TRANSACTION. 
mozIStorageProgressHandler mozIStorageConnection::setProgressHandler ( in PRInt32  aGranularity,
in mozIStorageProgressHandler  aHandler 
)

Sets a progress handler.

Only one handler can be registered at a time. If you need more than one, you need to chain them yourself. This progress handler should be threadsafe if you use this connection object on more than one thread.

Parameters:
aGranularity The number of SQL virtual machine steps between progress handler callbacks.
aHandler The instance of mozIStorageProgressHandler.
Returns:
previous registered handler.
boolean mozIStorageConnection::tableExists ( in AUTF8String  aTableName  ) 

Check if the given table exists.

Parameters:
aTableName The table to check
Returns:
TRUE if table exists, FALSE otherwise.

Member Data Documentation

Indicates if the connection is open and ready to use.

This will be false if the connection failed to open, or it has been closed.

The current database nsIFile.

Null if the database connection refers to an in-memory database.

readonly attribute long mozIStorageConnection::lastError

The last error SQLite error code.

readonly attribute AUTF8String mozIStorageConnection::lastErrorString

The last SQLite error as a string (in english, straight from the sqlite library).

readonly attribute long long mozIStorageConnection::lastInsertRowID

lastInsertRowID returns the row ID from the last INSERT operation.

The schema version of the database.

This should not be used until the database is ready. The schema will be reported as zero if it is not set.

Begins a new transaction with the given type.

Returns true if a transaction is active on this connection.


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