共用方式為

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
 將磁帶移至 dwOffsetLow 所指定的區塊位址，並在 dwPartition 所指定的分割區中移動 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 個 setmark，其中 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。

如果函式失敗，它可以傳回下列其中一個錯誤碼。

錯誤 Description
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
 作業期間已達到 setmark。
ERROR_UNABLE_TO_LOCK_MEDIA
1108L
 嘗試鎖定退出機制失敗。
ERROR_UNABLE_TO_UNLOAD_MEDIA
1109L
 嘗試卸除磁帶失敗。
ERROR_WRITE_PROTECT
19L
 媒體受到寫入保護。

備註

如果 dwOffsetLow 和 dwOffsetHigh 所指定的位移指定要移動的區塊、檔案標記或 setmark 數目，正位移會將磁帶向前移至最後一個區塊、檔案標記或 setmark 的結尾。 負位移會將磁帶往回移動至最後一個區塊、檔案標記或 setmark 的開頭。 如果位移為零，則磁帶不會移動。

若要取得磁帶機和媒體的狀態、功能和容量相關信息，請呼叫 GetTapeParameters 函式。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 winbase.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

CreateFile

GetTapeParameters

GetTapePosition