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

Статья
12/21/2024

Подпрограмма 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 создает объект устройства и возвращает указатель на объект. Вызывающий объект отвечает за удаление объекта, если он больше не нужен путем вызова IoDeleteDevice.

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

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

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

Объекты устройств для дисков, лент, cd-ROMs и ОЗУ предоставляют блок параметров тома (VPB), который инициализирован, чтобы указать, что том никогда не был подключен на устройстве.

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

Требования

Требование	Ценность
целевая платформа	Всеобщий
заголовка	wdm.h (include 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)