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

指向重叠结构的指针。

如果在未指定FILE_FLAG_OVERLAPPED的情况下打开 hDevice，则忽略 lpOverlapped。

如果使用FILE_FLAG_OVERLAPPED标志打开 hDevice，则操作将作为重叠 (异步) 操作执行。在这种情况下， 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)
Library	Kernel32.lib
DLL	Kernel32.dll