Функция DeviceIoControl (ioapiset.h)

Статья
03/09/2023

Отправляет код элемента управления непосредственно в указанный драйвер устройства, в результате чего соответствующее устройство выполнит соответствующую операцию.

См. пример назначения буквы диска.

Синтаксис

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
);

Параметры

[in] hDevice

Дескриптор устройства, на котором выполняется операция. Устройство обычно является томом, каталогом, файлом или потоком. Чтобы получить дескриптор устройства, используйте функцию CreateFile . Дополнительные сведения см. в подразделе "Примечания".

[in] dwIoControlCode

Код элемента управления для операции. Это значение определяет конкретную операцию, которую необходимо выполнить, и тип устройства, на котором она выполняется.

Список кодов элементов управления см. в разделе Примечания. Документация по каждому коду элемента управления содержит сведения об использовании параметров lpInBuffer, nInBufferSize, lpOutBuffer и nOutBufferSize .

[in, optional] lpInBuffer

Указатель на входной буфер, содержащий данные, необходимые для выполнения операции. Формат этих данных зависит от значения параметра dwIoControlCode .

Этот параметр может иметь значение NULL, если dwIoControlCode указывает операцию, которая не требует входных данных.

[in] nInBufferSize

Размер входного буфера в байтах.

[out, optional] lpOutBuffer

Указатель на выходной буфер, который получает данные, возвращаемые операцией. Формат этих данных зависит от значения параметра dwIoControlCode .

Этот параметр может иметь значение NULL, если dwIoControlCode указывает операцию, которая не возвращает данные.

[in] nOutBufferSize

Размер выходного буфера в байтах.

[out, optional] lpBytesReturned

Указатель на переменную, которая получает размер данных, хранящихся в выходном буфере, в байтах.

Если выходной буфер слишком мал для получения каких-либо данных, вызов завершается ошибкой, GetLastError возвращает ERROR_INSUFFICIENT_BUFFER, а значение lpBytesReturned равно нулю.

Если выходной буфер слишком мал для хранения всех данных, но может содержать некоторые записи, некоторые драйверы возвращают столько данных, сколько подходит. В этом случае вызов завершается сбоем, GetLastError возвращает ERROR_MORE_DATA, а lpBytesReturned указывает объем полученных данных. Приложение должно снова вызвать DeviceIoControl с той же операцией, указав новую начальную точку.

Если lpOverlapped имеет значение NULL, lpBytesReturned не может иметь значение NULL. Даже если операция не возвращает выходные данные, а lpOutBuffer имеет значение NULL, DeviceIoControl использует lpBytesReturned. После такой операции значение lpBytesReturned не имеет смысла.

Если значение lpOverlapped не равно NULL, lpBytesReturned может иметь значение NULL. Если этот параметр не имеет значения NULL и операция возвращает данные, функция lpBytesReturned не имеет смысла, пока не завершится перекрывающаяся операция. Чтобы получить количество возвращенных байтов, вызовите Метод GetOverlappedResult. Если hDevice связан с портом завершения ввода-вывода, можно получить количество возвращаемых байтов, вызвав Метод GetQueuedCompletionStatus.

[in, out, optional] lpOverlapped

Указатель на структуру OVERLAPPED .

Если hDevice был открыт без указания FILE_FLAG_OVERLAPPED, lpOverlapped игнорируется.

Если hDevice был открыт с флагом FILE_FLAG_OVERLAPPED , операция выполняется как перекрываемая (асинхронная) операция. В этом случае lpOverlapped должен указывать на допустимую структуру OVERLAPPED , содержащую дескриптор объекта события. В противном случае функция завершается сбоем непредсказуемым образом.

Для перекрывающихся операций DeviceIoControl возвращает немедленно, а объект события получает сигнал о завершении операции. В противном случае функция не возвращается, пока операция не будет завершена или не возникнет ошибка.

Возвращаемое значение

Если операция завершается успешно, возвращается ненулевое значение (TRUE).

Если операция завершается сбоем или находится в состоянии ожидания, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Чтобы получить дескриптор устройства, необходимо вызвать функцию CreateFile с именем устройства или именем драйвера, связанного с устройством. Чтобы указать имя устройства, используйте следующий формат:

\\.\DeviceName

DeviceIoControl может принимать дескриптор определенному устройству. Например, чтобы открыть дескриптор для логического диска A: с помощью CreateFile, укажите \\.\a:. Кроме того, можно использовать имена \\.\PhysicalDrive0, \\.\PhysicalDrive1 и т. д., чтобы открыть дескрипторы для физических дисков в системе.

При вызове CreateFile необходимо указать флаги доступа FILE_SHARE_READ и FILE_SHARE_WRITE, чтобы открыть дескриптор драйвера устройства. Однако при открытии ресурса связи, например последовательного порта, необходимо указать монопольный доступ. При открытии дескриптора устройства используйте другие параметры CreateFile следующим образом:

Параметр fdwCreate должен указывать OPEN_EXISTING.
Параметр hTemplateFile должен иметь значение NULL.
Параметр fdwAttrsAndFlags может указывать FILE_FLAG_OVERLAPPED , указывающий, что возвращенный дескриптор может использоваться в перекрывающихся (асинхронных) операциях ввода-вывода.

Списки поддерживаемых кодов элементов управления см. в следующих разделах:

Примеры

Пример использования DeviceIoControl см. в разделе Вызов DeviceIoControl.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP
Минимальная версия сервера	Windows Server 2003
Целевая платформа	Windows
Header	ioapiset.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll