共用方式為


deviceIoControl 函式 (ioapiset.h)

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

請參閱 指派驅動器號範例

語法

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

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

如需控制程式代碼的清單,請參閱。 每個控件程式代碼的文件都會提供 lpInBuffernInBufferSizelpOutBuffernOutBufferSize 參數的使用方式詳細數據。

[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 ,並指定新的起點。

如果 lpOverlappedNULL則 lpBytesReturned 不能是 NULL。 即使作業未傳回任何輸出數據且 lpOutBufferNULL,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

另請參閱

CreateEvent

CreateFile

IOCTL) (裝置輸入和輸出控制

GetOverlappedResult

GetQueuedCompletionStatus

重疊

指派驅動器號範例