Функция DeviceIoControl отправляет управляющий код непосредственно указанному драйверу устройства, заставляя соответствующее устройство выполнить соответствующую операцию.
Синтаксис
BOOL DeviceIoControl( HANDLE hDevice, DWORD dwIoControlCode, LPVOID lpInBuffer, DWORD nInBufferSize, LPVOID lpOutBuffer, DWORD nOutBufferSize, LPDWORD lpBytesReturned, LPOVERLAPPED lpOverlapped ); |
Параметры
hDevice
[in] Дескриптор устройства на котором должна выполниться операция. Это устройство - обычно том, каталог, файл или поток. Чтобы извлечь данные о дескрипторе устройства, используйте функцию CreateFile. Дополнительную информацию, см. в разделе Замечания.
dwIoControlCode
[in] Управляющий код для операции. Это значение идентифицирует конкретную операцию для выполнения и тип устройства, на котором она должна осуществиться.Список управляющих кодов см. в разделе Замечания. Документация для каждого управляющего кода рассматривает детали использования параметров lpInBuffer, nInBufferSize, lpOutBuffer и nOutBufferSize.
lpInBuffer
[in] Указатель на буфер ввода данных, который содержит данные необходимые, чтобы, выполнить операцию. Формат этих данных зависит от значения параметра dwIoControlCode.Этот параметр может быть ПУСТО (NULL), если dwIoControlCode определяет операцию, которая не требует ввода данных.
nInBufferSize
[in] Размер буфера ввода данных, в байтах.lpOutBuffer
[out] Указатель на буфер вывода данных, который должен получить данные, возвращенные операцией. Формат этих данных зависит от значения параметра dwIoControlCode.Этот параметр может быть ПУСТО (NULL), если dwIoControlCode определяет операцию, которая не возвращает данные.
nOutBufferSize
[in] Размер буфера вывода данных, в байтах.lpBytesReturned
[out] Указатель на переменную, которая получает размер данных, сохраненных в буфере вывода данных, в байтах.Если буфер вывода данных является слишком маленьким, чтобы получить какие-либо данные, вызов завершается ошибкой, 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 связан с портом завершения ввода-вывода данных (I/O), Вы можете извлечь число возвращаемых данных при помощи вызова функции GetQueuedCompletionStatus.
lpOverlapped
[in] Указатель на структуру OVERLAPPED.Если параметр hDevice открывался без определения FILE_FLAG_OVERLAPPED, параметр lpOverlapped игнорируется.
Если параметр hDevice открывался с флажком FILE_FLAG_OVERLAPPED, операция выполняется как перекрывающая (асинхронная) операция. В этой ситуации, параметр lpOverlapped должен указать на допустимую структуру OVERLAPPED, которая содержит дескриптор объекта события. В противном случае, функция завершается ошибкой непредсказуемыми способами.
Для асинхронных операций, DeviceIoControl возвращает значение немедленно, а объект события подает сигнал, когда операция завершается. В противном случае, функция не возвращает значение до тех пор, пока операция не завершится или не произойдет ошибка.
Возвращаемые значения
Если операция завершается успешно, DeviceIoControl возвращает ненулевое значение.
Если операция завершается ошибкой, DeviceIoControl возвращает нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.
Замечания
Чтобы извлечь данные о дескрипторе устройства, Вы должны вызвать функцию CreateFile или с именем устройства или с именем драйвера, связанного с устройством. Чтобы определить имя устройства, используйте ниже перечисленный формат:
\\.\DeviceName |
Функция DeviceIoControl может принять дескриптор конкретного устройства. Например, чтобы открыть дескриптор логического диска A: при помощи функции CreateFile, задайте \\.\a:. Альтернативно, Вы можете использовать имена \\.\PhysicalDrive0, \\.\PhysicalDrive1 и так далее, чтобы открывать дескрипторы на физические диски в системе.
Windows Me/98/95: DeviceIoControl может принять только дескриптор виртуального драйвера устройства. Например, чтобы открыть дескриптор системы VxD при помощи CreateFile, задайте \\.\vwin32.
Вам следует определить флажки доступа FILE_SHARE_READ и FILE_SHARE_WRITE при вызове CreateFile, чтобы открыть дескриптор драйвера устройства. Однако, когда Вы открываете коммуникационный ресурс (ресурс обмена данными), типа последовательного порта, Вы должны определить монопольный доступ нему. При открытии дескриптора устройства, используйте остальные параметры CreateFile как указано ниже:
Список поддерживаемых управляющих кодов, см. в темах перечисленных ниже:
Примеры, которые используют функцию DeviceIoControl, смотри в нижеперечисленных статьях:
Смотри также
Обзор Управление устройствами, CreateEvent, CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED
|
Размещение и совместимость DeviceIoControl |
||
| К | Windows XP |
Да |
| л | Windows 2000 Professional |
Да |
| и | Windows NT Workstation |
Да |
| е | Windows Me |
Да |
| н | Windows 98 |
Да |
| т | Windows 95 |
Да |
| С | Windows Server 2003 |
Да |
| е | Windows 2000 Server | Да |
| р | Windows NT Server | Да |
| в | ||
| е | ||
| р | ||
|
Используемая библиотека |
Kernel32.lib |
|
| Используемая DLL | kernel32.dll | |
| Заголовочный файл | ||
|
- объявлено в |
Winbase.h |
|
| - включено в |
Windows.h |
|
| Unicode |
Нет |
|
| Замечания по платформе |
Не имеется |
|