JetRetrieveKey 函数

  • 项目

适用于：Windows |Windows服务器

JetRetrieveKey 函数

JetRetrieveKey 函数检索光标当前位置索引项的键。 此类键由对 JetMakeKey 的调用构造。 然后，检索到的键可用于通过调用 JetSeek 将游标有效地返回到同一索引项。

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

参数

sesid

要用于此调用的会话。

tableid

用于此调用的游标。

pvData

将接收密钥的输出缓冲区。

cbMax

输出缓冲区的最大大小（以字节为单位）。

硬体

接收键的实际大小（以字节为单位）。

如果此参数为 NULL，则不会返回密钥的实际大小。

如果输出缓冲区太小，则仍会返回密钥的实际大小。 这意味着此数字将大于输出缓冲区的大小。

grbit

包含用于此调用的选项的一组位，其中包括以下零个或多个。

值

含义

JET_bitRetrieveCopy

指定后，引擎将返回游标的搜索键。 搜索键是使用一个或多个之前对 JetMakeKey 的调用来构建的，目的是使用 JetSeek 或使用 JetSetIndexRange 设置索引范围。

返回值

此函数使用以下返回代码之一返回 JET_ERR 数据类型。 有关可能的 ESE 错误的详细信息，请参阅可扩展存储引擎错误和错误处理参数。

返回代码

说明

JET_errSuccess

操作已成功完成。

JET_errClientRequestToStopJetService

无法完成该操作，因为由于调用 JetStopService 而停止了与会话关联的实例上的所有活动。

JET_errInstanceUnavailable

无法完成该操作，因为与会话关联的实例遇到了一个致命错误，该错误要求撤销对所有数据的访问以保护该数据的完整性。 此错误仅由 Windows XP 和更高版本返回。

JET_errKeyNotMade

游标没有当前搜索键。 如果指定了 JET_bitRetrieveCopy，并且尚未使用对 JetMakeKey 的调用为此游标构造搜索键，则 JetRetrieveKey 将发生这种情况。 搜索键将通过对除 JetMove 以外的游标上的任何导航 API 的调用删除。

JET_errNoCurrentRecord

游标未定位在记录上。 导致这种情况发生的原因有很多。 例如，如果光标当前定位在当前索引的最后一条记录之后，将发生这种情况。

JET_errNotInitialized

无法完成该操作，因为尚未初始化与会话关联的实例。

JET_errRestoreInProgress

无法完成该操作，因为还原操作正在与会话关联的实例上进行。

JET_errSessionSharingViolation

同一会话不能同时用于多个线程。 此错误仅由 Windows XP 和更高版本返回。

JET_errTermInProgress

无法完成该操作，因为与会话关联的实例正在关闭。

JET_wrnBufferTruncated

操作成功完成，但输出缓冲区太小，无法接收整个密钥。 输出缓冲区已填充了与拟合的键数量一样多。 如果请求，也会返回密钥的实际大小。

注意 如果指定了JET_bitRetrieveCopy，则不会返回此错误。 有关详细信息，请参阅“备注”部分。

成功后，游标当前位置的索引项的键将在输出缓冲区中返回。 如果返回JET_wrnBufferTruncated，则输出缓冲区将包含与所提供的空间一样多的键，并且键的实际大小准确。 不会更改数据库状态。

失败时，输出缓冲区的状态和密钥的实际大小将未定义。 不会更改数据库状态。

注解

密钥通常应被视为不透明的数据区块。 不应尝试利用此数据的内部结构。 但是，可以了解所有 ESENT 键的以下属性：

  • 可以使用 memcmp 函数相互比较键，以在源索引条目的表中建立其相对排序。

  • 无法相互比较不同索引的索引项的键。

  • Windows Vista 之前，密钥的长度始终小于或等于 JET_cbKeyMost (255) 字节。 在 Windows Vista 及更高版本上，密钥可能更大。 键的最大大小等于JET_paramKeyMost的当前值。

除了一般情况下 ESENT 键的上述属性外，请务必注意搜索键与索引项的键不同。 具体而言，搜索键可能比普通键长。 构造搜索键时使用通配符选项时，会出现此额外长度。 有关详细信息，请参阅 JetMakeKey 。

此 API 中存在一个重要的 bug，存在于所有版本中。 如果使用 JET_bitRetrieveCopy 请求搜索密钥，并且输出缓冲区太小，无法接收整个密钥，则不会返回JET_wrnBufferTruncated。 将改为返回JET_errSuccess。 请务必验证使用 azureActual 返回的键的实际大小是否小于或等于输出缓冲区的大小。 如果实际大小大于输出缓冲区的大小，则 JetRetrieveKey 的调用方应像返回JET_wrnBufferTruncated一样做出反应。

要求

要求 值

客户端

需要Windows Vista、Windows XP 或 Windows 2000 Professional。

Server

需要Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。

标头

在 Esent.h 中声明。

Library

使用 ESENT.lib。

DLL

需要ESENT.dll。

另请参阅

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange