deviceIoControl 函式 (ioapiset.h)

發行項
03/09/2023

將控制程式代碼直接傳送至指定的設備磁碟機，導致對應的裝置執行對應的作業。

語法

BOOL DeviceIoControl(
  [in]                HANDLE       hDevice,
  [in]                DWORD        dwIoControlCode,
  [in, optional]      LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out, optional]     LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out, optional]     LPDWORD      lpBytesReturned,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

參數

[in] hDevice

要在其中執行作業之裝置的控制碼。裝置通常是磁片區、目錄、檔案或資料流程。若要擷取裝置控制碼，請使用 CreateFile 函式。如需詳細資訊，請參閱＜備註＞。

[in] dwIoControlCode

作業的控制程式代碼。這個值會識別要執行的特定作業，以及要在其中執行的裝置類型。

如需控制程式代碼的清單，請參閱。每個控制項程式碼的檔都會提供 lpInBuffer、 nInBufferSize、 lpOutBuffer和 nOutBufferSize 參數的使用方式詳細資料。

[in, optional] lpInBuffer

輸入緩衝區的指標，其中包含執行作業所需的資料。此資料的格式取決於 dwIoControlCode 參數的值。

如果dwIoControlCode指定不需要輸入資料的作業，這個參數可以是Null。

[in] nInBufferSize

輸入緩衝區的大小，以位元組為單位。

[out, optional] lpOutBuffer

輸出緩衝區的指標，用來接收作業所傳回的資料。此資料的格式取決於 dwIoControlCode 參數的值。

如果dwIoControlCode指定不傳回資料的作業，這個參數可以是Null。

[in] nOutBufferSize

輸出緩衝區的大小 (以位元組為單位)。

[out, optional] lpBytesReturned

變數的指標，接收儲存在輸出緩衝區中的資料大小，以位元組為單位。

如果輸出緩衝區太小而無法接收任何資料，則呼叫會失敗， GetLastError 會 傳回ERROR_INSUFFICIENT_BUFFER，而 lpBytesReturned 為零。

如果輸出緩衝區太小而無法保存所有資料，但可以保存某些專案，某些驅動程式會傳回符合的資料量。在此情況下，呼叫會失敗， GetLastError 會傳回 ERROR_MORE_DATA，而 lpBytesReturned 表示收到的資料量。您的應用程式應該使用相同的作業再次呼叫 DeviceIoControl ，並指定新的起點。

如果 lpOverlapped 為 Null， 則 lpBytesReturned 不能是 Null。即使作業未傳回任何輸出資料， 且 lpOutBuffer 為 Null， DeviceIoControl 仍會使用 lpBytesReturned。在這類作業之後， lpBytesReturned 的值是無意義的。

如果 lpOverlapped 不是 Null， 則 lpBytesReturned 可以是 Null。如果此參數不是 Null ，而且作業會傳回資料， 則 lpBytesReturned 在重迭的作業完成之前是無意義的。若要擷取傳回的位元組數目，請呼叫 GetOverlappedResult。如果 hDevice 與 I/O 完成埠相關聯，您可以呼叫 GetQueuedCompletionStatus來擷取傳回的位元組數目。

[in, out, optional] lpOverlapped

重迭結構的指標。

如果 開啟 hDevice 而不指定 FILE_FLAG_OVERLAPPED，則會忽略 lpOverlapped 。

如果 hDevice 是以 FILE_FLAG_OVERLAPPED 旗標開啟，則會以重迭的 (非同步) 作業來執行。在此情況下， lpOverlapped 必須指向包含事件物件控制碼的有效 OVERLAPPED 結構。否則，函式會以無法預期的方式失敗。

針對重迭的作業， DeviceIoControl 會立即傳回，而且當作業完成時會發出事件物件的訊號。否則，除非作業完成或發生錯誤，否則函式不會傳回。

傳回值

如果作業順利完成，傳回值為非零 (TRUE) 。

如果作業失敗或擱置中，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

若要擷取裝置的控制碼，您必須使用裝置的名稱或與裝置相關聯的驅動程式名稱呼叫 CreateFile 函式。若要指定裝置名稱，請使用下列格式：

\\.\DeviceName

DeviceIoControl 可以接受特定裝置的控制碼。例如，若要開啟邏輯磁片磁碟機 A 的控制碼：使用 CreateFile，請指定 \\.\a：。或者，您可以使用名稱 \\.\PhysicalDrive0、\\.\PhysicalDrive1 等等，開啟系統上實體磁片磁碟機的控制碼。

呼叫CreateFile以開啟設備磁碟機控制碼時，您應該指定FILE_SHARE_READ和FILE_SHARE_WRITE存取旗標。不過，當您開啟通訊資源，例如序列埠時，您必須指定獨佔存取權。開啟裝置控制碼時，請使用其他 CreateFile 參數，如下所示：

fdwCreate參數必須指定OPEN_EXISTING。
hTemplateFile參數必須是Null。
fdwAttrsAndFlags參數可以指定FILE_FLAG_OVERLAPPED，指出傳回的控制碼可用於重迭的 (非同步) I/O 作業。

如需支援的控制項代碼清單，請參閱下列主題：

範例

如需使用 DeviceIoControl的範例，請參閱呼叫 DeviceIoControl。

規格需求


最低支援的用戶端	Windows XP
最低支援的伺服器	Windows Server 2003
目標平臺	Windows
標頭	ioapiset.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll