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

See theAssign drive letter sample.

Syntax

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

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 theCreateFile function. For more information, seeRemarks.

[in] dwIoControlCode

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

For a list of the control codes, see Remarks. The documentation for each control code provides usage detailsfor thelpInBuffer,nInBufferSize,lpOutBuffer, andnOutBufferSize parameters.

[in, optional] lpInBuffer

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

This parameter can beNULL ifdwIoControlCode specifiesan operation that does not require input data.

[in] nInBufferSize

The size of the input buffer, in bytes.

[out, optional] lpOutBuffer

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

This parameter can beNULL ifdwIoControlCode specifiesan operation that does not return data.

[in] nOutBufferSize

The size of the output buffer, in bytes.

[out, optional] 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, andlpBytesReturned is zero.

If the output buffer is too small to hold all of the data but can hold some entries, some drivers will returnas much data as fits. In this case, the call fails,GetLastError returnsERROR_MORE_DATA, andlpBytesReturned indicates the amountof data received. Your application should callDeviceIoControl again with the same operation,specifying a new starting point.

IflpOverlapped isNULL,lpBytesReturned cannot beNULL. Even when an operationreturns no output data andlpOutBuffer isNULL,DeviceIoControl makes use oflpBytesReturned. After such an operation, the value oflpBytesReturned is meaningless.

IflpOverlapped is notNULL,lpBytesReturned can beNULL. If this parameter is notNULL and the operation returns data,lpBytesReturned ismeaningless until the overlapped operation has completed. To retrieve the number of bytes returned, callGetOverlappedResult. IfhDevice is associated with an I/O completion port, you can retrieve the number ofbytes returned by callingGetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

A pointer to anOVERLAPPED structure.

IfhDevice was opened without specifyingFILE_FLAG_OVERLAPPED,lpOverlapped is ignored.

IfhDevice was opened with theFILE_FLAG_OVERLAPPED flag,the operation is performed as an overlapped (asynchronous) operation. In this case,lpOverlapped must point to a validOVERLAPPED structure that contains a handle to anevent object. Otherwise, the function fails in unpredictable ways.

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

Return value

If the operation completes successfully, the return value is nonzero (TRUE).

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 theCreateFile function with either the name of a device orthe name of the driver associated with a device. To specify a device name, use the following format:

\\.\DeviceName

DeviceIoControl can accept a handle to a specificdevice. For example, to open a handle to the logical drive A: withCreateFile, specify \\.\a:. Alternatively, you can use thenames \\.\PhysicalDrive0, \\.\PhysicalDrive1, and so on, to open handles to the physical drives on a system.

You should specify theFILE_SHARE_READ andFILE_SHARE_WRITE access flags when callingCreateFile to 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 otherCreateFile parameters as follows when opening a devicehandle:

• ThefdwCreate parameter must specifyOPEN_EXISTING.
• ThehTemplateFile parameter must beNULL.
• ThefdwAttrsAndFlags parameter can specifyFILE_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:

• CD-ROM Control Codes
• 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 usesDeviceIoControl, seeCalling DeviceIoControl.

Requirements

Requirement	Value
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

Assign drive letter sample