JetGetBookmark 函数

适用于： Windows |Windows Server

JetGetBookmark 函数

JetGetBookmark 函数检索与光标当前位置的索引项关联的记录的书签。 然后，可以使用此书签通过 JetGoToBookmark 将光标重新定位回同一记录。

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

参数

sesid

用于此调用的会话。

tableid

要用于此调用的游标。

pvBookmark

接收书签的输出缓冲区。

cbMax

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

2013

书签的实际大小（以字节为单位）。

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

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

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBufferTooSmall	操作已成功完成，但输出缓冲区太小，无法接收整个书签。 输出缓冲区中已填充了尽可能多的书签。 如果请求，还返回了书签的实际大小。
JET_errClientRequestToStopJetService	操作无法完成，因为调用 JetStopService 后，与会话关联的实例上的所有活动都已停止。
JET_errInstanceUnavailable	操作无法完成，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。 Windowsxp： 此返回值是在 Windows XP 中引入的。
JET_errNoCurrentRecord	光标未定位在记录上。 导致这种情况发生的原因有很多。 例如，如果光标位于当前索引上最后一条记录之后，则会发生此情况。
JET_errNotInitialized	操作无法完成，因为与会话关联的实例尚未初始化。
JET_errRestoreInProgress	操作无法完成，因为正在对与会话关联的实例执行还原操作。
JET_errSessionSharingViolation	同一会话不能同时用于多个线程。 Windowsxp： 此返回值是在 Windows XP 中引入的。
JET_errTermInProgress	操作无法完成，因为正在关闭与会话关联的实例。

如果此函数成功，则输出缓冲区中将返回与游标当前位置的索引项关联的记录的书签。 不会更改数据库状态。

如果此函数失败，除非返回JET_errBufferTooSmall，否则输出缓冲区的状态和书签的实际大小将不确定。 如果返回JET_errBufferTooSmall，输出缓冲区将包含所提供空间中容纳的书签，并且书签的实际大小将准确。 不会更改数据库状态。

备注

书签通常应被视为不透明的数据块。 不应尝试利用此数据的内部结构。 但是，以下条件适用于所有 ESENT 书签：

• 书签唯一标识给定表中的记录。

• 记录的书签在该记录的生存期内不会更改。

• 记录的书签与包含该记录的表上主索引上该记录的键相同。 如果未在该表上定义主索引，数据库引擎将为记录创建自己的书签。

• 书签可以使用 memcmp 函数相互比较，以在源记录表的主索引中建立书签的相对顺序。 如果未对该表定义主索引，则使用该表中书签的相对排序没有意义。

• 将不同表中的记录书签相互比较是毫无意义的。

• 在 Windows Vista 之前，书签的长度始终小于或等于 JET_cbBookmarkMost (256) 个字节。

Windows Vista： 在 Windows Vista 及更高版本中，书签可以大于 JET_cbBookmarkMost (256) 字节。 书签的最大大小等于当前值 JET_paramKeyMost + 1。

要求

要求	值
客户端	需要 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_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp