Функция IoCreateDevice (wdm.h)

Статья
08/08/2023

Подпрограмма IoCreateDevice создает объект устройства для использования драйвером.

Синтаксис

NTSTATUS IoCreateDevice(
  [in]           PDRIVER_OBJECT  DriverObject,
  [in]           ULONG           DeviceExtensionSize,
  [in, optional] PUNICODE_STRING DeviceName,
  [in]           DEVICE_TYPE     DeviceType,
  [in]           ULONG           DeviceCharacteristics,
  [in]           BOOLEAN         Exclusive,
  [out]          PDEVICE_OBJECT  *DeviceObject
);

Параметры

[in] DriverObject

Указатель на объект драйвера для вызывающего объекта. Каждый драйвер получает указатель на свой объект драйвера в параметре своей подпрограммы DriverEntry . Драйверы функций И фильтров WDM также получают указатель на объект драйвера в подпрограммах AddDevice .

[in] DeviceExtensionSize

Указывает определенное драйвером число байтов, выделяемых для расширения устройства объекта устройства. Внутренняя структура расширения устройства определяется драйвером.

[in, optional] DeviceName

При необходимости указывает на буфер, содержащий строку Юникода, завершающуюся null, которая называет объект устройства. Строка должна быть полным именем пути. Фильтры WDM и драйверы функций не называют свои объекты устройств. Дополнительные сведения см. в разделе Именованные объекты устройства.

Если имя устройства не указано (то есть DeviceName имеет значение NULL), объект устройства, созданный IoCreateDevice, не будет (и не может) иметь список управления доступом по усмотрению (DACL). Дополнительные сведения см. в разделе Дескрипторы безопасности.

[in] DeviceType

Указывает одну из системных констант FILE_DEVICE_XXX, которые указывают тип устройства (например, FILE_DEVICE_DISK или FILE_DEVICE_KEYBOARD) или определенное поставщиком значение для нового типа устройства. Дополнительные сведения см. в разделе Указание типов устройств.

[in] DeviceCharacteristics

Указывает одну или несколько системных констант ORed, которые предоставляют дополнительные сведения об устройстве драйвера. Список возможных характеристик устройств см. в разделе DEVICE_OBJECT. Дополнительные сведения о том, как указать характеристики устройства, см. в разделе Указание характеристик устройства. Большинство драйверов указывают FILE_DEVICE_SECURE_OPEN для этого параметра.

[in] Exclusive

Указывает, представляет ли объект устройства монопольное устройство. Большинство драйверов устанавливают для этого значения значение FALSE. Дополнительные сведения об монопольном доступе см. в разделе Указание монопольного доступа к объектам устройств.

[out] DeviceObject

Указатель на переменную, которая получает указатель на только что созданную DEVICE_OBJECT структуру. Структура DEVICE_OBJECT выделяется из непагированного пула. Расширение устройства объекта устройства обнуляется.

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

IoCreateDevice возвращает STATUS_SUCCESS при успешном выполнении или соответствующий код ошибки NTSTATUS при сбое. Частичный список кодов сбоев, возвращаемых этой функцией, включает:

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

IoCreateDevice можно использовать только для создания неименованного объекта устройства или именованного объекта устройства, для которого дескриптор безопасности задается INF-файлом. В противном случае драйверы должны использовать IoCreateDeviceSecure для создания именованных объектов устройств. Дополнительные сведения см. в разделе Создание объекта устройства. Вызывающий объект отвечает за установку определенных элементов возвращаемого объекта устройства. Дополнительные сведения см. в статьях Об инициализации объекта устройства и в документации по конкретному типу устройства.

Будьте внимательны, чтобы указать значения DeviceType и DeviceCharacteristics в правильных параметрах. Оба параметра используют системные константы FILE_XXX , а некоторые средства записи драйверов по ошибке указывают значения в неправильных параметрах.

Удаленная файловая система, которая создает именованный объект устройства для перенаправителя сети и регистрируется с помощью FsRtlRegisterUncProvider, должна указать FILE_REMOTE_DEVICE в качестве одного из параметров в параметре DeviceCharacteristics объекта IoCreateDevice.

Объектам устройств для дисков, лент, ДИСКОВ CD-ПЗУ и ОЗУ предоставляется блок параметров тома (VPB), который инициализирован, чтобы указать, что том никогда не был подключен на устройстве.

Если вызов драйвера IoCreateDevice возвращает ошибку, драйвер должен освободить все ресурсы, выделенные для этого устройства.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Правила соответствия DDI	AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)