Функция 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 и Exclusive .

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 возвращает ошибку, драйвер должен освободить все ресурсы, выделенные для этого устройства.

Требования

См. также раздел

DEVICE_OBJECT

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCreateDevice

IoCreateSymbolicLink

IoDeleteDevice