deviceIoControl 函式 (ioapiset.h)

發行項
03/05/2024

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

語法

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