IOCTL_ATA_PASS_THROUGH IOCTL (ntddscsi.h)

發行項
02/27/2024

允許應用程式將幾乎任何 ATA 命令傳送至目標裝置，但有下列限制：

如果裝置目標類型的類別驅動程式存在，應用程式必須將要求傳送至類別驅動程式。因此，應用程式只能將此要求直接傳送至目標邏輯單元的系統埠驅動程式， (LU) 只有在連線到該 LU 的裝置類型沒有類別驅動程式時。系統埠驅動程式不會檢查是否已在處理傳遞要求之前由類別驅動程式宣告裝置。因此，如果應用程式略過已宣告裝置的類別驅動程式，並將該裝置的傳遞要求直接傳送至埠驅動程式，則類別驅動程式與應用程式之間可能會發生裝置控制衝突。
如果命令需要基礎驅動程式直接存取記憶體，則無法使用此要求。如果呼叫端的命令可能需要直接存取記憶體，請改用 IOCTL_ATA_PASS_THROUGH_DIRECT 。
應用程式不得嘗試以異步方式傳送傳遞要求。所有傳遞要求都必須是同步的。
應用程式不需要系統管理許可權，即可將傳遞要求傳送至裝置，但必須具有裝置的讀取/寫入許可權。

呼叫的應用程式會在 ATA_PASS_THROUGH_EX 結構中，為預期的命令提供 ATA 工作檔註冊內容。系統雙精度浮點數會緩衝所有數據傳輸。此要求通常用於傳輸少量的數據， (小於 16 KB) 。

主要程序代碼

輸入緩衝區

Irp-AssociatedIrp.SystemBuffer> 上的緩衝區應該包含一個ATA_PASS_THROUGH_EX結構，其中包含一組工作檔輸入緩存器，指出要執行的命令順序及其參數。呼叫端必須初始化此結構的所有成員，但埠驅動程式會填入 的 PathId、 TargetId 和 Lun 除外。如果是數據輸出命令，結構的 DataBufferOffset 成員必須指向包含要寫入之數據的快取對齊緩衝區。

輸入緩衝區長度

Parameters.DeviceIoControl.InputBufferLength 會指出 Irp->AssociatedIrp.SystemBuffer 緩衝區的大小以位元組為單位。如果內嵌 ATA 命令是寫入作業，輸入緩衝區的大小應該是 sizeof (ATA_PASS_THROUGH_EX ) 和 dataTransferLength 成員中 ATA_PASS_THROUGH_EX的值總和。下列虛擬程式碼範例示範如何計算緩衝區大小：

ULONG buffsize; // size of the buffer
ATA_PASS_THROUGH_EX hdr;
hdr.DataTransferLength = size in bytes of the data transfer
buffsize = sizeof (ATA_PASS_THROUGH_EX) + hdr.DataTransferLength

如果內嵌 ATA 命令是讀取作業或未涉及數據傳輸的裝置控制作業， InputBufferLength 應該等於 大小of (ATA_PASS_THROUGH_EX) 。

在任一情況下，如果 InputBufferLength 小於 sizeof (ATA_PASS_THROUGH_EX) ，埠驅動程式就會失敗 I/O 要求並傳回錯誤。

輸出緩衝區

埠驅動程式會使用 ATA_PASS_THROUGH_EX 結構來格式化傳回數據，並將數據儲存在 Irp-AssociatedIrp.SystemBuffer> 的緩衝區中。

埠驅動程式會在內嵌 ATA 命令完成時，填入 CurrentTaskFile 成員中存在裝置輸出緩存器中的值。如果命令是數據傳輸，埠驅動程式會將傳輸的數據儲存在快取對齊的緩衝區中，該緩衝區位於結構開頭的 DataBufferOffset 位元組位移。應用程式負責解譯輸出緩存器的內容，以判斷裝置傳回的錯誤。

輸出緩衝區長度

埠驅動程式會更新 ATA_PASS_THROUGH_EX 的 DataTransferLength 成員，以指出實際從裝置傳輸的數據量。如果內嵌 ATA 命令是寫入作業或未傳輸資料的裝置控制作業， OutputBufferLength 等於 sizeof (ATA_PASS_THROUGH_EX) 。如果內嵌 ATA 命令是讀取作業， OutputBufferLength 等於 sizeof (ATA_PASS_THROUGH_EX) + DataTransferLength。

狀態區塊

信息成員會設定為 Irp-AssociatedIrp.SystemBuffer> 輸出緩衝區中傳回的位元元組數目。 [狀態] 成員會設定為 [STATUS_SUCCESS]，或者如果ATA_PASS_THROUGH_EX中的輸入[狀態] 值未正確設定，則設定為 [STATUS_BUFFER_TOO_SMALL] 或 [STATUS_INVALID_PARAMETER]。

規格需求

需求	值
最低支援的用戶端	從 Windows Server 2003 開始提供。
標頭	ntddscsi.h (包含 Ntddscsi.h)

另請參閱

ATA_PASS_THROUGH_EX

IOCTL_ATA_PASS_THROUGH_DIRECT

共用方式為