Songbird / Development / Songbird Add-Ons API Documentation

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 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.
sbIDatabasePreparedStatement prepareQuery (in AString strQuery)
 Create a prepared statement object to reduce overhead for repeated queries.
void addPreparedStatement (in sbIDatabasePreparedStatement PreparedStatement)
 Add a prepared query to the queue.
unsigned long getQueryCount ()
 Return the number of query strings enqueued for execution.
sbIDatabasePreparedStatement getQuery (in unsigned long nIndex)
 Get the query 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.
long getLastError ()
 Get the last error on the query that has executed.
void setLastError (in long dbError)
 Set the last error on the query.
long execute ()
 Execute the queries enqueued in the object.
long waitForCompletion ()
 Wait until the query has finished executing asynchronously.
boolean isExecuting ()
 Return whether or not the query is currently executing.
unsigned long currentQuery ()
 Return the current index in the queue being indexed.
boolean abort ()
 Abort a currently executing query.
void bindUTF8StringParameter (in unsigned long aParamIndex, in AUTF8String aValue)
 Binds a UTF8String to the last added query.
void bindStringParameter (in unsigned long aParamIndex, in AString aValue)
 Binds a String to the last added query.
void bindDoubleParameter (in unsigned long aParamIndex, in double aValue)
 Binds a double to the last added query.
void bindInt32Parameter (in unsigned long aParamIndex, in long aValue)
 Binds an int32 to the last added query.
void bindInt64Parameter (in unsigned long aParamIndex, in long long aValue)
 Binds an int64 to the last added query.
void bindNullParameter (in unsigned long aParamIndex)
 Binds a null to the last added query.

Public Attributes

attribute nsIURI databaseLocation
 Set a specific folder/directory URI for the database.
attribute unsigned long long rollingLimit
 Set the rolling limit for this query.
attribute unsigned long rollingLimitColumnIndex
 The index of the column used to add to the limit total.
attribute unsigned long rollingLimitResult
 The number of the row (1 is the first row) that met or exceeded the limit.


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 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(), 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 167 of file sbIDatabaseQuery.idl.


Member Function Documentation

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)

PRBool sbIDatabaseQuery::isAyncQuery (  ) 

Return whether or not the query will run asynchronously.

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

void sbIDatabaseQuery::addSimpleQueryCallback ( in sbIDatabaseSimpleQueryCallback  dbPersistCB  ) 

Add a sbIDatabaseSimpleQueryCallback instance to 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::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

AString sbIDatabaseQuery::getDatabaseGUID (  ) 

Get the database identifier string.

Returns:
The identifier string

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

sbIDatabasePreparedStatement sbIDatabaseQuery::prepareQuery ( in AString  strQuery  ) 

Create a prepared statement object to reduce overhead for repeated queries.

This method only creates the object, and does not actually compile the statement until first execution. As of first execution, the sqlite database pointer becomes fixed, and from that point on, it will return null if the Engine attempts to execute it via a different database engine.

See: http://www.sqlite.org/lang.html for supported query syntax.

Parameters:
strQuery The query string

void sbIDatabaseQuery::addPreparedStatement ( in sbIDatabasePreparedStatement  PreparedStatement  ) 

Add a prepared query to the queue.

This method enqueues a PreparedStatement prepared via prepareQuery().

Parameters:
PreparedStatement The prepared query. Must be prepared for use with this Query object.

unsigned long sbIDatabaseQuery::getQueryCount (  ) 

Return the number of query strings enqueued for execution.

Returns:
The number of query strings enqueued

sbIDatabasePreparedStatement sbIDatabaseQuery::getQuery ( in unsigned long  nIndex  ) 

Get the query at the Nth index.

Parameters:
nIndex The index into the queue
Returns:
The Prepared Query.

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.

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

long 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

void sbIDatabaseQuery::setLastError ( in long  dbError  ) 

Set the last error on the query.

The database engine calls this. Don't.

Parameters:
dbError The error code to insert

long sbIDatabaseQuery::execute (  ) 

Execute the queries enqueued in the object.

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

long sbIDatabaseQuery::waitForCompletion (  ) 

Wait until the query has finished executing asynchronously.

If the query is not executing, this immediately returns.

Returns:
NS_OK

boolean sbIDatabaseQuery::isExecuting (  ) 

Return whether or not the query is currently executing.

Returns:
true if executing

unsigned long sbIDatabaseQuery::currentQuery (  ) 

Return the current index in the queue being indexed.

Returns:
The current query index

boolean 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::bindUTF8StringParameter ( in unsigned long  aParamIndex,
in AUTF8String  aValue 
)

Binds a UTF8String to the last added query.

Parameters:
aParamIndex The index of the parameter to bind
aValue Value to bind to the specified index

void sbIDatabaseQuery::bindStringParameter ( in unsigned long  aParamIndex,
in AString  aValue 
)

Binds a String to the last added query.

Parameters:
aParamIndex The index of the parameter to bind
aValue Value to bind to the specified index

void sbIDatabaseQuery::bindDoubleParameter ( in unsigned long  aParamIndex,
in double  aValue 
)

Binds a double to the last added query.

Parameters:
aParamIndex The index of the parameter to bind
aValue Value to bind to the specified index

void sbIDatabaseQuery::bindInt32Parameter ( in unsigned long  aParamIndex,
in long  aValue 
)

Binds an int32 to the last added query.

Parameters:
aParamIndex The index of the parameter to bind
aValue Value to bind to the specified index

void sbIDatabaseQuery::bindInt64Parameter ( in unsigned long  aParamIndex,
in long long  aValue 
)

Binds an int64 to the last added query.

Parameters:
aParamIndex The index of the parameter to bind
aValue Value to bind to the specified index

void sbIDatabaseQuery::bindNullParameter ( in unsigned long  aParamIndex  ) 

Binds a null to the last added query.

Parameters:
aParamIndex The index of the parameter to bind


Member Data Documentation

attribute nsIURI sbIDatabaseQuery::databaseLocation

Set a specific folder/directory URI for the database.

Set a specific folder URI where you wish your database to reside. For example, you could set the location to be the following: 'file:///C:/MyDB/'

Note that the directory is not created for you and must exist by the time execute() is called on the query.

Definition at line 179 of file sbIDatabaseQuery.idl.

attribute unsigned long long sbIDatabaseQuery::rollingLimit

Set the rolling limit for this query.

If set, this query will be a rolling limit query. Rather than return the full result of the query, a rolling limit query will add up the values of the column specified in rollingLimitColumnIndex and stop running once the limit set in rollingLimit is reached. The query result will be a single row containing the row that met or exceeded the limit. The row number of this row will be set in rollingLimitResult. If the limit is not reach, no rows are returned.

Definition at line 371 of file sbIDatabaseQuery.idl.


The documentation for this interface was generated from the following file:
Generated on Tue Mar 10 14:28:57 2009 for Songbird by  doxygen 1.5.2