JetRetrieveKey 函数

适用于： Windows |Windows Server

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

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

2013

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

如果此参数为 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。 请务必验证使用 “db”Actual 返回的密钥的实际大小是否小于或等于输出缓冲区的大小。 如果实际大小大于输出缓冲区的大小，则 JetRetrieveKey 的调用方应像返回JET_wrnBufferTruncated一样做出反应。

要求

要求	值
客户端	需要 Windows Vista、Windows XP 或 Windows 2000 专业版。
服务器	需要 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