Функция WdmlibIoCreateDeviceSecure (wdmsec.h)
Функция 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и эксклюзивных параметров.
DeviceObject
Указатель на переменную, которая получает указатель на только что созданную DEVICE_OBJECT структуру. Структура DEVICE_OBJECT выделяется из непагрегированного пула.
Возвращаемое значение
WdmlibIoCreateDeviceSecure возвращает STATUS_SUCCESS при успешном выполнении или соответствующий код ошибки NTSTATUS при сбое. Частичный список кодов сбоев, которые могут быть возвращены этой функцией:
Замечания
WdmlibIoCreateDeviceSecure создает именованный объект устройства, применяет указанные параметры безопасности и возвращает указатель на объект. Вызывающий объект отвечает за удаление объекта, если он больше не нужен путем вызова IoDeleteDevice.
Эта подпрограмма не является частью операционной системы. Драйверы могут использовать подпрограмму, связываясь с Wdmsec.lib в Microsoft Windows 2000 и более поздних версиях Windows. (Библиотека Wdmsec.lib впервые поставляется с пакетом обновления 1 (SP1) и windows Server 2003 в комплекте средств разработки драйверов [DDK], а также поставляется с комплектом драйверов Windows [WDK].)
Любой драйвер, создающий именованный объект устройства, который не гарантирует, что его дескриптор безопасности задан INF-файлом, должен использовать WdmlibIoCreateDeviceSecure. Дополнительные сведения см. в статье Создание объекта устройства. Вызывающий объект отвечает за настройку определенных элементов возвращаемого объекта устройства. Дополнительные сведения см. в инициализации объекта устройства и документации по типу устройства.
Будьте осторожны, чтобы указать DeviceType и DeviceCharacteristics значения в правильных параметрах. Оба параметра используют системные FILE_XXX константы, а некоторые записи драйверов указывают значения в неправильных параметрах по ошибке.
Вызывающий объект отвечает за настройку определенных полей в возвращаемом объекте устройства, например поле Флаги, а также за инициализацию расширения устройства с любой информацией, определенной драйвером. Сведения о других операциях, необходимых для новых объектов устройств, см. в инициализации объекта устройства и документации по типу устройства.
Идентификатор GUID, указанный параметром DeviceClassGuid, определяет класс установки устройства для объекта устройства. (Дополнительные сведения о классах установки устройства см. в разделе Классы установки устройств.) Вызывающие пользователи должны предоставить значение, чтобы системные администраторы могли изменять параметры безопасности устройства (например, чтобы запретить доступ определенным пользователям). Дополнительные сведения см. в разделе Настройка свойств реестра объектов устройства после установки.
Драйверы, отличные от WDM, указывают новый GUID, который еще не используется существующим классом установки устройства. Создайте новый GUID с помощью средства GuidGen.exe, включенного в пакет SDK для Microsoft Windows.
Драйверы шины WDM, обрабатывающие устройства с поддержкой необработанного режима, могут указать класс установки устройства, но только если этот класс гарантированно уже создан. В противном случае создайте новый GUID.
Объекты устройств для дисков, лент, cd-ROMs и ОЗУ предоставляют блок параметров тома (VPB), который инициализирован, чтобы указать, что том никогда не был подключен на устройстве.
Если вызов драйвера к WdmlibIoCreateDeviceSecure возвращает ошибку, драйвер должен освободить все ресурсы, выделенные для этого устройства.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | См. раздел "Примечания". |
| целевая платформа | Настольный |
| заголовка | wdmsec.h (include Wdmsec.h) |
| библиотеки | Wdmsec.lib |
| IRQL | PASSIVE_LEVEL |
| правил соответствия DDI | AddDevice(wdm), HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice |