ZwDeviceIoControlFile routine

The ZwDeviceIoControlFile routine sends a control code directly to a specified device driver, causing the corresponding driver to perform the specified operation.

Syntax


NTSTATUS 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_opt_  PVOID            InputBuffer,
  _In_      ULONG            InputBufferLength,
  _Out_opt_ PVOID            OutputBuffer,
  _In_      ULONG            OutputBufferLength
);

Parameters

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.

Return value

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:

STATUS_ACCESS_DENIED
STATUS_INSUFFICIENT_RESOURCES
STATUS_INVALID_HANDLE
STATUS_INVALID_PARAMETER
STATUS_OBJECT_TYPE_MISMATCH

Remarks

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".
 

Requirements

Target platform

Universal

Version

Available starting with Windows 2000.

Header

Ntifs.h (include Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE_LEVEL (see Remarks section)

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

FltDeviceIoControlFile
IoCallDriver
IoBuildAsynchronousFsdRequest
IoBuildDeviceIoControlRequest
IoBuildSynchronousFsdRequest
ZwClose
Using I/O Control Codes
ZwCreateFile
ZwOpenFile

 

 

Send comments about this topic to Microsoft

Show: