TAPE_PROCESS_COMMAND_ROUTINE回呼函式 (minitape.h)

  • 發行項

TAPE_PROCESS_COMMAND_ROUTINE 處理IOCTL要求的裝置特定層面。

語法

TAPE_PROCESS_COMMAND_ROUTINE TapeProcessCommandRoutine;

TAPE_STATUS TapeProcessCommandRoutine(
  [in, out]      PVOID MinitapeExtension,
  [in, out]      PVOID CommandExtension,
  [in, out]      PVOID CommandParameters,
  [in, out]      PSCSI_REQUEST_BLOCK Srb,
  [in]           ULONG CallNumber,
  [in, optional] TAPE_STATUS StatusOfLastCommand,
  [in, out]      PULONG RetryFlags
)
{...}

參數

[in, out] MinitapeExtension

驅動程式專屬迷你工作延伸模組的指標。 如果迷你類別驅動程式在初始化時未要求迷你工作延伸模組，則為 NULL 。

[in, out] CommandExtension

命令延伸模組的指標。 如果 miniclass 驅動程式在初始化時未要求命令延伸模組，則為 NULL 。

[in, out] CommandParameters

呼叫端所配置的緩衝區指標，其中包含 TAPE_CREATE_PARTITION 結構。

[in, out] Srb

磁帶類別驅動程式所配置和部分填入 SRB 的指標。 TAPE_PROCESS_COMMAND_ROUTINE 必須在 SRB 中填入 CDB。

  • Cdb - 命令的 SCSI CDB 指標。 在填入 CDB 之前，請先清除 CDB 與 TapeClassZeroMemory 。
  • CdbLength - 指定 CDB 中的位元元組數目。
TAPE_PROCESS_COMMAND_ROUTINE 也可能在 SRB 中填入下列成員：
  • DataBuffer - 要傳送之數據緩衝區的指標。 使用TapeClassAllocateSrbBuffer 來配置長度大於或等於DataTransferLength的DataBuffer。
  • DataTransferLength - 指定要在 SRB 中傳輸的位元元組數目。 此成員是由 TapeClassAllocateSrbBuffer 設定。
  • TimeOutValue - 指定此命令的逾時值，從磁帶類別驅動程式的裝置擴充功能覆寫預設逾時值。
  • SrbFlags - 指定此命令的旗標。 如果 SRB 將數據傳送至磁帶機，則磁帶迷你類別驅動程式必須設定SRB_FLAGS_DATA_OUT。 如果 SRB 從磁帶機要求數據，或命令未傳輸任何數據，則此成員可以是零。

[in] CallNumber

指定呼叫 TAPE_PROCESS_COMMAND_ROUTINE 處理指定磁帶命令的次數。 CallNumber 在第一次呼叫這個例程時為零，而且會針對每個後續呼叫遞增，直到miniclass驅動程式傳回指出命令已完成 的TAPE_STATUS 值為止。

[in, optional] StatusOfLastCommand

指定最後一個命令的狀態。 在第一次呼叫 TAPE_PROCESS_COMMAND_ROUTINE 來處理指定的要求時， StatusOfLastCommand 會TAPE_STATUS_SUCCESS。 在後續呼叫中， StatusOfLastCommand 是TAPE_STATUS_SUCCESS或發生錯誤狀態，而磁帶迷你類別驅動程式會在上一次呼叫的 RetryFlags 中設定RETURN_ERRORS。

[in, out] RetryFlags

變數的指標，指定磁帶類別驅動程式在磁帶裝置回報錯誤時應該採取的動作。

低序字會指定要在發生SCSI命令失敗時執行的重試次數。 默認值為零， (沒有重試) 。

高序字包含旗標，指定磁帶類別驅動程式在發生錯誤時應該如何傳回控件：

  • 如果RETURN_ERRORS和IGNORE_ERRORS清楚 (預設) 磁帶類別驅動程式會將失敗狀態傳回給原始要求者。
  • 如果 miniclass 驅動程式設定RETURN_ERRORS，磁帶類別驅動程式會呼叫 TAPE_PROCESS_COMMAND_ROUTINE，並將 StatusOfLastCommand 設定為失敗狀態。
  • 如果 miniclass 驅動程式設定IGNORE_ERRORS，磁帶類別驅動程式會將失敗狀態轉換為成功，並將 StatusOfLastCommand 設定為成功，並呼叫TAPE_PROCESS_COMMAND_ROUTINE。

傳回值

傳回碼 Description
TAPE_STATUS_SEND_SRB_AND_CALLBACK
 表示磁帶類別驅動程式已填入 SRB，並已準備好傳送至目標裝置。 根據預設，只有在 SRB 成功時，磁帶類別驅動程式才會再次呼叫 TAPE_PROCESS_COMMAND_ROUTINE 。 迷你類別驅動程式可以在從 TAPE_PROCESS_COMMAND_ROUTINE傳回之前設定 RetryFlags 來修改預設行為。
TAPE_STATUS_CALLBACK
 指示磁帶類別驅動程式以遞增 CallNumber 並再次呼叫 TAPE_PROCESS_COMMAND_ROUTINE ，而不需將 SRB 傳送至磁帶裝置。
TAPE_STATUS_CHECK_TEST_UNIT_READY
 指示磁帶類別驅動程式填入 TEST UNIT READY 命令的 SRB，並將 SRB 傳送至裝置。
TAPE_STATUS_XXX
 任何其他傳回碼會向磁帶類別驅動程式指出命令已完成，並指出成功、失敗或警告。 此例程可能的完成傳回值包括，但不限於：
TAPE_STATUS_SUCCESS
TAPE_STATUS_INSUFFICIENT_RESOURCES
TAPE_STATUS_INVALID_DEVICE_REQUEST
TAPE_STATUS_INVALID_PARAMETER
TAPE_STATUS_IO_DEVICE_ERROR
TAPE_STATUS_MEDIA_WRITE_PROTECTED
TAPE_STATUS_NOT_IMPLEMENTED

備註

下列函式可以指派給這個回呼佔位元：

CreatePartition

CreatePartition 會處理 IOCTL_TAPE_CREATE_PARTITION 要求的裝置特定層面。 需要此例程。 CreatePartition 會填入磁帶類別驅動程式所傳遞 SRB 中的 CDB，在磁帶上建立磁碟分區。 建立分割區通常需要一系列SRB才能完成作業。 在 CreatePartition 填入指定的 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至目標裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 TapeMiniCreatePartition。

CreatePartition 必須先填入 SRB 中的下列成員，才能返回磁帶類別驅動程式：

如果磁帶迷你類別驅動程式將分割區資訊儲存在minitape擴充功能中， CreatePartition 會先更新擴充功能，再使用TAPE_STATUS_SUCCESS返回磁帶類別驅動程式。

擦 除

清除 會處理 IOCTL_TAPE_ERASE 要求的裝置特定層面。 需要此例程。 清除清除 磁帶，方法是填入磁帶類別驅動程式所傳遞SRB中的CDB。 清除磁帶通常需要一個SRB才能完成作業。 Erase 填入 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 Erase。 然後清除會傳回TAPE_STATUS_SUCCESS。

GetDriveParameters

GetDriveParameters 會處理 IOCTL_TAPE_GET_DRIVE_PARAMS 要求的裝置特定層面。 需要此例程。 GetDriveParameters 會填入磁帶類別驅動程式所傳遞 SRB 中的 CDB，以取得磁帶機參數。 取得磁碟驅動器參數通常需要一系列 SRB 才能完成作業。 GetDriveParameters 填入指定的 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至目標裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 GetDriveParameters。

GetMediaParameters

GetMediaParameters 會處理 IOCTL_TAPE_GET_MEDIA_PARAMS 要求的裝置特定層面。 需要此例程。 GetMediaParameters 會填入磁帶類別驅動程式所傳遞 SRB 中的 CDB，以取得磁帶媒體參數。 取得媒體參數通常需要多個 SRB 才能完成作業，從測試單元開始，迷你類別驅動程式會在第一次呼叫例程時傳回TAPE_STATUS_CHECK_TEST_UNIT_READY來要求此測試單元。

GetMediaParameters 填入指定的 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 GetMediaParameters。

GetMediaTypes

GetMediaTypes 會處理 IOCTL_STORAGE_GET_MEDIA_TYPES_EX 要求的裝置特定層面。 需要此例程。 GetMediaTypes 會填入磁帶類別驅動程式所傳遞 SRB 中的 CDB，以取得磁帶裝置所支援之媒體類型的相關信息。 取得媒體類型通常需要一個以上的 SRB 才能完成作業，從測試單元開始，迷你類別驅動程式會藉由第一次呼叫例程時傳回TAPE_STATUS_CHECK_TEST_UNIT_READY來要求此測試單元。

GetPosition

GetPosition 會處理 IOCTL_TAPE_GET_POSITION 要求的裝置特定層面。 需要此例程。 GetPosition 會填入磁帶類別驅動程式所傳遞 SRB 中的 CDB 來讀取磁帶的位置。 讀取磁帶位置通常需要一個以上的 SRB 才能完成作業，通常從測試單元開始，迷你類別驅動程式會藉由第一次呼叫例程時傳回TAPE_STATUS_CHECK_TEST_UNIT_READY來要求測試單元。

GetStatus

GetStatus 會處理 IOCTL_TAPE_GET_STATUS 要求的裝置特定層面。 此例程是必要的。 GetStatus 會讀取磁帶裝置的狀態，通常是藉由指示磁帶類別驅動程式發出測試單元就緒命令。

如果裝置指出磁碟驅動器是否需要在感知數據中清除 (，而不是回報清除所需的錯誤，迷你類別驅動程式會在 其TapeMiniTapeError 例程) 中處理， GetStatus 會在磁帶類別驅動程式傳遞的SRB中填入CDB以取得感知數據，並視需要， 會傳回TAPE_STATUS_REQUIRES_CLEANING。

準備

準備 會處理 IOCTL_TAPE_PREPARE 要求的裝置特定層面。 此例程是必要的。 準備 準備磁帶，方法是在磁帶類別驅動程式所傳遞的SRB中填入CDB。 如果裝置支援要求的作業，準備磁帶通常需要一個SRB。 準備填入 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 Prepare。

SetDriveParameters

SetDriveParameters 會 處理 IOCTL_TAPE_SET_DRIVE_PARAMS 要求的裝置特定層面。 此例程是必要的。 SetDriveParameters 會填入磁帶類別驅動程式所傳遞之 SRB 中的 CDB，以設定磁帶裝置的參數。 設定參數通常牽涉到一系列SRB來完成作業。 在 SetDriveParameters 填入指定的 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 SetDriveParameters。

SetMediaParameters

SetMediaParameters 會 處理 IOCTL_TAPE_SET_MEDIA_PARAMS 要求的裝置特定層面。 此例程是必要的。 SetMediaParameters 會填入磁帶類別驅動程式所傳遞之 SRB 中的 CDB，以設定磁帶的區塊大小。 設定區塊大小通常需要一個以上的SRB才能完成作業，從測試單元開始，迷你類別驅動程式在第一次呼叫例程時傳回TAPE_STATUS_CHECK_TEST_UNIT_READY要求。

在 SetMediaParameters 填入指定的 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 SetMediaParameters。

SetPosition

SetPosition 會處理 IOCTL_TAPE_SET_POSITION 要求的裝置特定層面。 此例程是必要的。 SetPosition 會藉由填入磁帶類別驅動程式所傳遞之 SRB 中的 CDB 來設定磁帶的位置。 設定位置通常需要一個SRB。 在 SetPosition 填入 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 SetPosition。 SetPosition 接著會傳回TAPE_STATUS_SUCCESS。

WriteMarks

WriteMarks 會 處理 IOCTL_TAPE_WRITE_MARKS 要求的裝置特定層面。 此例程是必要的。 WriteMark 會在 磁帶類別驅動程式所傳遞的 SRB 中填入 CDB，以將標記寫入磁帶。 寫入標記通常需要一個SRB來完成作業。 在 WriteMarks 填入 SRB 並傳回之後，磁帶類別驅動程式會將 SRB 傳送至裝置，並根據 SRB 的結果和 RetryFlags 的值，再次呼叫 WriteMarks。 WriteMarks 接著會傳回TAPE_STATUS_SUCCESS。

PreProcessReadWrite

PreProcessReadWrite 是選擇性的特殊用途例程，會執行讀取和寫入作業之前所需的任何裝置特定作業。 大部分磁帶迷你類別驅動程式不需要此例程。 PreProcessReadWrite 例程的活動是裝置專屬的活動。 例程可以使用類別驅動程序傳遞給它的資訊，來實作讀取和寫入的特殊前置處理。 如果磁碟驅動器的功能有限，驅動程式可能需要此例程來維持一致的狀態，例如。

如果磁帶迷你類別驅動程式在TAPE_INIT_DATA_EX結構中設定此例程的非 NULL 進入點，它會從其 DriverEntry 例程傳遞至 TapeClassInitialize，磁帶類別驅動程式會在磁帶裝置上的每個讀取和寫入作業之前呼叫它。 類別驅動程式不會預期此例程傳回任何資訊。

WMIOperations

WMIOperations 是磁帶類別驅動程式中所有 WMI 呼叫的常見進入點。 支援 WMI 的迷你驅動程式應該在 結構中設定函式指標成員 WMIOperations TAPE_INIT_DATA_EX，以指向迷你驅動程式 的TAPE_PROCESS_COMMAND_ROUTINE 例程。 迷你驅動程式應該在其 DriverEntry 例程中執行此動作，再呼叫 TapeClassInitialize。 如果迷你驅動程式不支援 WMI 作業，它應該將 TapeWMIOperations 欄位設定為 NULL。

磁帶類別驅動程式會將值指派給 TAPE_WMI_OPERATIONS 結構的成員，並在 CommandParameters 參數中將此結構傳遞至 minidriver 的 WMIOperations 例程。 如同其他迷你驅動程式例程， WMIOperations 會 填入、建立和初始化 SCSI 要求區塊， (SRB) 和命令描述元區塊 (CDB) 實作指定的 WMI 方法，並將控制權傳回磁帶類別驅動程式。 磁帶類別驅動程式接著會呼叫埠驅動程序來執行要求。

迷你驅動程式會傳回緩衝區中由 TAPE_WMI_OPERATIONS 結構 之 DataBuffer 成員指向的 WMI 數據。

規格需求

需求 值
目標平台 桌面
標頭 minitape.h (包含 Minitape.h)

另請參閱

SCSI_REQUEST_BLOCK

TAPE_STATUS

TapeClassAllocateSrbBuffer

TapeClassZeroMemory