import "sbIDatabaseQuery.idl";
Public Member Functions | |
void | setAsyncQuery (in PRBool bAsyncQuery) |
Set the query to run asynchronously (ie: execute() does not block). | |
PRBool | isAyncQuery () |
Return whether or not the query will run asynchronously. | |
void | setPersistentQuery (in PRBool bPersistentQuery) |
Set the query to run persistently. | |
PRBool | isPersistentQuery () |
Return whether or not the query should run persistently. | |
void | addSimpleQueryCallback (in sbIDatabaseSimpleQueryCallback dbPersistCB) |
Add a sbIDatabaseSimpleQueryCallback instance to the query. | |
void | removeSimpleQueryCallback (in sbIDatabaseSimpleQueryCallback dbPersistCB) |
Remove a sbIDatabaseSimpleQueryCallback instance from the query. | |
void | setDatabaseGUID (in AString dbGUID) |
Set the database to be queried. | |
AString | getDatabaseGUID () |
Get the database identifier string. | |
void | addQuery (in AString strQuery) |
Add a SQL query string to the queue. | |
PRInt32 | getQueryCount () |
Return the number of query strings enqueued for execution. | |
AString | getQuery (in PRInt32 nIndex) |
Get the query string at the Nth index. | |
void | resetQuery () |
Clear out the query and make it all sparkly new. | |
sbIDatabaseResult | getResultObject () |
Get the results object for the query that has executed. | |
sbIDatabaseResult | getResultObjectOrphan () |
[DEPRECATED] | |
PRInt32 | getLastError () |
Get the last error on the query that has executed. | |
void | setLastError (in PRInt32 dbError) |
Set the last error on the query. | |
PRInt32 | execute () |
Execute the queries enqueued in the object. | |
PRInt32 | waitForCompletion () |
Wait until the query has finished executing asynchronously. | |
void | addCallback (in sbIDatabaseQueryCallback dbCallback) |
Add a sbIDatabaseQueryCallback instance to the query. | |
void | removeCallback (in sbIDatabaseQueryCallback dbCallback) |
Remove a sbIDatabaseQueryCallback instance from the query. | |
PRBool | isExecuting () |
Return whether or not the query is currently executing. | |
PRInt32 | currentQuery () |
Return the current index in the queue being indexed. | |
PRBool | abort () |
Abort a currently executing query. |
The sbIDatabaseQuery object is used to execute queries on the underlying databases that store library and playlist data.
While client code running from chrome is free to query the databases directly, this object is more commonly passed to the database helper objects (sbIMediaLibrary, sbIPlaylistManager) that translate their methods into SQL queries placed into the passed sbIDatabaseQuery instance.
The basic loop for using a query is as follows:
1) Object Initialization - setDatabaseGUID(), optionally setAsyncQuery(), setPersistentQuery(), set callbacks, etc
2) Query Construction - addQuery(), or calls to the helper objects
3) Execution - execute(), optionally waitForCompletion()
4) Get Results - getResultObject()
5) Reset - optionally resetQuery(), if you're going to reuse the object with a new set of query strings
Multiple queries may be added to the object via multiple calls to addQuery, or multiple calls to the helper interfaces. The queries will execute sequentially and the result object will be for the last query executed.
Definition at line 173 of file sbIDatabaseQuery.idl.
PRBool sbIDatabaseQuery::abort | ( | ) |
Abort a currently executing query.
This method blocks until the query has aborted
void sbIDatabaseQuery::addCallback | ( | in sbIDatabaseQueryCallback | dbCallback | ) |
void sbIDatabaseQuery::addQuery | ( | in AString | strQuery | ) |
Add a SQL query string to the queue.
This method enqueues a string to be exectued as a SQL query.
See: http://www.sqlite.org/lang.html for supported query syntax.
strQuery | The query string |
void sbIDatabaseQuery::addSimpleQueryCallback | ( | in sbIDatabaseSimpleQueryCallback | dbPersistCB | ) |
Add a sbIDatabaseSimpleQueryCallback instance to the query.
dbPersistCB | The callback instance |
PRInt32 sbIDatabaseQuery::currentQuery | ( | ) |
Return the current index in the queue being indexed.
PRInt32 sbIDatabaseQuery::execute | ( | ) |
Execute the queries enqueued in the object.
AString sbIDatabaseQuery::getDatabaseGUID | ( | ) |
Get the database identifier string.
PRInt32 sbIDatabaseQuery::getLastError | ( | ) |
Get the last error on the query that has executed.
Don't call this method unless you know the query has completed executing.
AString sbIDatabaseQuery::getQuery | ( | in PRInt32 | nIndex | ) |
Get the query string at the Nth index.
nIndex | The index into the queue |
PRInt32 sbIDatabaseQuery::getQueryCount | ( | ) |
Return the number of query strings enqueued for execution.
sbIDatabaseResult sbIDatabaseQuery::getResultObject | ( | ) |
Get the results object for the query that has executed.
Don't get this object unless you know the query has completed executing.
PRBool sbIDatabaseQuery::isAyncQuery | ( | ) |
Return whether or not the query will run asynchronously.
PRBool sbIDatabaseQuery::isExecuting | ( | ) |
Return whether or not the query is currently executing.
PRBool sbIDatabaseQuery::isPersistentQuery | ( | ) |
Return whether or not the query should run persistently.
void sbIDatabaseQuery::removeCallback | ( | in sbIDatabaseQueryCallback | dbCallback | ) |
Remove a sbIDatabaseQueryCallback instance from the query.
dbPersistCB | The callback instance |
void sbIDatabaseQuery::removeSimpleQueryCallback | ( | in sbIDatabaseSimpleQueryCallback | dbPersistCB | ) |
Remove a sbIDatabaseSimpleQueryCallback instance from the query.
dbPersistCB | The callback instance |
void sbIDatabaseQuery::resetQuery | ( | ) |
Clear out the query and make it all sparkly new.
You *must* call this method if you want to reuse a query object with new query strings.
Otherwise, you may simply call execute again on a query object to reissue the last set of queries.
void sbIDatabaseQuery::setAsyncQuery | ( | in PRBool | bAsyncQuery | ) |
Set the query to run asynchronously (ie: execute() does not block).
Use callbacks or poll via isExecuting() to know when the query completes.
bAsyncQuery | If true, do not block on execute (default: false) |
void sbIDatabaseQuery::setDatabaseGUID | ( | in AString | dbGUID | ) |
Set the database to be queried.
This function associates the query object with a particular database.
The dbGUID parameter is any unique string used as a filename to create a queryable database sandbox.
The special character "*" may be passed to execute a query across all databases tracked by the application.
dbGUID | The database identifier |
void sbIDatabaseQuery::setLastError | ( | in PRInt32 | dbError | ) |
Set the last error on the query.
The database engine calls this. Don't.
dbError | The error code to insert |
void sbIDatabaseQuery::setPersistentQuery | ( | in PRBool | bPersistentQuery | ) |
Set the query to run persistently.
A persistent query will be executed again if the database engine detects that an update or an insert has occured on the table queried by this object.
Usually, this is only useful with a callback. :)
bPersistentQuery | If true, register as a persistent query (default: false) |
PRInt32 sbIDatabaseQuery::waitForCompletion | ( | ) |
Wait until the query has finished executing asynchronously.
If the query is not executing, this immediately returns.