1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtSql module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qsqldatabase.h"

    43 #include "qsqlquery.h"

    44 

    45 #ifdef Q_OS_WIN32

    46 // Conflicting declarations of LPCBYTE in sqlfront.h and winscard.h

    47 #define _WINSCARD_H_

    48 #endif

    49 

    50 #ifdef QT_SQL_PSQL

    51 #include "../drivers/psql/qsql_psql.h"

    52 #endif

    53 #ifdef QT_SQL_MYSQL

    54 #include "../drivers/mysql/qsql_mysql.h"

    55 #endif

    56 #ifdef QT_SQL_ODBC

    57 #include "../drivers/odbc/qsql_odbc.h"

    58 #endif

    59 #ifdef QT_SQL_OCI

    60 #include "../drivers/oci/qsql_oci.h"

    61 #endif

    62 #ifdef QT_SQL_TDS

    63 #include "../drivers/tds/qsql_tds.h"

    64 #endif

    65 #ifdef QT_SQL_DB2

    66 #include "../drivers/db2/qsql_db2.h"

    67 #endif

    68 #ifdef QT_SQL_SQLITE

    69 #include "../drivers/sqlite/qsql_sqlite.h"

    70 #endif

    71 #ifdef QT_SQL_SQLITE2

    72 #include "../drivers/sqlite2/qsql_sqlite2.h"

    73 #endif

    74 #ifdef QT_SQL_IBASE

    75 #undef SQL_FLOAT  // avoid clash with ODBC

    76 #undef SQL_DOUBLE

    77 #undef SQL_TIMESTAMP

    78 #undef SQL_TYPE_TIME

    79 #undef SQL_TYPE_DATE

    80 #undef SQL_DATE

    81 #define SCHAR IBASE_SCHAR  // avoid clash with ODBC (older versions of ibase.h with Firebird)

    82 #include "../drivers/ibase/qsql_ibase.h"

    83 #undef SCHAR

    84 #endif

    85 

    86 #include "qdebug.h"

    87 #include "qcoreapplication.h"

    88 #include "qreadwritelock.h"

    89 #include "qsqlresult.h"

    90 #include "qsqldriver.h"

    91 #include "qsqldriverplugin.h"

    92 #include "qsqlindex.h"

    93 #include "private/qfactoryloader_p.h"

    94 #include "private/qsqlnulldriver_p.h"

    95 #include "qmutex.h"

    96 #include "qhash.h"

    97 #include <stdlib.h>

    98 

    99 QT_BEGIN_NAMESPACE

   100 

   101 #if !defined(QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   102 Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,

   103                           (QSqlDriverFactoryInterface_iid,

   104                            QLatin1String("/sqldrivers")))

   105 #endif

   106 

   107 QT_STATIC_CONST_IMPL char *QSqlDatabase::defaultConnection = "qt_sql_default_connection";

   108 

   109 typedef QHash<QString, QSqlDriverCreatorBase*> DriverDict;

   110 

   111 class QConnectionDict: public QHash<QString, QSqlDatabase>

   112 {

   113 public:

   114     inline bool contains_ts(const QString &key)

   115     {

   116         QReadLocker locker(&lock);

   117         return contains(key);

   118     }

   119     inline QStringList keys_ts() const

   120     {

   121         QReadLocker locker(&lock);

   122         return keys();

   123     }

   124 

   125     mutable QReadWriteLock lock;

   126 };

   127 Q_GLOBAL_STATIC(QConnectionDict, dbDict)

   128 

   129 class QSqlDatabasePrivate

   130 {

   131 public:

   132     QSqlDatabasePrivate(QSqlDatabase *d, QSqlDriver *dr = 0):

   133         q(d),

   134         driver(dr),

   135         port(-1)

   136     {

   137         ref = 1;

   138         if(driver)

   139             precisionPolicy = driver->numericalPrecisionPolicy();

   140         else

   141             precisionPolicy= QSql::LowPrecisionDouble;

   142     }

   143     QSqlDatabasePrivate(const QSqlDatabasePrivate &other);

   144     ~QSqlDatabasePrivate();

   145     void init(const QString& type);

   146     void copy(const QSqlDatabasePrivate *other);

   147     void disable();

   148 

   149     QAtomicInt ref;

   150     QSqlDatabase *q;

   151     QSqlDriver* driver;

   152     QString dbname;

   153     QString uname;

   154     QString pword;

   155     QString hname;

   156     QString drvName;

   157     int port;

   158     QString connOptions;

   159     QString connName;

   160     QSql::NumericalPrecisionPolicy precisionPolicy;

   161 

   162     static QSqlDatabasePrivate *shared_null();

   163     static QSqlDatabase database(const QString& name, bool open);

   164     static void addDatabase(const QSqlDatabase &db, const QString & name);

   165     static void removeDatabase(const QString& name);

   166     static void invalidateDb(const QSqlDatabase &db, const QString &name);

   167     static DriverDict &driverDict();

   168     static void cleanConnections();

   169 };

   170 

   171 QSqlDatabasePrivate::QSqlDatabasePrivate(const QSqlDatabasePrivate &other)

   172 {

   173     ref = 1;

   174     q = other.q;

   175     dbname = other.dbname;

   176     uname = other.uname;

   177     pword = other.pword;

   178     hname = other.hname;

   179     drvName = other.drvName;

   180     port = other.port;

   181     connOptions = other.connOptions;

   182     driver = other.driver;

   183     precisionPolicy = other.precisionPolicy;

   184 }

   185 

   186 QSqlDatabasePrivate::~QSqlDatabasePrivate()

   187 {

   188     if (driver != shared_null()->driver)

   189         delete driver;

   190 }

   191 

   192 void QSqlDatabasePrivate::cleanConnections()

   193 {

   194     QConnectionDict *dict = dbDict();

   195     Q_ASSERT(dict);

   196     QWriteLocker locker(&dict->lock);

   197 

   198     QConnectionDict::iterator it = dict->begin();

   199     while (it != dict->end()) {

   200         invalidateDb(it.value(), it.key());

   201         ++it;

   202     }

   203     dict->clear();

   204 }

   205 

   206 static bool qDriverDictInit = false;

   207 static void cleanDriverDict()

   208 {

   209     qDeleteAll(QSqlDatabasePrivate::driverDict());

   210     QSqlDatabasePrivate::driverDict().clear();

   211     QSqlDatabasePrivate::cleanConnections();

   212     qDriverDictInit = false;

   213 }

   214 

   215 DriverDict &QSqlDatabasePrivate::driverDict()

   216 {

   217     static DriverDict dict;

   218     if (!qDriverDictInit) {

   219         qDriverDictInit = true;

   220         qAddPostRoutine(cleanDriverDict);

   221     }

   222     return dict;

   223 }

   224 

   225 QSqlDatabasePrivate *QSqlDatabasePrivate::shared_null()

   226 {

   227     static QSqlNullDriver dr;

   228     static QSqlDatabasePrivate n(NULL, &dr);

   229     return &n;

   230 }

   231 

   232 void QSqlDatabasePrivate::invalidateDb(const QSqlDatabase &db, const QString &name)

   233 {

   234     if (db.d->ref != 1) {

   235         qWarning("QSqlDatabasePrivate::removeDatabase: connection '%s' is still in use, "

   236                  "all queries will cease to work.", name.toLocal8Bit().constData());

   237         db.d->disable();

   238         db.d->connName.clear();

   239     }

   240 }

   241 

   242 void QSqlDatabasePrivate::removeDatabase(const QString &name)

   243 {

   244     QConnectionDict *dict = dbDict();

   245     Q_ASSERT(dict);

   246     QWriteLocker locker(&dict->lock);

   247 

   248     if (!dict->contains(name))

   249         return;

   250 

   251     invalidateDb(dict->take(name), name);

   252 }

   253 

   254 void QSqlDatabasePrivate::addDatabase(const QSqlDatabase &db, const QString &name)

   255 {

   256     QConnectionDict *dict = dbDict();

   257     Q_ASSERT(dict);

   258     QWriteLocker locker(&dict->lock);

   259 

   260     if (dict->contains(name)) {

   261         invalidateDb(dict->take(name), name);

   262         qWarning("QSqlDatabasePrivate::addDatabase: duplicate connection name '%s', old "

   263                  "connection removed.", name.toLocal8Bit().data());

   264     }

   265     dict->insert(name, db);

   266     db.d->connName = name;

   267 }

   268 

   269 /*! \internal

   270 */

   271 QSqlDatabase QSqlDatabasePrivate::database(const QString& name, bool open)

   272 {

   273     const QConnectionDict *dict = dbDict();

   274     Q_ASSERT(dict);

   275 

   276     dict->lock.lockForRead();

   277     QSqlDatabase db = dict->value(name);

   278     dict->lock.unlock();

   279     if (db.isValid() && !db.isOpen() && open) {

   280         if (!db.open())

   281             qWarning() << "QSqlDatabasePrivate::database: unable to open database:" << db.lastError().text();

   282 

   283     }

   284     return db;

   285 }

   286 

   287 

   288 /*! \internal

   289     Copies the connection data from \a other.

   290 */

   291 void QSqlDatabasePrivate::copy(const QSqlDatabasePrivate *other)

   292 {

   293     q = other->q;

   294     dbname = other->dbname;

   295     uname = other->uname;

   296     pword = other->pword;

   297     hname = other->hname;

   298     drvName = other->drvName;

   299     port = other->port;

   300     connOptions = other->connOptions;

   301     precisionPolicy = other->precisionPolicy;

   302 }

   303 

   304 void QSqlDatabasePrivate::disable()

   305 {

   306     if (driver != shared_null()->driver) {

   307         delete driver;

   308         driver = shared_null()->driver;

   309     }

   310 }

   311 

   312 /*!

   313     \class QSqlDriverCreatorBase

   314     \brief The QSqlDriverCreatorBase class is the base class for

   315     SQL driver factories.

   316 

   317     \ingroup database

   318     \inmodule QtSql

   319 

   320     Reimplement createObject() to return an instance of the specific

   321     QSqlDriver subclass that you want to provide.

   322 

   323     See QSqlDatabase::registerSqlDriver() for details.

   324 

   325     \sa QSqlDriverCreator

   326 */

   327 

   328 /*!

   329     \fn QSqlDriverCreatorBase::~QSqlDriverCreatorBase()

   330 

   331     Destroys the SQL driver creator object.

   332 */

   333 

   334 /*!

   335     \fn QSqlDriver *QSqlDriverCreatorBase::createObject() const

   336 

   337     Reimplement this function to returns a new instance of a

   338     QSqlDriver subclass.

   339 */

   340 

   341 /*!

   342     \class QSqlDriverCreator

   343     \brief The QSqlDriverCreator class is a template class that

   344     provides a SQL driver factory for a specific driver type.

   345 

   346     \ingroup database

   347     \inmodule QtSql

   348 

   349     QSqlDriverCreator<T> instantiates objects of type T, where T is a

   350     QSqlDriver subclass.

   351 

   352     See QSqlDatabase::registerSqlDriver() for details.

   353 */

   354 

   355 /*!

   356     \fn QSqlDriver *QSqlDriverCreator::createObject() const

   357     \reimp

   358 */

   359 

   360 /*!

   361     \class QSqlDatabase

   362     \brief The QSqlDatabase class represents a connection to

   363     a database.

   364 

   365     \ingroup database

   366 

   367     \inmodule QtSql

   368 

   369     The QSqlDatabase class provides an interface for accessing a

   370     database through a connection. An instance of QSqlDatabase

   371     represents the connection. The connection provides access to the

   372     database via one of the \l{SQL Database Drivers#Supported

   373     Databases} {supported database drivers}, which are derived from

   374     QSqlDriver.  Alternatively, you can subclass your own database

   375     driver from QSqlDriver. See \l{How to Write Your Own Database

   376     Driver} for more information.

   377 

   378     Create a connection (i.e., an instance of QSqlDatabase) by calling

   379     one of the static addDatabase() functions, where you specify

   380     \l{SQL Database Drivers#Supported Databases} {the driver or type

   381     of driver} to use (i.e., what kind of database will you access?)

   382     and a connection name. A connection is known by its own name,

   383     \e{not} by the name of the database it connects to. You can have

   384     multiple connections to one database. QSqlDatabase also supports

   385     the concept of a \e{default} connection, which is the unnamed

   386     connection. To create the default connection, don't pass the

   387     connection name argument when you call addDatabase().

   388     Subsequently, when you call any static member function that takes

   389     the connection name argument, if you don't pass the connection

   390     name argument, the default connection is assumed. The following

   391     snippet shows how to create and open a default connection to a

   392     PostgreSQL database:

   393 

   394     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 0

   395 

   396     Once the QSqlDatabase object has been created, set the connection

   397     parameters with setDatabaseName(), setUserName(), setPassword(),

   398     setHostName(), setPort(), and setConnectOptions(). Then call

   399     open() to activate the physical connection to the database. The

   400     connection is not usable until you open it.

   401 

   402     The connection defined above will be the \e{default} connection,

   403     because we didn't give a connection name to \l{QSqlDatabase::}

   404     {addDatabase()}. Subsequently, you can get the default connection

   405     by calling database() without the connection name argument:

   406 

   407     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 1

   408 

   409     QSqlDatabase is a value class. Changes made to a database

   410     connection via one instance of QSqlDatabase will affect other

   411     instances of QSqlDatabase that represent the same connection. Use

   412     cloneDatabase() to create an independent database connection based

   413     on an existing one.

   414 

   415     If you create multiple database connections, specify a unique

   416     connection name for each one, when you call addDatabase(). Use

   417     database() with a connection name to get that connection. Use

   418     removeDatabase() with a connection name to remove a connection.

   419     QSqlDatabase outputs a warning if you try to remove a connection

   420     referenced by other QSqlDatabase objects. Use contains() to see if

   421     a given connection name is in the list of connections.

   422 

   423     Once a connection is established, you can call tables() to get the

   424     list of tables in the database, call primaryIndex() to get a

   425     table's primary index, and call record() to get meta-information

   426     about a table's fields (e.g., field names).

   427 

   428     \note QSqlDatabase::exec() is deprecated. Use QSqlQuery::exec()

   429     instead.

   430 

   431     If the driver supports transactions, use transaction() to start a

   432     transaction, and commit() or rollback() to complete it. Use

   433     \l{QSqlDriver::} {hasFeature()} to ask if the driver supports

   434     transactions. \note When using transactions, you must start the

   435     transaction before you create your query.

   436 

   437     If an error occurrs, lastError() will return information about it.

   438 

   439     Get the names of the available SQL drivers with drivers().  Check

   440     for the presence of a particular driver with isDriverAvailable().

   441     If you have created your own custom driver, you must register it

   442     with registerSqlDriver().

   443 

   444     \sa QSqlDriver, QSqlQuery, {QtSql Module}, {Threads and the SQL Module}

   445 */

   446 

   447 /*! \fn QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName)

   448     \threadsafe

   449 

   450     Adds a database to the list of database connections using the

   451     driver \a type and the connection name \a connectionName. If

   452     there already exists a database connection called \a

   453     connectionName, that connection is removed.

   454 

   455     The database connection is referred to by \a connectionName. The

   456     newly added database connection is returned.

   457 

   458     If \a type is not available or could not be loaded, isValid() returns false.

   459 

   460     If \a connectionName is not specified, the new connection becomes

   461     the default connection for the application, and subsequent calls

   462     to database() without the connection name argument will return the

   463     default connection. If a \a connectionName is provided here, use

   464     database(\a connectionName) to retrieve the connection.

   465 

   466     \warning If you add a connection with the same name as an existing

   467     connection, the new connection replaces the old one.  If you call

   468     this function more than once without specifying \a connectionName,

   469     the default connection will be the one replaced.

   470 

   471     Before using the connection, it must be initialized. e.g., call

   472     some or all of setDatabaseName(), setUserName(), setPassword(),

   473     setHostName(), setPort(), and setConnectOptions(), and, finally,

   474     open().

   475 

   476     \sa database() removeDatabase() {Threads and the SQL Module}

   477 */

   478 QSqlDatabase QSqlDatabase::addDatabase(const QString &type, const QString &connectionName)

   479 {

   480     QSqlDatabase db(type);

   481     QSqlDatabasePrivate::addDatabase(db, connectionName);

   482     return db;

   483 }

   484 

   485 /*!

   486     \threadsafe

   487 

   488     Returns the database connection called \a connectionName. The

   489     database connection must have been previously added with

   490     addDatabase(). If \a open is true (the default) and the database

   491     connection is not already open it is opened now. If no \a

   492     connectionName is specified the default connection is used. If \a

   493     connectionName does not exist in the list of databases, an invalid

   494     connection is returned.

   495 

   496     \sa isOpen() {Threads and the SQL Module}

   497 */

   498 

   499 QSqlDatabase QSqlDatabase::database(const QString& connectionName, bool open)

   500 {

   501     return QSqlDatabasePrivate::database(connectionName, open);

   502 }

   503 

   504 /*!

   505     \threadsafe

   506 

   507     Removes the database connection \a connectionName from the list of

   508     database connections.

   509 

   510     \warning There should be no open queries on the database

   511     connection when this function is called, otherwise a resource leak

   512     will occur.

   513 

   514     Example:

   515 

   516     \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 0

   517 

   518     The correct way to do it:

   519 

   520     \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 1

   521 

   522     To remove the default connection, which may have been created with a

   523     call to addDatabase() not specifying a connection name, you can

   524     retrieve the default connection name by calling connectionName() on

   525     the database returned by database(). Note that if a default database

   526     hasn't been created an invalid database will be returned.

   527 

   528     \sa database() connectionName() {Threads and the SQL Module}

   529 */

   530 

   531 void QSqlDatabase::removeDatabase(const QString& connectionName)

   532 {

   533     QSqlDatabasePrivate::removeDatabase(connectionName);

   534 }

   535 

   536 /*!

   537     Returns a list of all the available database drivers.

   538 

   539     \sa registerSqlDriver()

   540 */

   541 

   542 QStringList QSqlDatabase::drivers()

   543 {

   544     QStringList list;

   545 

   546 #ifdef QT_SQL_PSQL

   547     list << QLatin1String("QPSQL7");

   548     list << QLatin1String("QPSQL");

   549 #endif

   550 #ifdef QT_SQL_MYSQL

   551     list << QLatin1String("QMYSQL3");

   552     list << QLatin1String("QMYSQL");

   553 #endif

   554 #ifdef QT_SQL_ODBC

   555     list << QLatin1String("QODBC3");

   556     list << QLatin1String("QODBC");

   557 #endif

   558 #ifdef QT_SQL_OCI

   559     list << QLatin1String("QOCI8");

   560     list << QLatin1String("QOCI");

   561 #endif

   562 #ifdef QT_SQL_TDS

   563     list << QLatin1String("QTDS7");

   564     list << QLatin1String("QTDS");

   565 #endif

   566 #ifdef QT_SQL_DB2

   567     list << QLatin1String("QDB2");

   568 #endif

   569 #ifdef QT_SQL_SQLITE

   570     list << QLatin1String("QSQLITE");

   571 #endif

   572 #ifdef QT_SQL_SQLITE2

   573     list << QLatin1String("QSQLITE2");

   574 #endif

   575 #ifdef QT_SQL_IBASE

   576     list << QLatin1String("QIBASE");

   577 #endif

   578 

   579 #if !defined(QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   580     if (QFactoryLoader *fl = loader()) {

   581         QStringList keys = fl->keys();

   582         for (QStringList::const_iterator i = keys.constBegin(); i != keys.constEnd(); ++i) {

   583             if (!list.contains(*i))

   584                 list << *i;

   585         }

   586     }

   587 #endif

   588 

   589     DriverDict dict = QSqlDatabasePrivate::driverDict();

   590     for (DriverDict::const_iterator i = dict.constBegin(); i != dict.constEnd(); ++i) {

   591         if (!list.contains(i.key()))

   592             list << i.key();

   593     }

   594 

   595     return list;

   596 }

   597 

   598 /*!

   599     This function registers a new SQL driver called \a name, within

   600     the SQL framework. This is useful if you have a custom SQL driver

   601     and don't want to compile it as a plugin.

   602 

   603     Example:

   604     \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 2

   605 

   606     QSqlDatabase takes ownership of the \a creator pointer, so you

   607     mustn't delete it yourself.

   608 

   609     \sa drivers()

   610 */

   611 void QSqlDatabase::registerSqlDriver(const QString& name, QSqlDriverCreatorBase *creator)

   612 {

   613     delete QSqlDatabasePrivate::driverDict().take(name);

   614     if (creator)

   615         QSqlDatabasePrivate::driverDict().insert(name, creator);

   616 }

   617 

   618 /*!

   619     \threadsafe

   620 

   621     Returns true if the list of database connections contains \a

   622     connectionName; otherwise returns false.

   623 

   624     \sa connectionNames(), database(), {Threads and the SQL Module}

   625 */

   626 

   627 bool QSqlDatabase::contains(const QString& connectionName)

   628 {

   629     return dbDict()->contains_ts(connectionName);

   630 }

   631 

   632 /*!

   633     \threadsafe

   634 

   635     Returns a list containing the names of all connections.

   636 

   637     \sa contains(), database(), {Threads and the SQL Module}

   638 */

   639 QStringList QSqlDatabase::connectionNames()

   640 {

   641     return dbDict()->keys_ts();

   642 }

   643 

   644 /*!

   645     \overload

   646 

   647     Creates a QSqlDatabase connection that uses the driver referred

   648     to by \a type. If the \a type is not recognized, the database

   649     connection will have no functionality.

   650 

   651     The currently available driver types are:

   652 

   653     \table

   654     \header \i Driver Type \i Description

   655     \row \i QDB2     \i IBM DB2

   656     \row \i QIBASE   \i Borland InterBase Driver

   657     \row \i QMYSQL   \i MySQL Driver

   658     \row \i QOCI     \i Oracle Call Interface Driver

   659     \row \i QODBC    \i ODBC Driver (includes Microsoft SQL Server)

   660     \row \i QPSQL    \i PostgreSQL Driver

   661     \row \i QSQLITE  \i SQLite version 3 or above

   662     \row \i QSQLITE2 \i SQLite version 2

   663     \row \i QTDS     \i Sybase Adaptive Server

   664     \endtable

   665 

   666     Additional third party drivers, including your own custom

   667     drivers, can be loaded dynamically.

   668 

   669     \sa {SQL Database Drivers}, registerSqlDriver(), drivers()

   670 */

   671 

   672 QSqlDatabase::QSqlDatabase(const QString &type)

   673 {

   674     d = new QSqlDatabasePrivate(this);

   675     d->init(type);

   676 }

   677 

   678 /*!

   679     \overload

   680 

   681     Creates a database connection using the given \a driver.

   682 */

   683 

   684 QSqlDatabase::QSqlDatabase(QSqlDriver *driver)

   685 {

   686     d = new QSqlDatabasePrivate(this, driver);

   687 }

   688 

   689 /*!

   690     Creates an empty, invalid QSqlDatabase object. Use addDatabase(),

   691     removeDatabase(), and database() to get valid QSqlDatabase

   692     objects.

   693 */

   694 QSqlDatabase::QSqlDatabase()

   695 {

   696     d = QSqlDatabasePrivate::shared_null();

   697     d->ref.ref();

   698 }

   699 

   700 /*!

   701     Creates a copy of \a other.

   702 */

   703 QSqlDatabase::QSqlDatabase(const QSqlDatabase &other)

   704 {

   705     d = other.d;

   706     d->ref.ref();

   707 }

   708 

   709 /*!

   710     Assigns \a other to this object.

   711 */

   712 QSqlDatabase &QSqlDatabase::operator=(const QSqlDatabase &other)

   713 {

   714     qAtomicAssign(d, other.d);

   715     return *this;

   716 }

   717 

   718 /*!

   719     \internal

   720 

   721     Create the actual driver instance \a type.

   722 */

   723 

   724 void QSqlDatabasePrivate::init(const QString &type)

   725 {

   726     drvName = type;

   727 

   728     if (!driver) {

   729 #ifdef QT_SQL_PSQL

   730         if (type == QLatin1String("QPSQL") || type == QLatin1String("QPSQL7"))

   731             driver = new QPSQLDriver();

   732 #endif

   733 #ifdef QT_SQL_MYSQL

   734         if (type == QLatin1String("QMYSQL") || type == QLatin1String("QMYSQL3"))

   735             driver = new QMYSQLDriver();

   736 #endif

   737 #ifdef QT_SQL_ODBC

   738         if (type == QLatin1String("QODBC") || type == QLatin1String("QODBC3"))

   739             driver = new QODBCDriver();

   740 #endif

   741 #ifdef QT_SQL_OCI

   742         if (type == QLatin1String("QOCI") || type == QLatin1String("QOCI8"))

   743             driver = new QOCIDriver();

   744 #endif

   745 #ifdef QT_SQL_TDS

   746         if (type == QLatin1String("QTDS") || type == QLatin1String("QTDS7"))

   747             driver = new QTDSDriver();

   748 #endif

   749 #ifdef QT_SQL_DB2

   750         if (type == QLatin1String("QDB2"))

   751             driver = new QDB2Driver();

   752 #endif

   753 #ifdef QT_SQL_SQLITE

   754         if (type == QLatin1String("QSQLITE"))

   755             driver = new QSQLiteDriver();

   756 #endif

   757 #ifdef QT_SQL_SQLITE2

   758         if (type == QLatin1String("QSQLITE2"))

   759             driver = new QSQLite2Driver();

   760 #endif

   761 #ifdef QT_SQL_IBASE

   762         if (type == QLatin1String("QIBASE"))

   763             driver = new QIBaseDriver();

   764 #endif

   765     }

   766 

   767     if (!driver) {

   768         DriverDict dict = QSqlDatabasePrivate::driverDict();

   769         for (DriverDict::const_iterator it = dict.constBegin();

   770              it != dict.constEnd() && !driver; ++it) {

   771             if (type == it.key()) {

   772                 driver = ((QSqlDriverCreatorBase*)(*it))->createObject();

   773             }

   774         }

   775     }

   776 

   777 #if !defined(QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   778     if (!driver && loader()) {

   779         if (QSqlDriverFactoryInterface *factory = qobject_cast<QSqlDriverFactoryInterface*>(loader()->instance(type)))

   780             driver = factory->create(type);

   781     }

   782 #endif // QT_NO_LIBRARY

   783 

   784     if (!driver) {

   785         qWarning("QSqlDatabase: %s driver not loaded", type.toLatin1().data());

   786         qWarning("QSqlDatabase: available drivers: %s",

   787                         QSqlDatabase::drivers().join(QLatin1String(" ")).toLatin1().data());

   788         if (QCoreApplication::instance() == 0)

   789             qWarning("QSqlDatabase: an instance of QCoreApplication is required for loading driver plugins");

   790         driver = shared_null()->driver;

   791     }

   792 }

   793 

   794 /*!

   795     Destroys the object and frees any allocated resources.

   796 

   797     If this is the last QSqlDatabase object that uses a certain

   798     database connection, the is automatically closed.

   799 

   800     \sa close()

   801 */

   802 

   803 QSqlDatabase::~QSqlDatabase()

   804 {

   805     if (!d->ref.deref()) {

   806         close();

   807         delete d;

   808     }

   809 }

   810 

   811 /*!

   812     Executes a SQL statement on the database and returns a QSqlQuery

   813     object. Use lastError() to retrieve error information. If \a

   814     query is empty, an empty, invalid query is returned and

   815     lastError() is not affected.

   816 

   817     \sa QSqlQuery, lastError()

   818 */

   819 

   820 QSqlQuery QSqlDatabase::exec(const QString & query) const

   821 {

   822     QSqlQuery r(d->driver->createResult());

   823     if (!query.isEmpty()) {

   824         r.exec(query);

   825         d->driver->setLastError(r.lastError());

   826     }

   827     return r;

   828 }

   829 

   830 /*!

   831     Opens the database connection using the current connection

   832     values. Returns true on success; otherwise returns false. Error

   833     information can be retrieved using lastError().

   834 

   835     \sa lastError() setDatabaseName() setUserName() setPassword()

   836     \sa setHostName() setPort() setConnectOptions()

   837 */

   838 

   839 bool QSqlDatabase::open()

   840 {

   841     return d->driver->open(d->dbname, d->uname, d->pword, d->hname,

   842                             d->port, d->connOptions);

   843 }

   844 

   845 /*!

   846     \overload

   847 

   848     Opens the database connection using the given \a user name and \a

   849     password. Returns true on success; otherwise returns false. Error

   850     information can be retrieved using the lastError() function.

   851 

   852     This function does not store the password it is given. Instead,

   853     the password is passed directly to the driver for opening the

   854     connection and it is then discarded.

   855 

   856     \sa lastError()

   857 */

   858 

   859 bool QSqlDatabase::open(const QString& user, const QString& password)

   860 {

   861     setUserName(user);

   862     return d->driver->open(d->dbname, user, password, d->hname,

   863                             d->port, d->connOptions);

   864 }

   865 

   866 /*!

   867     Closes the database connection, freeing any resources acquired, and

   868     invalidating any existing QSqlQuery objects that are used with the

   869     database.

   870 

   871     This will also affect copies of this QSqlDatabase object.

   872 

   873     \sa removeDatabase()

   874 */

   875 

   876 void QSqlDatabase::close()

   877 {

   878     d->driver->close();

   879 }

   880 

   881 /*!

   882     Returns true if the database connection is currently open;

   883     otherwise returns false.

   884 */

   885 

   886 bool QSqlDatabase::isOpen() const

   887 {

   888     return d->driver->isOpen();

   889 }

   890 

   891 /*!

   892     Returns true if there was an error opening the database

   893     connection; otherwise returns false. Error information can be

   894     retrieved using the lastError() function.

   895 */

   896 

   897 bool QSqlDatabase::isOpenError() const

   898 {

   899     return d->driver->isOpenError();

   900 }

   901 

   902 /*!

   903   Begins a transaction on the database if the driver supports

   904   transactions. Returns \c{true} if the operation succeeded.

   905   Otherwise it returns \c{false}.

   906 

   907   \sa QSqlDriver::hasFeature(), commit(), rollback()

   908 */

   909 bool QSqlDatabase::transaction()

   910 {

   911     if (!d->driver->hasFeature(QSqlDriver::Transactions))

   912         return false;

   913     return d->driver->beginTransaction();

   914 }

   915 

   916 /*!

   917   Commits a transaction to the database if the driver supports

   918   transactions and a transaction() has been started. Returns \c{true}

   919   if the operation succeeded. Otherwise it returns \c{false}.

   920 

   921   \note For some databases, the commit will fail and return \c{false}

   922   if there is an \l{QSqlQuery::isActive()} {active query} using the

   923   database for a \c{SELECT}. Make the query \l{QSqlQuery::isActive()}

   924   {inactive} before doing the commit.

   925 

   926   Call lastError() to get information about errors.

   927 

   928   \sa QSqlQuery::isActive() QSqlDriver::hasFeature() rollback()

   929 */

   930 bool QSqlDatabase::commit()

   931 {

   932     if (!d->driver->hasFeature(QSqlDriver::Transactions))

   933         return false;

   934     return d->driver->commitTransaction();

   935 }

   936 

   937 /*!

   938   Rolls back a transaction on the database, if the driver supports

   939   transactions and a transaction() has been started. Returns \c{true}

   940   if the operation succeeded. Otherwise it returns \c{false}.

   941 

   942   \note For some databases, the rollback will fail and return

   943   \c{false} if there is an \l{QSqlQuery::isActive()} {active query}

   944   using the database for a \c{SELECT}. Make the query

   945   \l{QSqlQuery::isActive()} {inactive} before doing the rollback.

   946 

   947   Call lastError() to get information about errors.

   948 

   949   \sa QSqlQuery::isActive() QSqlDriver::hasFeature() commit()

   950 */

   951 bool QSqlDatabase::rollback()

   952 {

   953     if (!d->driver->hasFeature(QSqlDriver::Transactions))

   954         return false;

   955     return d->driver->rollbackTransaction();

   956 }

   957 

   958 /*!

   959     Sets the connection's database name to \a name. To have effect,

   960     the database name must be set \e{before} the connection is

   961     \l{open()} {opened}.  Alternatively, you can close() the

   962     connection, set the database name, and call open() again.  \note

   963     The \e{database name} is not the \e{connection name}. The

   964     connection name must be passed to addDatabase() at connection

   965     object create time.

   966 

   967     For the QOCI (Oracle) driver, the database name is the TNS

   968     Service Name.

   969 

   970     For the QODBC driver, the \a name can either be a DSN, a DSN

   971     filename (in which case the file must have a \c .dsn extension),

   972     or a connection string.

   973 

   974     For example, Microsoft Access users can use the following

   975     connection string to open an \c .mdb file directly, instead of

   976     having to create a DSN entry in the ODBC manager:

   977 

   978     \snippet doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp 3

   979 

   980     There is no default value.

   981 

   982     \sa databaseName() setUserName() setPassword() setHostName()

   983     \sa setPort() setConnectOptions() open()

   984 */

   985 

   986 void QSqlDatabase::setDatabaseName(const QString& name)

   987 {

   988     if (isValid())

   989         d->dbname = name;

   990 }

   991 

   992 /*!

   993     Sets the connection's user name to \a name. To have effect, the

   994     user name must be set \e{before} the connection is \l{open()}

   995     {opened}.  Alternatively, you can close() the connection, set the

   996     user name, and call open() again.

   997 

   998     There is no default value.

   999 

  1000     \sa userName() setDatabaseName() setPassword() setHostName()

  1001     \sa setPort() setConnectOptions() open()

  1002 */

  1003 

  1004 void QSqlDatabase::setUserName(const QString& name)

  1005 {

  1006     if (isValid())

  1007         d->uname = name;

  1008 }

  1009 

  1010 /*!

  1011     Sets the connection's password to \a password. To have effect, the

  1012     password must be set \e{before} the connection is \l{open()}

  1013     {opened}.  Alternatively, you can close() the connection, set the

  1014     password, and call open() again.

  1015 

  1016     There is no default value.

  1017 

  1018     \warning This function stores the password in plain text within

  1019     Qt. Use the open() call that takes a password as parameter to

  1020     avoid this behavior.

  1021 

  1022     \sa password() setUserName() setDatabaseName() setHostName()

  1023     \sa setPort() setConnectOptions() open()

  1024 */

  1025 

  1026 void QSqlDatabase::setPassword(const QString& password)

  1027 {

  1028     if (isValid())

  1029         d->pword = password;

  1030 }

  1031 

  1032 /*!

  1033     Sets the connection's host name to \a host. To have effect, the

  1034     host name must be set \e{before} the connection is \l{open()}

  1035     {opened}.  Alternatively, you can close() the connection, set the

  1036     host name, and call open() again.

  1037 

  1038     There is no default value.

  1039 

  1040     \sa hostName() setUserName() setPassword() setDatabaseName()

  1041     \sa setPort() setConnectOptions() open()

  1042 */

  1043 

  1044 void QSqlDatabase::setHostName(const QString& host)

  1045 {

  1046     if (isValid())

  1047         d->hname = host;

  1048 }

  1049 

  1050 /*!

  1051     Sets the connection's port number to \a port. To have effect, the

  1052     port number must be set \e{before} the connection is \l{open()}

  1053     {opened}.  Alternatively, you can close() the connection, set the

  1054     port number, and call open() again..

  1055 

  1056     There is no default value.

  1057 

  1058     \sa port() setUserName() setPassword() setHostName()

  1059     \sa setDatabaseName() setConnectOptions() open()

  1060 */

  1061 

  1062 void QSqlDatabase::setPort(int port)

  1063 {

  1064     if (isValid())

  1065         d->port = port;

  1066 }

  1067 

  1068 /*!

  1069     Returns the connection's database name, which may be empty.

  1070     \note The database name is not the connection name.

  1071 

  1072     \sa setDatabaseName()

  1073 */

  1074 QString QSqlDatabase::databaseName() const

  1075 {

  1076     return d->dbname;

  1077 }

  1078 

  1079 /*!

  1080     Returns the connection's user name; it may be empty.

  1081 

  1082     \sa setUserName()

  1083 */

  1084 QString QSqlDatabase::userName() const

  1085 {

  1086     return d->uname;

  1087 }

  1088 

  1089 /*!

  1090     Returns the connection's password. If the password was not set

  1091     with setPassword(), and if the password was given in the open()

  1092     call, or if no password was used, an empty string is returned.

  1093 */

  1094 QString QSqlDatabase::password() const

  1095 {

  1096     return d->pword;

  1097 }

  1098 

  1099 /*!

  1100     Returns the connection's host name; it may be empty.

  1101 

  1102     \sa setHostName()

  1103 */

  1104 QString QSqlDatabase::hostName() const

  1105 {

  1106     return d->hname;

  1107 }

  1108 

  1109 /*!

  1110     Returns the connection's driver name.

  1111 

  1112     \sa addDatabase(), driver()

  1113 */

  1114 QString QSqlDatabase::driverName() const

  1115 {

  1116     return d->drvName;

  1117 }

  1118 

  1119 /*!

  1120     Returns the connection's port number. The value is undefined if

  1121     the port number has not been set.

  1122 

  1123     \sa setPort()

  1124 */

  1125 int QSqlDatabase::port() const

  1126 {

  1127     return d->port;

  1128 }

  1129 

  1130 /*!

  1131     Returns the database driver used to access the database

  1132     connection.

  1133 

  1134     \sa addDatabase() drivers()