Функция WdmlibIoCreateDeviceSecure (wdmsec.h)

Статья
03/08/2023

Функция WdmlibIoCreateDeviceSecure (или IoCreateDeviceSecure) создает именованный объект устройства и применяет указанные параметры безопасности.

Синтаксис

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 PDEVICE_OBJECT   *DeviceObject
);

Параметры

[in] DriverObject

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

[in] DeviceExtensionSize

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

[in, optional] DeviceName

При необходимости указывает на буфер, содержащий строку Юникода, завершающуюся null, которая называет объект устройства. Строка должна быть полным именем пути. Если имя не указано, флаг FILE_AUTOGENERATED_DEVICE_NAME должен присутствовать в параметре DeviceCharacteristics . (Чтобы создать неименованный объект устройства, используйте процедуру IoCreateDevice .)

[in] DeviceType

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

[in] DeviceCharacteristics

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

[in] Exclusive

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

[in] DefaultSDDLString

Задает строковое представление для параметров безопасности объекта устройства по умолчанию. Безопасность, применяемая к объекту устройства, является производным от этой строки, если системный администратор не помещает переопределение в раздел реестра, определяемый параметром DeviceClassGuid .

Параметр безопасности указывается в подмножестве языка определения дескриптора безопасности (SDDL). Также предоставляется набор предопределенных констант (SDDL_DEVOBJ_XXX). Дополнительные сведения см. в разделе Защита объектов устройств.

[in, optional] DeviceClassGuid

Указатель на GUID, который идентифицирует раздел реестра, содержащий возможные переопределения для параметров DefaultSDDLString, DeviceType, DeviceCharacteristics и Exclusive .

Примечание Всегда следует указывать идентификатор GUID пользовательского класса. Не следует указывать существующий GUID класса. Если указать существующий GUID класса, другие драйверы, которые пытаются указать существующий guid класса, могут не установиться или установить с неправильными параметрами безопасности.

DeviceObject

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

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

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

WdmlibIoCreateDeviceSecure создает именованный объект устройства, применяет указанные параметры безопасности и возвращает указатель на объект . Вызывающий объект отвечает за удаление объекта, когда он больше не нужен, вызывая IoDeleteDevice.

Эта подпрограмма не является частью операционной системы. Драйверы могут использовать подпрограмму, связываясь с Wdmsec.lib в Microsoft Windows 2000 и более поздних версиях Windows. (Библиотека Wdmsec.lib впервые поставляется вместе с Microsoft Windows XP с пакетом обновления 1 (SP1) и Windows Server 2003 пакета средств разработки драйверов [DDK], а также поставляется вместе с комплектом драйверов Windows [WDK].)

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

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

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

Guid, заданный параметром DeviceClassGuid , определяет класс настройки устройства для объекта устройства. (Дополнительные сведения о классах настройки устройств см. в разделе Классы настройки устройства.) Вызывающие абоненты должны предоставить значение, чтобы системные администраторы могли изменить параметры безопасности устройства (например, запретить доступ определенным пользователям). Дополнительные сведения см. в разделе Настройка свойств реестра объектов устройства после установки.

Драйверы, не относящиеся к WDM, указывают новый GUID, который еще не используется существующим классом настройки устройства. Создайте новый ИДЕНТИФИКАТОР GUID с помощью средства GuidGen.exe, включенного в Microsoft Windows SDK.

Драйверы шины WDM, обрабатывающие устройства с поддержкой необработанного режима, могут указывать класс настройки устройства, но только в том случае, если этот класс гарантированно уже создан. В противном случае создайте новый GUID.

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

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

Требования

Требование	Значение
Минимальная версия клиента	См. раздел "Примечания".
Целевая платформа	Персональный компьютер
Верхняя часть	wdmsec.h (включая Wdmsec.h)
Библиотека	Wdmsec.lib
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	AddDevice(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice