deviceIoControl 函数 (ioapiset.h)

项目
08/24/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

指向 OVERLAPPED 结构的指针。

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

如果使用 FILE_FLAG_OVERLAPPED 标志打开 hDevice，则此操作将作为重叠（异步）操作执行。在这种情况下，lpOverlapped 必须指向包含事件对象句柄的有效 OVERLAPPED 结构。否则，函数会以不可预知的方式失败。

对于重叠操作，DeviceIoControl 会立即返回，并在操作完成时向事件对象发出信号。否则，在操作完成或发生错误之前，函数不会返回。

返回值

如果操作成功完成，则返回值为非零 (TRUE) 。

如果操作失败或挂起，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

若要检索设备的句柄，必须使用设备的名称或与设备关联的驱动程序的名称调用 CreateFile 函数。若要指定设备名称，请使用以下格式：

\\.\DeviceName

DeviceIoControl 可以接受特定设备的句柄。例如，若要使用 CreateFile 打开逻辑驱动器 A：的句柄，请指定 \\.\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