DeviceIoControl
Other versions of this page are also available for the following:
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
This function sends an IOCTL directly to a specified device driver, causing the corresponding device to perform the specified operation.
Syntax
BOOL DeviceIoControl(
HANDLE hDevice,
DWORD dwIoControlCode,
LPVOID lpInBuffer,
DWORD nInBufferSize,
LPVOID lpOutBuffer,
DWORD nOutBufferSize,
LPDWORD lpBytesReturned,
LPOVERLAPPED lpOverlapped
);
Parameters
- hDevice
[in] Handle to the device that is to perform the operation. To obtain a device handle, call the CreateFile function.
- dwIoControlCode
[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.
**** For Windows Embedded CE:** **
For more information on the **CTL\_CODE** macro, see [CTL\_CODE](aa914767\(v=winembedded.60\).md).**
- 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 dwIoControlCode parameter 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 Value
Nonzero indicates success. Zero indicates failure. To obtain extended error information, call the GetLastError function.
Remarks
For some IOCTLs, such as many of the IOCTL_DISK_* IOCTLs, the DeviceIoControl function does not change the lpBytesReturned parameter. These IOCTLs return any information to the input buffer specified by lpOutBuffer. DeviceIoControl only sets lpBytesReturned when the IOCTL writes to lpOutBuffer.
Requirements
| Header | winbase.h |
| Library | coredll.lib |
| Windows Embedded CE | Windows CE 1.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |