DeviceIoControl

应用程序和驱动程序的通信过程是：应用程序使用CreateFile函数打开设备，然后用DeviceIoControl与驱动程序进行通信，包括读和写两种操作。还可以用ReadFile读数据用WriteFile写数据。操作完毕时用CloseHandle关闭设备。我们比较常用的就是用DeviceIoControl对设备进行读写操作。先看看DeviceIoControl是怎么定义的：

BOOL DeviceIoControl(
  HANDLE hDevice, 
  DWORD dwIoControlCode, 
  LPVOID lpInBuffer, 
  DWORD nInBufferSize, 
  LPVOID lpOutBuffer, 
  DWORD nOutBufferSize, 
  LPDWORD lpBytesReturned, 
  LPOVERLAPPED lpOverlapped
);

Parameters（参数）

hDevice （CreateFile返回的设备句柄）

[in] Handle to the device that is to perform the operation. To obtain a device handle, call the CreateFile function.

dwIoControlCode （应用程序调用驱动程序的控制命令，就是IOCTL_XXX IOCTLs ）

[in] IOCTL for the operation. This value identifies the specific operation to perform and the type of device on which to perform the operation. There are no specific values defined for the dwIoControlCode parameter. However, you can define custom IOCTL_XXX IOCTLs with the CTL_CODE macro. You can then advertise these IOCTLs and an application can use these IOCTLs with DeviceIoControl to perform the driver-specific functions.

lpInBuffer （应用程序传递给驱动程序的数据缓冲区地址）

[in] Long pointer to a buffer that contains the data required to perform the operation. Set to NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

nInBufferSize （应用程序传递给驱动程序的数据缓冲区大小，字节数）

[in] Size, in bytes, of the buffer pointed to by lpInBuffer.

lpOutBuffer （驱动程序返回给应用程序的数据缓冲区地址）

[out] Long pointer to a buffer that receives the output data for the operation. Set to NULL if the dwIoControlCodeparameter specifies an operation that does not produce output data.

nOutBufferSize （驱动程序返回给应用程序的数据缓冲区大小，字节数）

[out] Size, in bytes, of the buffer pointed to by lpOutBuffer.

lpBytesReturned （驱动程序实际返回给应用程序的数据字节数地址）

[out] Long pointer to a variable that receives the size, in bytes, of the data stored in lpOutBuffer. The DeviceIoControl function may unnecessarily use this parameter. For example, if an operation does not produce data for lpOutBuffer and lpOutBuffer is NULL, the value of lpBytesReturned is meaningless.

lpOverlapped （重叠操作结构）

[in] Ignored; set to NULL.

Return Values（返回值）

Nonzero indicates success. Zero indicates failure. To obtain extended error information, call the GetLastErrorfunction. （非0成功，0失败）

具体使用我们看看列子：

1，向设备传递数据，我们定义一个函数来实现

bool CDeviceOperDlg::SendKeyData(HANDLE handle, BYTE *bData, int iSize)
{
 ULONG nOutput;
 BYTE bTemp[512];

 //将数据放置到发送数组
 memset(bTemp,0,sizeof(bTemp));
 memcpy(bTemp,&bData[0],iSize);
 //向设备发送
 if (!DeviceIoControl(handle,         
       ATST2004_IOCTL_WRITE,     //根据具体的设备有相关的定义
       bTemp,                                        //向设备传递的数据地址
       iSize,                                            //数据大小，字节数
       NULL,                                          //没有返回的数据，置为NULL
       0,                                                  //没有返回的数据，置为0

       &nOutput,
       NULL)
    )
 {
  return false;
 }

 return true;
}

2，从设备读取数据

bool CDeviceOperDlg::ReviceKeyData(HANDLE handle, BYTE *bData, int iSize)
{

 ULONG nOutput;
 BYTE bTemp[512];
 //数组清零
 memset(bTemp,0,sizeof(bTemp));
 //向设备发送
 if (!DeviceIoControl(handle,
       ATST2004_IOCTL_READ,           //根据具体的设备有相关的定义
       NULL,                                              //没有向设备传递的数据，置为NULL
       0,                                                      //没有向设备传递的数据，置为NULL
       bTemp,                                           //读取设备的数据返回地址
       iSize,                                               //读取数据的字节数
       &nOutput,
       NULL)
    )
 {
  return false;
 }
 //放置到公用数组
 memcpy(&bData[0],&bTemp[0],iSize);
 return true;
}

---

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开始，例如：

名称	含义
\\.\PhysicalDrive0	打开第一个物理驱动器
\\.\PhysicalDrive1	打开第二个物理驱动器

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

名称	含义
\\.\A:	打开A盘（软驱）
\\.\C:	打开C盘（磁盘逻辑分区）

    调用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

---

Sends a control code directly to a specified device driver, causing the corresponding device to perform the corresponding operation.

Syntax

C++复制

BOOL DeviceIoControl(
  HANDLE       hDevice,
  DWORD        dwIoControlCode,
  LPVOID       lpInBuffer,
  DWORD        nInBufferSize,
  LPVOID       lpOutBuffer,
  DWORD        nOutBufferSize,
  LPDWORD      lpBytesReturned,
  LPOVERLAPPED lpOverlapped
);

Parameters

hDevice

A handle to the device on which the operation is to be performed. The device is typically a volume, directory, file, or stream. To retrieve a device handle, use the CreateFile function. For more information, see Remarks.

dwIoControlCode

The control code for the operation. This value identifies the specific operation to be performed and the type of device on which to perform it.

For a list of the control codes, see Remarks. The documentation for each control code provides usage details for the lpInBuffer, nInBufferSize, lpOutBuffer, and nOutBufferSize parameters.

lpInBuffer

A pointer to the input buffer that contains the data required to perform the operation. The format of this data depends on the value of the dwIoControlCode parameter.

This parameter can be NULL if dwIoControlCode specifies an operation that does not require input data.

nInBufferSize

The size of the input buffer, in bytes.

lpOutBuffer

A pointer to the output buffer that is to receive the data returned by the operation. The format of this data depends on the value of the dwIoControlCode parameter.

This parameter can be NULL if dwIoControlCode specifies an operation that does not return data.

nOutBufferSize

The size of the output buffer, in bytes.

lpBytesReturned

A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

If the output buffer is too small to receive any data, the call fails, GetLastError returnsERROR_INSUFFICIENT_BUFFER, and lpBytesReturned is zero.

If the output buffer is too small to hold all of the data but can hold some entries, some drivers will return as much data as fits. In this case, the call fails, GetLastError returns ERROR_MORE_DATA, and lpBytesReturned indicates the amount of data received. Your application should call DeviceIoControlagain with the same operation, specifying a new starting point.

If lpOverlapped is NULL, lpBytesReturned cannot be NULL. Even when an operation returns no output data and lpOutBuffer is NULL, DeviceIoControl makes use of lpBytesReturned. After such an operation, the value of lpBytesReturned is meaningless.

If lpOverlapped is not NULL, lpBytesReturned can be NULL. If this parameter is not NULL and the operation returns data, lpBytesReturned is meaningless until the overlapped operation has completed. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

A pointer to an OVERLAPPED structure.

If hDevice was opened without specifying FILE_FLAG_OVERLAPPED, lpOverlapped is ignored.

If hDevice was opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. In this case, lpOverlapped must point to a valid OVERLAPPEDstructure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.

For overlapped operations, DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed. Otherwise, the function does not return until the operation has been completed or an error occurs.

Return Value

If the operation completes successfully, the return value is nonzero.

If the operation fails or is pending, the return value is zero. To get extended error information, callGetLastError.

Remarks

To retrieve a handle to the device, you must call the CreateFile function with either the name of a device or the name of the driver associated with a device. To specify a device name, use the following format:

\.<i>DeviceName

DeviceIoControl can accept a handle to a specific device. For example, to open a handle to the logical drive A: with CreateFile, specify \.\a:. Alternatively, you can use the names \.\PhysicalDrive0, \.\PhysicalDrive1, and so on, to open handles to the physical drives on a system.

You should specify the FILE_SHARE_READ and FILE_SHARE_WRITE access flags when calling CreateFileto open a handle to a device driver. However, when you open a communications resource, such as a serial port, you must specify exclusive access. Use the other CreateFile parameters as follows when opening a device handle:

• The fdwCreate parameter must specify OPEN_EXISTING.
• The hTemplateFile parameter must be NULL.
• The fdwAttrsAndFlags parameter can specify FILE_FLAG_OVERLAPPED to indicate that the returned handle can be used in overlapped (asynchronous) I/O operations.

For lists of supported control codes, see the following topics:

• 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

Examples

For an example that uses DeviceIoControl, see Calling DeviceIoControl.

Requirements

Minimum supported client	Windows XP
Minimum supported server	Windows Server 2003
Target Platform	Windows
Header	ioapiset.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

See Also

CreateEvent

CreateFile

Device Input and Output Control (IOCTL)

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED