NtDeviceIoControlFile - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTIOAPI_H
/**
* The NtDeviceIoControlFile function sends a control code directly to a specified device driver, causing the corresponding driver to perform the specified operation.
*
* \param[in] FileHandle A handle to the file object representing the file or directory on which the specified action is to be performed.
* \param[in] Event A handle for a caller-created event. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.
* \param[in] ApcRoutine Address of a caller-supplied APC routine to be called when the requested operation completes. This parameter is optional and can be NULL.
* \param[in] ApcContext Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object.
* \param[out] IoStatusBlock Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation.
* \param[in] IoControlCode IOCTL_XXX code that indicates which device I/O control operation is to be carried out on, usually by the underlying device driver.
* \param[in] InputBuffer Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target driver.
* \param[in] InputBufferLength Size, in bytes, of the buffer at InputBuffer. This value is ignored if InputBuffer is NULL.
* \param[out] OutputBuffer Pointer to a caller-allocated output buffer in which information is returned from the target driver.
* \param[in] OutputBufferLength Size, in bytes, of the buffer at OutputBuffer. This value is ignored if OutputBuffer is NULL.
* \return NTSTATUS Successful or errant status.
* \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwdeviceiocontrolfile
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtDeviceIoControlFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_In_ ULONG IoControlCode,
_In_reads_bytes_opt_(InputBufferLength) PVOID InputBuffer,
_In_ ULONG InputBufferLength,
_Out_writes_bytes_opt_(OutputBufferLength) PVOID OutputBuffer,
_In_ ULONG OutputBufferLength
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwDeviceIoControlFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_In_ ULONG IoControlCode,
_In_reads_bytes_opt_(InputBufferLength) PVOID InputBuffer,
_In_ ULONG InputBufferLength,
_Out_writes_bytes_opt_(OutputBufferLength) PVOID OutputBuffer,
_In_ ULONG OutputBufferLength
);
View code on GitHub// ntddk.h
NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
View the official Windows Driver Kit DDI reference// ntifs.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtDeviceIoControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
View the official Windows Driver Kit DDI reference// ntifs.h
NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
View the official Windows Driver Kit DDI reference// winternl.h
__kernel_entry NTSTATUS NtDeviceIoControlFile(
[in] HANDLE FileHandle,
[in] HANDLE Event,
[in] PIO_APC_ROUTINE ApcRoutine,
[in] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG IoControlCode,
[in] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out] PVOID OutputBuffer,
[in] ULONG OutputBufferLength
);
View the official Win32 API referenceNo description available.
The ZwDeviceIoControlFile routine sends a control code directly to a specified device driver, causing the corresponding driver to perform the specified operation.
FileHandle [in]Handle returned by ZwCreateFile or ZwOpenFile for the file object representing the device to which the control information should be given or from which information should be returned. The file object must have been opened for asynchronous I/O if the caller specifies an Event, ApcRoutine, and an APC context (in ApcContext), or a completion context (in ApcContext). For I/O to an underlying mass-storage device, the file object must have been opened for Direct Access to Storage Device (DASD) access.
Event [in, optional]Handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.
ApcRoutine [in, optional]Address of an optional, caller-supplied APC routine to be called when the requested operation completes. This parameter can be NULL. It must be NULL if there is an I/O completion object associated with the file object.
ApcContext [in, optional]Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object. When the operation completes, either the APC context is passed to the APC, if one was specified, or the completion context is included as part of the completion message that the I/O Manager posts to the associated I/O completion object.
This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.
IoStatusBlock [out]Pointer to a variable that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the OutputBuffer is returned in the Information member.
IoControlCode [in]IOCTL_XXX code that indicates which device I/O control operation is to be carried out on, usually by the underlying device driver. The value of this parameter determines the format and required length of the InputBuffer and OutputBuffer, as well as which of the following parameter pairs are required. For detailed information about the system-defined, device-type-specific IOCTL_XXX codes, see the device technology-specific section of the Microsoft Windows Driver Kit (WDK) documentation and Device Input and Output Control Codes in the Microsoft Windows SDK documentation.
InputBuffer [in, optional]Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target device. If IoControlCode specifies an operation that does not require input data, this pointer can be NULL.
InputBufferLength [in]Size, in bytes, of the buffer at InputBuffer. If InputBuffer is NULL, set InputBufferLength to zero.
OutputBuffer [out, optional]Pointer to a caller-allocated output buffer in which information is returned from the target device. If IoControlCode specifies an operation that does not produce output data, this pointer can be NULL.
OutputBufferLength [in]Size, in bytes, of the buffer at OutputBuffer. If OutputBuffer is NULL, set OutputBufferLength to zero.
ZwDeviceIoControlFile returns STATUS_SUCCESS if the underlying driver(s) successfully carried out the requested operation. Otherwise, the return value can be an error status code propagated from an underlying driver. Possible error status codes include the following:
ZwDeviceIoControlFile provides a consistent view of the input and output data to the system and to kernel-mode drivers, while providing applications and underlying drivers with a device-dependent method of specifying a communications interface.
For more information about system-defined IOCTL_XXX codes, and about defining driver-specific IOCTL_XXX or FSCTL_XXX values, see Using I/O Control Codes in the Kernel Mode Architecture Guide and Device Input and Output Control Codes in the Microsoft Windows SDK documentation.
If the caller opened the file for asynchronous I/O (with neither FILE_SYNCHRONOUS_XXX create/open option set), the specified event, if any, will be set to the signaled state when the device control operation completes. Otherwise, the file object specified by FileHandle will be set to the signaled state. If an ApcRoutine was specified, it is called with the ApcContext and IoStatusBlock pointers.
Minifilters should use FltDeviceIoControlFile instead of ZwDeviceIoControlFile.
Callers of ZwDeviceIoControlFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.
If the call to the ZwDeviceIoControlFile function occurs in user mode, you should use the name "NtDeviceIoControlFile" instead of "ZwDeviceIoControlFile".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
The ZwDeviceIoControlFile routine sends a control code directly to a specified device driver, causing the corresponding driver to perform the specified operation.
FileHandle [in]Handle returned by ZwCreateFile or ZwOpenFile for the file object representing the device to which the control information should be given or from which information should be returned. The file object must have been opened for asynchronous I/O if the caller specifies an Event, ApcRoutine, and an APC context (in ApcContext), or a completion context (in ApcContext). For I/O to an underlying mass-storage device, the file object must have been opened for Direct Access to Storage Device (DASD) access.
Event [in, optional]Handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.
ApcRoutine [in, optional]Address of an optional, caller-supplied APC routine to be called when the requested operation completes. This parameter can be NULL. It must be NULL if there is an I/O completion object associated with the file object.
ApcContext [in, optional]Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object. When the operation completes, either the APC context is passed to the APC, if one was specified, or the completion context is included as part of the completion message that the I/O Manager posts to the associated I/O completion object.
This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.
IoStatusBlock [out]Pointer to a variable that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the OutputBuffer is returned in the Information member.
IoControlCode [in]IOCTL_Xxx code that indicates which device I/O control operation is to be carried out on, usually by the underlying device driver. The value of this parameter determines the format and required length of the InputBuffer and OutputBuffer, as well as which of the following parameter pairs are required. For detailed information about the system-defined, device-type-specific IOCTL_Xxx codes, see the device technology-specific section of the Microsoft Windows Driver Kit (WDK) documentation and Device Input and Output Control Codes.
InputBuffer [in, optional]Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target device. If IoControlCode specifies an operation that does not require input data, this pointer can be NULL.
InputBufferLength [in]Size, in bytes, of the buffer at InputBuffer. If InputBuffer is NULL, set InputBufferLength to zero.
OutputBuffer [out, optional]Pointer to a caller-allocated output buffer in which information is returned from the target device. If IoControlCode specifies an operation that does not produce output data, this pointer can be NULL.
OutputBufferLength [in]Size, in bytes, of the buffer at OutputBuffer. If OutputBuffer is NULL, set OutputBufferLength to zero.
ZwDeviceIoControlFile returns STATUS_SUCCESS if the underlying driver(s) successfully carried out the requested operation. Otherwise, the return value can be an error status code propagated from an underlying driver. Possible error status codes include the following:
ZwDeviceIoControlFile provides a consistent view of the input and output data to the system and to kernel-mode drivers, while providing applications and underlying drivers with a device-dependent method of specifying a communications interface.
For more information about system-defined IOCTL_Xxx codes, and about defining driver-specific IOCTL_Xxx or FSCTL_Xxx values, see Using I/O Control Codes and Device Input and Output Control Codes.
If the caller opened the file for asynchronous I/O (with neither FILE_SYNCHRONOUS_Xxx create/open option set), the specified event, if any, will be set to the signaled state when the device control operation completes. Otherwise, the file object specified by FileHandle will be set to the signaled state. If an ApcRoutine was specified, it is called with the ApcContext and IoStatusBlock pointers.
Minifilters should use FltDeviceIoControlFile instead of ZwDeviceIoControlFile.
Callers of ZwDeviceIoControlFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.
If the call to the ZwDeviceIoControlFile function occurs in user mode, you should use the name "NtDeviceIoControlFile" instead of "ZwDeviceIoControlFile".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
The ZwDeviceIoControlFile routine sends a control code directly to a specified device driver, causing the corresponding driver to perform the specified operation.
FileHandle [in]Handle returned by ZwCreateFile or ZwOpenFile for the file object representing the device to which the control information should be given or from which information should be returned. The file object must have been opened for asynchronous I/O if the caller specifies an Event, ApcRoutine, and an APC context (in ApcContext), or a completion context (in ApcContext). For I/O to an underlying mass-storage device, the file object must have been opened for Direct Access to Storage Device (DASD) access.
Event [in, optional]Handle for a caller-created event. If this parameter is supplied, the caller will be put into a wait state until the requested operation is completed and the given event is set to the Signaled state. This parameter is optional and can be NULL. It must be NULL if the caller will wait for the FileHandle to be set to the Signaled state.
ApcRoutine [in, optional]Address of an optional, caller-supplied APC routine to be called when the requested operation completes. This parameter can be NULL. It must be NULL if there is an I/O completion object associated with the file object.
ApcContext [in, optional]Pointer to a caller-determined context area. This parameter value is used as the APC context if the caller supplies an APC, or is used as the completion context if an I/O completion object has been associated with the file object. When the operation completes, either the APC context is passed to the APC, if one was specified, or the completion context is included as part of the completion message that the I/O Manager posts to the associated I/O completion object.
This parameter is optional and can be NULL. It must be NULL if ApcRoutine is NULL and there is no I/O completion object associated with the file object.
IoStatusBlock [out]Pointer to a variable that receives the final completion status and information about the operation. For successful calls that return data, the number of bytes written to the OutputBuffer is returned in the Information member.
IoControlCode [in]IOCTL_XXX code that indicates which device I/O control operation is to be carried out on, usually by the underlying device driver. The value of this parameter determines the format and required length of the InputBuffer and OutputBuffer, as well as which of the following parameter pairs are required. For detailed information about the system-defined, device-type-specific IOCTL_XXX codes, see the device technology-specific section of the Microsoft Windows Driver Kit (WDK) documentation and Device Input and Output Control Codes in the Microsoft Windows SDK documentation.
InputBuffer [in, optional]Pointer to a caller-allocated input buffer that contains device-specific information to be given to the target device. If IoControlCode specifies an operation that does not require input data, this pointer can be NULL.
InputBufferLength [in]Size, in bytes, of the buffer at InputBuffer. If InputBuffer is NULL, set InputBufferLength to zero.
OutputBuffer [out, optional]Pointer to a caller-allocated output buffer in which information is returned from the target device. If IoControlCode specifies an operation that does not produce output data, this pointer can be NULL.
OutputBufferLength [in]Size, in bytes, of the buffer at OutputBuffer. If OutputBuffer is NULL, set OutputBufferLength to zero.
ZwDeviceIoControlFile returns STATUS_SUCCESS if the underlying driver(s) successfully carried out the requested operation. Otherwise, the return value can be an error status code propagated from an underlying driver. Possible error status codes include the following:
ZwDeviceIoControlFile provides a consistent view of the input and output data to the system and to kernel-mode drivers, while providing applications and underlying drivers with a device-dependent method of specifying a communications interface.
For more information about system-defined IOCTL_XXX codes, and about defining driver-specific IOCTL_XXX or FSCTL_XXX values, see Using I/O Control Codes in the Kernel Mode Architecture Guide and Device Input and Output Control Codes in the Microsoft Windows SDK documentation.
If the caller opened the file for asynchronous I/O (with neither FILE_SYNCHRONOUS_XXX create/open option set), the specified event, if any, will be set to the signaled state when the device control operation completes. Otherwise, the file object specified by FileHandle will be set to the signaled state. If an ApcRoutine was specified, it is called with the ApcContext and IoStatusBlock pointers.
Minifilters should use FltDeviceIoControlFile instead of ZwDeviceIoControlFile.
Callers of ZwDeviceIoControlFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.
Note If the call to the ZwDeviceIoControlFile function occurs in user mode, you should use the name "NtDeviceIoControlFile" instead of "ZwDeviceIoControlFile".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
Deprecated. Builds descriptors for the supplied buffer(s) and passes the untyped data to the device driver associated with the file handle. NtDeviceIoControlFile is superseded by DeviceIoControl.
FileHandle [in]Open file handle to the file or device to which the control information should be given.
Event [in]A handle to an event to be set to the signaled state when the operation completes. This parameter can be NULL.
ApcRoutine [in]Procedure to be invoked once the operation completes. This parameter can be NULL. For more information on Asynchronous Procedure Calls (APCs), see Asynchronous Procedure Calls.
ApcContext [in]A pointer to pass to ApcRoutine when the operation completes. This parameter is required if an ApcRoutine is specified.
IoStatusBlock [out]Variable to receive the final completion status and information about the operation. Service calls that return information return the length of the data that is written to the output buffer in the Information field of this variable.
IoControlCode [in]Code that indicates which device I/O control function is to be executed.
InputBuffer [in]A pointer to a buffer that contains the information to be given to the target device. This parameter can be NULL. This information is device-dependent.
InputBufferLength [in]Length of the InputBuffer in bytes. If the buffer is not supplied, then this value is ignored.
OutputBuffer [out]A pointer to a buffer that is to receive the device-dependent return information from the target device. This parameter can be NULL.
OutputBufferLength [in]Length of the OutputBuffer in bytes. If the buffer is not supplied, then this value is ignored.
The various NTSTATUS values are defined in NTSTATUS.H, which is distributed with the Windows DDK.
| Return code | Description |
|---|---|
| STATUS_SUCCESS | The control operation was properly queued to the I/O system. Once the operation completes, the status can be determined by examining the Status field of the I/O status block. |
The NtDeviceIoControlFile service is a device-dependent interface that extends the control that applications have over various devices within the system. This API provides a consistent view of the input and output data to the system while still providing the application and the driver a device-dependent method of specifying a communications interface.
The type of access to the file that the caller needs is dependent on the actual operation being performed.
Once the service is complete the Event, if specified, is set to the signaled state. If no Event parameter is specified, then the file object specified by the FileHandle is set to the signaled state. If an ApcRoutine is specified, it is invoked with the ApcContext and the IoStatusBlock as its arguments.
Because there is no import library for this function, you must use GetProcAddress.
This function is documented in Windows Driver Kit here, here, and here.
Function NtDeviceIoControlFile sends IOCTL_* control code to Device Driver. It is primary (but not the best) solution to communicate between application and Device Driver.
HANDLE to Device Object opened as a file.
Optional HANDLE to Event Object signalled on the end of processing request.
Optional pointer to user's APC Routine called on the end of processing request.
User's parameter to ApcRoutine.
IO result of call.
IO Control code [IOCTL_*].
User's allocated buffer with input data.
Length of InputBuffer, in bytes.
User's allocated buffer for result data.
Length of OutputBuffer, in bytes.
See also NtFsControlFile.