Contents

• Public Functions
• Protected Types
• Protected Functions
• Detailed Description

Detailed Description

TheQSqlResult class provides an abstract interface for accessing data from specific SQL databases.

Normally, you would useQSqlQuery instead ofQSqlResult, sinceQSqlQuery provides a generic wrapper for database-specific implementations ofQSqlResult.

If you are implementing your own SQL driver (by subclassingQSqlDriver), you will need to provide your ownQSqlResult subclass that implements all the pure virtual functions and other virtual functions that you need.

Member Type Documentation

enum QSqlResult::BindingSyntax

This enum type specifies the different syntaxes for specifying placeholders in prepared queries.

See alsobindingSyntax().

Member Function Documentation

[protected]QSqlResult::QSqlResult(constQSqlDriver * db)

Creates aQSqlResult using database driverdb. The object is initialized to an inactive state.

See alsoisActive() anddriver().

[virtual]QSqlResult::~QSqlResult()

Destroys the object and frees any allocated resources.

[protected]void QSqlResult::addBindValue(constQVariant & val,QSql::ParamType paramType)

Binds the valueval of parameter typeparamType to the next available position in the current record (row).

See alsobindValue().

[protected]int QSqlResult::at() const

Returns the current (zero-based) row position of the result. May return the special valuesQSql::BeforeFirstRow orQSql::AfterLastRow.

See alsosetAt() andisValid().

[virtual protected]void QSqlResult::bindValue(int index, constQVariant & val,QSql::ParamType paramType)

Binds the valueval of parameter typeparamType to positionindex in the current record (row).

See alsoaddBindValue().

[virtual protected]void QSqlResult::bindValue(constQString & placeholder, constQVariant & val,QSql::ParamType paramType)

This is an overloaded function.

Binds the valueval of parameter typeparamType to theplaceholder name in the current record (row).

Values cannot be bound to multiple locations in the query, eg:

INSERT INTO testtable (id, name, samename) VALUES (:id, :name, :name)

Binding to name will bind to the first :name, but not the second.

Note:Binding an undefined placeholder will result in undefined behavior.

See alsoQSqlQuery::bindValue().

[protected]QSql::ParamType QSqlResult::bindValueType(int index) const

Returns the parameter type for the value bound at positionindex.

See alsoboundValue().

[protected]QSql::ParamType QSqlResult::bindValueType(constQString & placeholder) const

This is an overloaded function.

Returns the parameter type for the value bound with the givenplaceholder name.

[protected]BindingSyntax QSqlResult::bindingSyntax() const

Returns the binding syntax used by prepared queries.

[protected]QVariant QSqlResult::boundValue(int index) const

Returns the value bound at positionindex in the current record (row).

See alsobindValue() andboundValues().

[protected]QVariant QSqlResult::boundValue(constQString & placeholder) const

This is an overloaded function.

Returns the value bound by the givenplaceholder name in the current record (row).

See alsobindValueType().

[protected]int QSqlResult::boundValueCount() const

Returns the number of bound values in the result.

See alsoboundValues().

[protected]QString QSqlResult::boundValueName(int index) const

Returns the name of the bound value at positionindex in the current record (row).

See alsoboundValue().

[protected]QVector<QVariant> & QSqlResult::boundValues() const

Returns a vector of the result's bound values for the current record (row).

See alsoboundValueCount().

[protected]void QSqlResult::clear()

Clears the entire result set and releases any associated resources.

[pure virtual protected]QVariant QSqlResult::data(int index)

Returns the data for fieldindex in the current row as aQVariant. This function is only called if the result is in an active state and is positioned on a valid record andindex is non-negative. Derived classes must reimplement this function and return the value of fieldindex, or QVariant() if it cannot be determined.

[protected]constQSqlDriver * QSqlResult::driver() const

Returns the driver associated with the result. This is the object that was passed to the constructor.

[virtual protected]bool QSqlResult::exec()

Executes the query, returning true if successful; otherwise returns false.

See alsoprepare().

[protected]QString QSqlResult::executedQuery() const

Returns the query that was actually executed. This may differ from the query that was passed, for example if bound values were used with a prepared query and the underlying database doesn't support prepared queries.

See alsoexec() andsetQuery().

[pure virtual protected]bool QSqlResult::fetch(int index)

Positions the result to an arbitrary (zero-based) rowindex.

This function is only called if the result is in an active state. Derived classes must reimplement this function and position the result to the rowindex, and callsetAt() with an appropriate value. Return true to indicate success, or false to signify failure.

See alsoisActive(),fetchFirst(),fetchLast(),fetchNext(), andfetchPrevious().

[pure virtual protected]bool QSqlResult::fetchFirst()

Positions the result to the first record (row 0) in the result.

This function is only called if the result is in an active state. Derived classes must reimplement this function and position the result to the first record, and callsetAt() with an appropriate value. Return true to indicate success, or false to signify failure.

See alsofetch() andfetchLast().

[pure virtual protected]bool QSqlResult::fetchLast()

Positions the result to the last record (last row) in the result.

This function is only called if the result is in an active state. Derived classes must reimplement this function and position the result to the last record, and callsetAt() with an appropriate value. Return true to indicate success, or false to signify failure.

See alsofetch() andfetchFirst().

[virtual protected]bool QSqlResult::fetchNext()

Positions the result to the next available record (row) in the result.

This function is only called if the result is in an active state. The default implementation callsfetch() with the next index. Derived classes can reimplement this function and position the result to the next record in some other way, and callsetAt() with an appropriate value. Return true to indicate success, or false to signify failure.

See alsofetch() andfetchPrevious().

[virtual protected]bool QSqlResult::fetchPrevious()

Positions the result to the previous record (row) in the result.

This function is only called if the result is in an active state. The default implementation callsfetch() with the previous index. Derived classes can reimplement this function and position the result to the next record in some other way, and callsetAt() with an appropriate value. Return true to indicate success, or false to signify failure.

[virtual]QVariant QSqlResult::handle() const

Returns the low-level database handle for this result set wrapped in aQVariant or an invalidQVariant if there is no handle.

Warning: Use this with uttermost care and only if you know what you're doing.

Warning: The handle returned here can become a stale pointer if the result is modified (for example, if you clear it).

Warning: The handle can be NULL if the result was not executed yet.

The handle returned here is database-dependent, you should query the type name of the variant before accessing it.

This example retrieves the handle for a sqlite result:

QSqlQuery query=...QVariant v= query.result()->handle();if (v.isValid()&& qstrcmp(v.typeName(),"sqlite3_stmt*")) {// v.data() returns a pointer to the handle    sqlite3_stmt*handle=*static_cast<sqlite3_stmt**>(v.data());if (handle!=0) {// check that it is not NULL...    }}

This snippet returns the handle for PostgreSQL or MySQL:

if (v.typeName()=="PGresult*") {    PGresult*handle=*static_cast<PGresult**>(v.data());if (handle!=0)...}if (v.typeName()=="MYSQL_STMT*") {    MYSQL_STMT*handle=*static_cast<MYSQL_STMT**>(v.data());if (handle!=0)...}

See alsoQSqlDriver::handle().

[protected]bool QSqlResult::hasOutValues() const

Returns true if at least one of the query's bound values is aQSql::Out or aQSql::InOut; otherwise returns false.

See alsobindValueType().

[protected]bool QSqlResult::isActive() const

Returns true if the result has records to be retrieved; otherwise returns false.

[protected]bool QSqlResult::isForwardOnly() const

Returns true if you can only scroll forward through the result set; otherwise returns false.

See alsosetForwardOnly().

[pure virtual protected]bool QSqlResult::isNull(int index)

Returns true if the field at positionindex in the current row is null; otherwise returns false.

[protected]bool QSqlResult::isSelect() const

Returns true if the current result is from aSELECT statement; otherwise returns false.

See alsosetSelect().

[protected]bool QSqlResult::isValid() const

Returns true if the result is positioned on a valid record (that is, the result is not positioned before the first or after the last record); otherwise returns false.

See alsoat().

[protected]QSqlError QSqlResult::lastError() const

Returns the last error associated with the result.

See alsosetLastError().

[virtual protected]QVariant QSqlResult::lastInsertId() const

Returns the object ID of the most recent inserted row if the database supports it. An invalidQVariant will be returned if the query did not insert any value or if the database does not report the id back. If more than one row was touched by the insert, the behavior is undefined.

Note that for Oracle databases the row's ROWID will be returned, while for MySQL databases the row's auto-increment field will be returned.

See alsoQSqlDriver::hasFeature().

[protected]QString QSqlResult::lastQuery() const

Returns the current SQL query text, or an empty string if there isn't one.

See alsosetQuery().

[pure virtual protected]int QSqlResult::numRowsAffected()

Returns the number of rows affected by the last query executed, or -1 if it cannot be determined or if the query is aSELECT statement.

See alsosize().

[virtual protected]bool QSqlResult::prepare(constQString & query)

Prepares the givenquery for execution; the query will normally use placeholders so that it can be executed repeatedly. Returns true if the query is prepared successfully; otherwise returns false.

See alsoexec().

[virtual protected]QSqlRecord QSqlResult::record() const

Returns the current record if the query is active; otherwise returns an emptyQSqlRecord.

The default implementation always returns an emptyQSqlRecord.

See alsoisActive().

[pure virtual protected]bool QSqlResult::reset(constQString & query)

Sets the result to use the SQL statementquery for subsequent data retrieval.

Derived classes must reimplement this function and apply thequery to the database. This function is only called after the result is set to an inactive state and is positioned before the first record of the new result. Derived classes should return true if the query was successful and ready to be used, or false otherwise.

See alsosetQuery().

[virtual protected]bool QSqlResult::savePrepare(constQString & query)

Prepares the givenquery, using the underlying database functionality where possible. Returns true if the query is prepared successfully; otherwise returns false.

See alsoprepare().

[virtual protected]void QSqlResult::setActive(bool active)

This function is provided for derived classes to set the internal active state toactive.

See alsoisActive().

[virtual protected]void QSqlResult::setAt(int index)

This function is provided for derived classes to set the internal (zero-based) row position toindex.

See alsoat().

[virtual protected]void QSqlResult::setForwardOnly(bool forward)

Sets forward only mode toforward. Ifforward is true, onlyfetchNext() is allowed for navigating the results. Forward only mode needs much less memory since results do not have to be cached. By default, this feature is disabled.

Setting forward only to false is a suggestion to the database engine, which has the final say on whether a result set is forward only or scrollable.isForwardOnly() will always return the correct status of the result set.

Note:Calling setForwardOnly after execution of the query will result in unexpected results at best, and crashes at worst.

See alsoisForwardOnly(),fetchNext(), andQSqlQuery::setForwardOnly().

[virtual protected]void QSqlResult::setLastError(constQSqlError & error)

This function is provided for derived classes to set the last error toerror.

See alsolastError().

[virtual protected]void QSqlResult::setQuery(constQString & query)

Sets the current query for the result toquery. You must callreset() to execute the query on the database.

See alsoreset() andlastQuery().

[virtual protected]void QSqlResult::setSelect(bool select)

This function is provided for derived classes to indicate whether or not the current statement is a SQLSELECT statement. Theselect parameter should be true if the statement is aSELECT statement; otherwise it should be false.

See alsoisSelect().

[pure virtual protected]int QSqlResult::size()

Returns the size of theSELECT result, or -1 if it cannot be determined or if the query is not aSELECT statement.

See alsonumRowsAffected().