通过

setTapePosition 函数 (winbase.h)

  • 项目

SetTapePosition 函数设置指定设备上的磁带位置。

语法

DWORD SetTapePosition(
  [in] HANDLE hDevice,
  [in] DWORD  dwPositionMethod,
  [in] DWORD  dwPartition,
  [in] DWORD  dwOffsetLow,
  [in] DWORD  dwOffsetHigh,
  [in] BOOL   bImmediate
);

参数

[in] hDevice

要设置磁带位置的设备的句柄。 此句柄是使用 CreateFile 函数创建的。

[in] dwPositionMethod

要执行的定位类型。 此参数须为下列值之一。

值 含义
TAPE_ABSOLUTE_BLOCK
1L
 将磁带移动到 dwOffsetLow 和 dwOffsetHigh 参数指定的特定于设备的块地址。 将忽略 dwPartition 参数。
TAPE_LOGICAL_BLOCK
2L
 将磁带移动到 dwPartition 指定的分区中由 dwOffsetLow 和 dwOffsetHigh 指定的块地址。
TAPE_REWIND
0L
 将磁带移动到当前分区的开头。 将忽略 dwPartition、 dwOffsetLow 和 dwOffsetHigh 参数。
TAPE_SPACE_END_OF_DATA
4L
 将磁带移到 dwPartition 指定的分区上的数据的末尾。
TAPE_SPACE_FILEMARKS
6L
 将磁带向前移动 (或向后移动) 当前分区中 dwOffsetLow 和 dwOffsetHigh 指定的文件标记数。 将忽略 dwPartition 参数。
TAPE_SPACE_RELATIVE_BLOCKS
5L
 将磁带向前 (或向后移动) 当前分区中 dwOffsetLow 和 dwOffsetHigh 指定的块数。 将忽略 dwPartition 参数。
TAPE_SPACE_SEQUENTIAL_FMKS
7L
 将磁带向前移动 (或向后移动) 到当前分区中第一个出现的 n 个文件标记，其中 n 是 dwOffsetLow 和 dwOffsetHigh 指定的数字。 将忽略 dwPartition 参数。
TAPE_SPACE_SEQUENTIAL_SMKS
9L
 将磁带向前移动 (或向后移动) 到当前分区中第一个出现的 n 个设置标记，其中 n 是由 dwOffsetLow 和 dwOffsetHigh 指定的数字。 将忽略 dwPartition 参数。
TAPE_SPACE_SETMARKS
8L
 将磁带向前 (或向后移动) 当前分区中 dwOffsetLow 和 dwOffsetHigh 指定的设置标记数。 将忽略 dwPartition 参数。

[in] dwPartition

要在其中定位的分区。 如果 dwPartition 为零，则使用当前分区。 分区按逻辑从 1 到 n 进行编号，其中 1 是磁带上的第一个分区，n 是最后一个分区。

[in] dwOffsetLow

由 dwPositionMethod 参数指定的位置操作的块地址或计数的低序位。

[in] dwOffsetHigh

由 dwPositionMethod 参数指定的位置操作的块地址或计数的高序位。 如果不需要高阶位，则此参数应为零。

[in] bImmediate

指示是否在移动操作开始后立即返回。 如果此参数为 TRUE，则函数将立即返回;如果 为 FALSE，则函数在移动操作完成之前不会返回。

返回值

如果函数成功，则返回值NO_ERROR。

如果函数失败，它可以返回以下错误代码之一。

错误 说明
ERROR_BEGINNING_OF_MEDIA
1102L
 尝试在中开始标记之前访问数据失败。
ERROR_BUS_RESET
1111L
 在总线上检测到重置条件。
ERROR_DEVICE_NOT_PARTITIONED
1107L
 加载磁带时找不到分区信息。
ERROR_END_OF_MEDIA
1100L
 操作期间到达了磁带结束标记。
ERROR_FILEMARK_DETECTED
1101L
 操作期间已达到文件标记。
ERROR_INVALID_BLOCK_LENGTH
1106L
 在多卷分区中的新磁带上，块大小不正确。
ERROR_MEDIA_CHANGED
1110L
 已更换或删除驱动器中的磁带。
ERROR_NO_DATA_DETECTED
1104L
 操作期间到达了数据结束标记。
ERROR_NO_MEDIA_IN_DRIVE
1112L
 驱动器中没有媒体。
ERROR_NOT_SUPPORTED
50L
 磁带驱动程序不支持请求的函数。
ERROR_PARTITION_FAILURE
1105L
 无法对磁带进行分区。
ERROR_SETMARK_DETECTED
1103L
 操作期间已达到设置标记。
ERROR_UNABLE_TO_LOCK_MEDIA
1108L
 尝试锁定弹出机制失败。
ERROR_UNABLE_TO_UNLOAD_MEDIA
1109L
 尝试卸载磁带失败。
ERROR_WRITE_PROTECT
19L
 介质受写入保护。

注解

如果 dwOffsetLow 和 dwOffsetHigh 指定的偏移量指定要移动的块数、文件标记或集标记，则正偏移量会将磁带向前移动到最后一个块、文件标记或 setmark 的末尾。 负偏移量将磁带向后移动到最后一个块、文件标记或集标记的开头。 如果偏移量为零，则磁带不会移动。

若要获取有关磁带驱动器和介质的状态、功能和容量的信息，请调用 GetTapeParameters 函数。

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

CreateFile

GetTapeParameters

GetTapePosition