JetGetBookmark 函数

  • 项目

适用于：Windows |Windows服务器

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

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

缪尔文

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

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

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

返回值

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

返回代码

说明

JET_errSuccess

操作已成功完成。

JET_errBufferTooSmall

操作成功完成，但输出缓冲区太小，无法接收整个书签。 输出缓冲区已填充与适合的书签一样多。 如果请求，也返回书签的实际大小。

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

操作无法完成，因为与会话关联的实例遇到一个致命错误，要求撤消对所有数据的访问权限以保护该数据的完整性。

Windows XP：Windows XP 中引入了此返回值。

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

同一会话不能同时用于多个线程。

Windows XP：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 Professional。

Server

需要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