DeviceIoControl 函数详细解析

前言：

    最近需要对Windows中的设备进行编程操作，其中涉及到非常重要的函数DeviceIoControl，在使用的时候也比较的复杂，国内这一块中文资料比较少，在学习之余顺便将其翻译出来，以供参考，如有错误，欢迎指正。lcb0281@163点com 

MSDN原文地址：DeviceIoControl function 

    DeviceIoControl 将控制代码直接发送到指定的设备驱动程序，使相应的设备执行相应的操作。

句法：

BOOL WINAPI DeviceIoControl(
  _In_        HANDLE       hDevice,
  _In_        DWORD        dwIoControlCode,
  _In_opt_    LPVOID       lpInBuffer,
  _In_        DWORD        nInBufferSize,
  _Out_opt_   LPVOID       lpOutBuffer,
  _In_        DWORD        nOutBufferSize,
  _Out_opt_   LPDWORD      lpBytesReturned,
  _Inout_opt_ LPOVERLAPPED lpOverlapped
);

参数：

hDevice [in]
    需要执行操作的设备句柄。该设备通常是卷，目录，文件或流，使用 CreateFile 函数打开获取设备句柄。具体的见备注
dwIoControlCode [in]
    操作的控制代码，该值标识要执行的特定操作以及执行该操作的设备的类型，有关控制代码的列表，请参考备注。每个控制代码的文档都提供了lpInBuffer，nInBufferSize，lpOutBuffer和nOutBufferSize参数的使用细节。
lpInBuffer [in, optional]
    （可选）指向输入缓冲区的指针。这些数据的格式取决于dwIoControlCode参数的值。如果dwIoControlCode指定不需要输入数据的操作，则此参数可以为NULL。
nInBufferSize [in]
    输入缓冲区以字节为单位的大小。单位为字节。
lpOutBuffer [out, optional]
    （可选）指向输出缓冲区的指针。这些数据的格式取决于dwIoControlCode参数的值。如果dwIoControlCode指定不返回数据的操作，则此参数可以为NULL。
nOutBufferSize [in]
    输出缓冲区以字节为单位的大小。单位为字节。
lpBytesReturned [out, optional]
    （可选）指向一个变量的指针，该变量接收存储在输出缓冲区中的数据的大小。如果输出缓冲区太小，无法接收任何数据，则GetLastError返回ERROR_INSUFFICIENT_BUFFER,错误代码122(0x7a)，此时lpBytesReturned是零。
    如果输出缓冲区太小而无法保存所有数据，但可以保存一些条目，某些驱动程序将返回尽可能多的数据,在这种情况下，调用失败，GetLastError返回ERROR_MORE_DATA,错误代码234，lpBytesReturned指示接收到的数据量。您的应用程序应该再次使用相同的操作调用DeviceIoControl，指定一个新的起点。
    如果lpOverlapped为NULL，则lpBytesReturned不能为NULL。 即使操作没有返回输出数据并且lpOutBuffer为NULL，DeviceIoControl也会使用lpBytesReturned。在这样的操作之后，lpBytesReturned的值是没有意义的。
    如果lpOverlapped不为NULL，则lpBytesReturned可以为NULL。 如果此参数不为NULL并且操作返回数据，则在重叠操作完成之前，lpBytesReturned是无意义的。要检索返回的字节数，请调用GetOverlappedResult,如果hDevice与I / O完成端口相关联，则可以检索通过调用GetQueuedCompletionStatus返回的字节数。
lpOverlapped [in, out, optional]
    （可选）指向OVERLAPPED结构的指针,
  如果在未指定FILE_FLAG_OVERLAPPED的情况下打开hDevice，则忽略lpOverlapped。
  如果使用FILE_FLAG_OVERLAPPED标志打开hDevice，则该操作将作为重叠（异步）操作执行。在这种情况下，lpOverlapped必须指向包含事件对象句柄的有效OVERLAPPED结构。 否则，该功能将以不可预知的方式失败。
    对于重叠操作，DeviceIoControl会立即返回，并在操作完成时通知事件对象。 否则，该功能在操作完成或发生错误之前不会返回。

返回值:
    如果操作成功完成，DeviceIoControl将返回一个非零值。

    如果操作失败或正在等待，则DeviceIoControl返回零。 要获得扩展的错误信息，请调用GetLastError。

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

DeviceIoControl可以接受特定设备的句柄。 对于硬盘来说，可能为以下几种形式：

  对于物理驱动器x，形式为 \\.\PhysicalDriveX ，编号从0开始，例如：

对于逻辑分区（卷），形式为 \\.\X: ，例如：

    调用CreateFile打开设备驱动程序的句柄时，应指定FILE_SHARE_READ和FILE_SHARE_WRITE访问标志。但是，当您打开通信资源（如串行端口）时，必须指定独占访问权限。 打开设备句柄时使用其他CreateFile参数，如下所示：
     (a)fdwCreate参数必须指定OPEN_EXISTING。
     (b)hTemplateFile参数必须为NULL。

    (c)fdwAttrsAndFlags参数可指定FILE_FLAG_OVERLAPPED，以指示返回的句柄可用于重叠（异步）I / O操作。

有关支持的控制代码列表，请参阅以下主题：
    Communications Control Codes
    Device Management Control Codes
    Directory Management Control Codes
    Disk Management Control Codes
    File Management Control Codes
    Power Management Control Codes
    Volume Management Control Codes

实例：
    有关使用DeviceIoControl的示例，请参阅调用DeviceIoControl。

其他链接：

    CreateEvent
    CreateFile
    Device Input and Output Control (IOCTL)
    GetOverlappedResult
    GetQueuedCompletionStatus

    OVERLAPPED

                                                                                                                          Wen Lee

                                                                                                                         2018.04.28

今天的文章DeviceIoControl 函数详细解析分享到此就结束了，感谢您的阅读。