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
);

parameters

[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_BUFFERlpBytesReturned 为零。

如果输出缓冲区太小,无法容纳所有数据,但可以容纳一些条目,则某些驱动程序将返回尽可能多的数据。 在这种情况下,调用失败, GetLastError 返回 ERROR_MORE_DATAlpBytesReturned 指示接收的数据量。 应用程序应再次使用相同的操作调用 DeviceIoControl ,并指定一个新的起点。

如果 lpOverlapped 为 NULL,则 lpBytesReturned 不能为 NULL。 即使操作不返回输出数据且 lpOutBufferNULLDeviceIoControl 也会使用 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_READFILE_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

另请参阅

CreateEvent

CreateFile

设备输入和输出控制 (IOCTL)

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED

分配驱动器号示例