Qt 之 QSqlResult Class

详细描述

QSqlResult 类提供了从特定数据库访问数据的抽象接口。

通常地，我们使用QSqlQuery而不是QSqlResult，因为QSqlQuery为特定于数据库的QSqlResult实现提供了一个通用的包装器。

如果你实现你自己的SQL驱动（通过子类化QSqlDriver），你将需要提供你自己的实现了所有纯虚函数和其它你需要的虚函数的QSqlResult子类。

相关成员

enum QSqlResult::BindingSyntax

这个enum类型指定在准备查询（prepared queries）中指定占位符的不同语法。

枚举常量值描述QSqlResult::PositionalBinding0使用ODBC-风格的位置语法，"?"作为占位符QSqlResult::NamedBinding1使用带有命名占位符的Oracle-风格的语法（例如：":id"）

相关API

QSqlResult::QSqlResult(const QSqlDriver * db) [protected]

创建一个使用数据库驱动db的QSqlResult对象。该对象被初始化为一个非活跃状态。

QSqlResult::~QSqlResult() [virtual]

销毁该对象并释放已分配的任何资源。

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

绑定参数类型为paramType的值val到当前记录(行)中的下一个可用的位置。

int QSqlResult::at() const [protected]

返回结果集中当前行的位置（从0开始）。可能返回特殊值QSql::BeforeFirstRow（-1）或QSql::AfterLastRow（-2）。.

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

绑定参数类型为paramType的值val到当前记录（行）的index位置。

void QSqlResult::bindValue(const QString & placeholder, const QVariant & val, QSql::ParamType paramType) [virtual protected]

这是一个重载函数。

将参数类型为paramType的值val绑定到当前记录（行）中的占位符名称。

值不可以被绑定到查询中的多个位置，例如：

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

绑定到name将绑定到第一个:name,而不是第二个。

注意：绑定一个未定义的占位符将导致未定义的行为。

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

返回绑定到位置index的值得参数类型。

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

这是一个重载函数。

返回给定的占位符名称的值得参数类型。

BindingSyntax QSqlResult::bindingSyntax() const [protected]

返回准备查询（prepare queries）使用的绑定语法。

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

返回当前记录（行）在位置index绑定的值。

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

这是一个重载函数。

返回给定占位符名称在当前记录（行）中绑定的值。

int QSqlResult::boundValueCount() const [protected]

返回结果集中绑定值得数目。

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

返回当前记录在index位置绑定值得名称。

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

返回当前记录结果集的绑定值的一个QVariant容器。

void QSqlResult::clear() [protected]

清楚所有的结果集并释放任何相关的资源。

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

以QVariant类型返回当前行的index字段的数据。这个函数只有在结果处于一个活跃状态，位于一条有效地记录并且索引index是非负数的情况下才会被调用。派生类必须重新实现这个函数并返回索引index字段的值，或者返回QVariant()当没办法决定（该返回什么的时候）。

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

返回结果关联的驱动。这是传给构造器的那个对象。

bool QSqlResult::exec() [virtual protected]

执行查询，成功返回true；否则返回false。

QString QSqlResult::executedQuery() const [protected]

返回实际执行的查询。这可能和已经通过的查询不同，比如，如果将绑定值与准备好的查询一起使用而底层数据库不支持准备查询。

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

将结果定位为任意行的索引index（从0开始）。

这个函数只有在结果处于活跃状态时才会被调用。派生类必须重新实现这个函数、定位结果到index行并以一个合适的值调用setAt()。返回true表示成功，false表示失败。

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

在结果集中将结果定位到第一条记录（第0行）。

这个函数只有在结果处于活跃状态时才会被调用。派生类必须重新实现这个函数、定位结果到第一条记录（第0行）并以一个合适的值调用setAt()。返回true表示成功，false表示失败。

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

在结果集中将结果定位到最后一条记录（最后一行）。

这个函数只有在结果处于活跃状态时才会被调用。派生类必须重新实现这个函数、定位结果到最后一条记录（最后一行）并以一个合适的值调用setAt()。返回true表示成功，false表示失败。

bool QSqlResult::fetchNext() [virtual protected]

定位结果到结果集中的下一条可用的记录（行）。

这个函数只有在结果处于活跃状态时才会被调用。默认实现以下一个索引（为参数）调用fetch()。派生类可以重新实现这个函数、以其他方式定位结果到下一条记录（下一行）并以一个合适的值调用setAt()。返回true表示成功，false表示失败。

bool QSqlResult::fetchPrevious() [virtual protected]

定位结果到结果集中的上一条可用的记录（行）。

这个函数只有在结果处于活跃状态时才会被调用。默认实现以上一个索引（为参数）调用fetch()。派生类可以重新实现这个函数、以其他方式定位结果到上一条记录（上一行）并以一个合适的值调用setAt()。返回true表示成功，false表示失败。

QVariant QSqlResult::handle() const [virtual]

将这个结果集的低级数据库句柄返回到一个QVariant中，或者如果没有句柄则返回一个无效的QVariant。

警告：只有当你知道你在干什么的时候就十分小心地使用它。

警告：如果结果被修改（例如,如果你清除了该结果）则返回的句柄将变成一个旧的指针。

警告：如果结果尚未执行，则该句柄可以为空。

这里返回的句柄是数据库依赖的，你应该在访问它之前先查询该变体的类型名称。

这个例子检索sqlite结果的句柄：

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

此代码片段返回PostgreSQL或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) ...}

bool QSqlResult::hasOutValues() const [protected]

如果查询的绑定值中至少有一个是QSql::Out 或者 QSql::InOut则返回真；否则返回false。

bool QSqlResult::isActive() const [protected]

如果结果有被检索的记录，则返回true；否则返回false。

bool QSqlResult::isForwardOnly() const [protected]

如果只能向前滚动遍历结果集返回true；否则返回false。

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

如果当前行的index位置字段为空返回true；否则返回false。

bool QSqlResult::isSelect() const [protected]

如果当前结果是来自SELECT语句，则返回true；否则返回false。

bool QSqlResult::isValid() const [protected]

如果结果被放置在一条有效地记录上（也就是说，结果不是被放置在第一条记录之前或最后一条记录之后）则返回true；否则返回false。

QSqlError QSqlResult::lastError() const [protected]

返回与结果相关联的最后一个错误。

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

如果数据库支持，则返回最近插入的行的对象的ID。如果查询没有插入任何值或者数据库没有返回id，则返回无效的QVariant。如果插入超过一行，则行为是未定义的。

注意：对于Oracle数据库该行的ROWID将被返回，而对于MySQL，该行的自动增量字段将被返回。

QString QSqlResult::lastQuery() const [protected]

返回当前的SQL查询文本，如果没有则返回一个空字符串。

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

返回被执行的最后一个查询所影响的行数，如果不能确定，或者查询是一条SELECT语句，则返回-1.

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

准备给定的执行查询query；查询通常使用占位符以便可以重复执行。如果成功地准备了查询，则返回true；否则，返回false。

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

如果查询时活跃的则返回当前的记录；否则返回一个空的记录（QSqlRecord）。

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

将结果设置为使用SQL语句query以进行后续的数据检索。

派生类必须重新实现这个函数，并将查询应用于数据库。这个函数只在结果被设置为不活跃状态后被调用，并在新结果的的第一条记录之前被定位。如果查询成功并准备好被使用，派生类应该返回true，否则，返回false。

void QSqlResult::resetBindCount()  [protected]

重置绑定参数的数量。

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

准备给定的查询query，在可能情况下使用底层数据库功能。如果成功地准备了查询query，则返回true；否则，返回false。

注意：这个方法应该被称为"safePrepare()"。

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

这个函数是为派生类提供的，以将内部活跃状态设置为active。

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

这个函数是为派生类提供的，以将内部的行设置到索引index（从0开始）。

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

设置只向前导航模式为参数forward。如果forward为true，只允许fetchNext()导航结果集。只向前导航模式需要更少的内存，因为结果不需要缓存。默认情况下，该特性是禁用的。

设置只向前导航是对数据库引擎的一个建议，它（数据库引擎）对结果集是否只向前或可滚动有最终的决定权。isForwardOnly()始终返回结果集的正确状态。

注意：在执行完查询后调用setForwardOnly()会导致意想不到的结果，最坏的情况会导致崩溃。（所以要在执行查询之前调用该函数，不能再查询执行之后调用）

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

这个函数是为派生类提供的，用以将最后一个错误设置为参数指定的error。

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

设置结果的当前查询为参数query。你必须调用reset()来执行数据库上的查询。

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

这个函数是为派生类提供的，以指示当前语句是否为SQL的SELECT 语句。如果语句时一条SELECT语句，参数select应该是true。否则应该为false。

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

返回SELECT结果的大小，如果不能确定，或者查询不是SELECT语句，则返回-1。