Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions

QtopiaSql Class Reference
[QtBaseModule]

The QtopiaSql class provides a collection of methods for setting up and managing database connections. More...

    #include <QtopiaSql>

• List of all members, including inherited members

Public Functions

• QSqlDatabase applicationSpecificDatabase ( const QString & appname )
• void attachDB ( const QString & path )
• void attachDB ( const QString & path, const QString & dbPath )
• QSqlDatabase & database ( const QtopiaDatabaseId & id )
• QtopiaDatabaseId databaseIdForDatabasePath ( const QString & dbPath )
• QtopiaDatabaseId databaseIdForPath ( const QString & path )
• const QList<QtopiaDatabaseId> databaseIds ()
• QString databasePathForId ( const QtopiaDatabaseId & id )
• const QList<QSqlDatabase> databases ()
• void detachDB ( const QString & path )
• bool ensureTableExists ( const QString & tableName, QSqlDatabase & db )
• bool ensureTableExists ( const QStringList & tableNames, QSqlDatabase & db )
• QString escapeString ( const QString & input )   (deprecated)
• QSqlError exec ( const QString & query, QSqlDatabase & db, bool inTransaction = true )
• QSqlError exec ( QSqlQuery & query, QSqlDatabase & db, bool inTransaction = true )
• bool isDatabase ( const QString & path )
• bool isValidDatabaseId ( const QtopiaDatabaseId & id )
• void loadConfig ( const QString & type, const QString & name, const QString & user )
• void logQuery ( const QSqlQuery & q )
• void openDatabase ()
• QSqlDatabase & systemDatabase ()

Static Public Members

• QString escape ( const QString & input )
• QtopiaSql * instance ()
• int stringCompare ( const QString & l, const QString & r )

Detailed Description

The QtopiaSql class provides a collection of methods for setting up and managing database connections.

Qt Extended has a database architecture which uses a number of different databases, including a seperate database for each removable storage media. Additionally the database schema required for a particular version of Qt Extended may differ from that currently on the device due to Qt Extended being upgraded.

Use these routines to manage connections to these databases. The QtopiaDatabaseId type identifies a particular database of the collectin.

The systemDatabase() method is used to fetch a QSqlDatabase object pointing to the Qt Extended main system database. Call attachDB() to connect a database for a particular path, typically associated with a new storage media mount-point. These will be operated on with the system database as a unit.

Lists of the current databases can be obtained with databaseIds() and databases(). Given a database id obtain the path for the associated media mount point with databasePathForId() and obtain the QSqlDatabase itself with database().

The ensureTableExists() methods call through to the Database migration utility to ensure the table schema referred to is loaded.

The attachDB() methods use the underlying database implementation specific method for creating queries across seperate databases. In SQLITE this method is the ATTACH statement, but an equivalent method is used for other implementations.

This documentation should be read and understood in conjunction with the Database Policy and the Database Specification

Member Function Documentation

QSqlDatabase QtopiaSql::applicationSpecificDatabase ( const QString & appname )

Return a QSqlDatabase object for the database specific to the application given by appname Note: You are responsible for calling QSqlDatabase::removeDatabase once you are finished with the connection.

void QtopiaSql::attachDB ( const QString & path )

Attach the database for the media located at the mount-point path. The database to use is located on that media.

After this call database entries for the attached database will be used in future queries executed.

See also exec().

void QtopiaSql::attachDB ( const QString & path, const QString & dbPath )

This is an overloaded member function, provided for convenience.

Attach the database for the media located at the mount-point path. The path given by dbPath is the database to use in the attach.

See also exec().

QSqlDatabase & QtopiaSql::database ( const QtopiaDatabaseId & id )

Returns a reference to the qtopia database object (used for settings storage, doc manager, etc) for the given QtopiaDatabaseId id. There is a separate set of database objects created per thread.

QtopiaDatabaseId QtopiaSql::databaseIdForDatabasePath ( const QString & dbPath )

Return the QtopiaDatabaseId identifier for the database located at the given dbPath.

Internally causes the database system to be opened, if not already open.

QtopiaDatabaseId QtopiaSql::databaseIdForPath ( const QString & path )

Return the QtopiaDatabaseId identifier for the database associated with the given path.

Internally causes the database system to be opened, if not already open.

const QList<QtopiaDatabaseId> QtopiaSql::databaseIds ()

Return a list of the QtopiaDatabaseId entries for all the attached databases.

Internally causes the database system to be opened, if not already open.

QString QtopiaSql::databasePathForId ( const QtopiaDatabaseId & id )

Return the full path to the mount-point related to the database for the given QtopiaDatabaseId id

const QList<QSqlDatabase> QtopiaSql::databases ()

Returns a list QSqlDatabase objects comprising all attached databases.

void QtopiaSql::detachDB ( const QString & path )

Undo the effect of the attachDB() method, for the database associated with mount-point path.

After this call database queries executed will not attempt to reference this database.

See also attachDB() and exec().

bool QtopiaSql::ensureTableExists ( const QString & tableName, QSqlDatabase & db )

Ensure that the given table tableName exists in the database db

Return true if the operation was successful; otherwise returns false

bool QtopiaSql::ensureTableExists ( const QStringList & tableNames, QSqlDatabase & db )

This is an overloaded member function, provided for convenience.

Ensure that all tables in the list of tableNames exists in the database db.

Internally this invokes the "DBMigrationEngine" service to run any migrations or schema updates required.

QString QtopiaSql::escape ( const QString & input )   [static]

Returns the given input with all single quote characters repalced with two consecutive quote characters.

QString QtopiaSql::escapeString ( const QString & input )

This function is deprecated.

Returns the given input with all single quote characters repalced with two consecutive quote characters.

QSqlError QtopiaSql::exec ( const QString & query, QSqlDatabase & db, bool inTransaction = true )

Execute the given QString query on the database db. If inTransaction is true, then perform the query inside an SQL transaction, for atomicity, if the database backend supports this.

QSqlError QtopiaSql::exec ( QSqlQuery & query, QSqlDatabase & db, bool inTransaction = true )

This is an overloaded member function, provided for convenience.

Execute the given QSqlQuery query on the database db. If inTransaction is true, then perform the query inside an SQL transaction, for atomicity, if the database backend supports this.

QtopiaSql * QtopiaSql::instance ()   [static]

Returns a pointer to the singleton object of QtopiaSql. This is the preferred method of accessing the QtopiaSql class.

bool QtopiaSql::isDatabase ( const QString & path )

Return true if the file located at the given path is a Qt Extended database file, for example the datastore used by the SQLITE engine; return false otherwise.

This may be used to test if the file should be shown to the end-user.

    if ( !QtopiaSql::isDatabase( fileFound ))
        listForDisplay.append( fileFound );

bool QtopiaSql::isValidDatabaseId ( const QtopiaDatabaseId & id )

Returns true if the database id is a valid open database in the system.

void QtopiaSql::loadConfig ( const QString & type, const QString & name, const QString & user )

Initializes the state of the QtopiaSql system with the type of database, eg "sqlite".

The meaning of the name and user parameters are as defined in QSqlDatabase.

void QtopiaSql::logQuery ( const QSqlQuery & q )

Send a string for the given QSqlQuery q to the qtopia logging system.

void QtopiaSql::openDatabase ()

Opens the main system database, if it is not already open.

int QtopiaSql::stringCompare ( const QString & l, const QString & r )   [static]

Perform a locale aware string compare of the two argument QStrings l and r using the database implementations native collating functions.

If the database does not provide one, or if one is provided but not integrated, then returns the same result as QString::localeAwareCompare()

QSqlDatabase & QtopiaSql::systemDatabase ()

Return the QSqlDatabase instance of the main system database.