sbIDatabaseQuery Interface Reference

An object responsible for executing SQL queries on the database. More...

import "sbIDatabaseQuery.idl";

List of all members.

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.


Detailed Description

An object responsible for executing SQL queries on the database.

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.

See also:
sbIDatabaseSimpleQueryCallback, sbIDatabaseQueryCallback

Definition at line 173 of file sbIDatabaseQuery.idl.


Member Function Documentation

PRBool sbIDatabaseQuery::abort (  ) 

Abort a currently executing query.

This method blocks until the query has aborted

Returns:
True, if the query was executing and aborted (false if not executing)

void sbIDatabaseQuery::addCallback ( in sbIDatabaseQueryCallback  dbCallback  ) 

Add a sbIDatabaseQueryCallback instance to the query.

Parameters:
dbPersistCB The callback instance

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.

Parameters:
strQuery The query string

void sbIDatabaseQuery::addSimpleQueryCallback ( in sbIDatabaseSimpleQueryCallback  dbPersistCB  ) 

Add a sbIDatabaseSimpleQueryCallback instance to the query.

Parameters:
dbPersistCB The callback instance

PRInt32 sbIDatabaseQuery::currentQuery (  ) 

Return the current index in the queue being indexed.

Returns:
The current query index

PRInt32 sbIDatabaseQuery::execute (  ) 

Execute the queries enqueued in the object.

Returns:
The error value if synchronous, or 0 if async

AString sbIDatabaseQuery::getDatabaseGUID (  ) 

Get the database identifier string.

Returns:
The 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.

Returns:
The error code, or 0 if no error

AString sbIDatabaseQuery::getQuery ( in PRInt32  nIndex  ) 

Get the query string at the Nth index.

Parameters:
nIndex The index into the queue

PRInt32 sbIDatabaseQuery::getQueryCount (  ) 

Return the number of query strings enqueued for execution.

Returns:
The number of query strings enqueued

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.

Returns:
The results object

PRBool sbIDatabaseQuery::isAyncQuery (  ) 

Return whether or not the query will run asynchronously.

Returns:
If the query will run asynchronously
See also:
setAsyncQuery

PRBool sbIDatabaseQuery::isExecuting (  ) 

Return whether or not the query is currently executing.

Returns:
true if executing

PRBool sbIDatabaseQuery::isPersistentQuery (  ) 

Return whether or not the query should run persistently.

Returns:
If the query is persistent
See also:
setPersistentQuery

void sbIDatabaseQuery::removeCallback ( in sbIDatabaseQueryCallback  dbCallback  ) 

Remove a sbIDatabaseQueryCallback instance from the query.

Parameters:
dbPersistCB The callback instance

void sbIDatabaseQuery::removeSimpleQueryCallback ( in sbIDatabaseSimpleQueryCallback  dbPersistCB  ) 

Remove a sbIDatabaseSimpleQueryCallback instance from the query.

Parameters:
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.

Parameters:
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.

Parameters:
dbGUID The database identifier

void sbIDatabaseQuery::setLastError ( in PRInt32  dbError  ) 

Set the last error on the query.

The database engine calls this. Don't.

Parameters:
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. :)

Parameters:
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.

Returns:
NS_OK


The documentation for this interface was generated from the following file:
Generated on Mon Aug 21 21:01:55 2006 for Songbird by  doxygen 1.4.7