Función WdmlibIoCreateDeviceSecure (wdmsec.h)

Artículo
03/08/2023

La función WdmlibIoCreateDeviceSecure (o IoCreateDeviceSecure) crea un objeto de dispositivo con nombre y aplica la configuración de seguridad especificada.

Sintaxis

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
);

Parámetros

[in] DriverObject

Puntero al objeto de controlador para el autor de la llamada. Cada controlador recibe un puntero a su objeto driver en un parámetro a su rutina DriverEntry . La función WDM y los controladores de filtro también reciben un puntero de objeto de controlador en sus rutinas AddDevice .

[in] DeviceExtensionSize

Especifica el número de bytes determinado por el controlador que se va a asignar para la extensión de dispositivo del objeto de dispositivo. La estructura interna de la extensión de dispositivo está definida por el controlador.

[in, optional] DeviceName

Opcionalmente, apunta a un búfer que contiene una cadena Unicode terminada en null que asigna un nombre al objeto de dispositivo. La cadena debe ser un nombre de ruta de acceso completa. Si no se proporciona un nombre, la marca FILE_AUTOGENERATED_DEVICE_NAME debe estar presente en el parámetro DeviceCharacteristics . (Para crear un objeto de dispositivo sin nombre, use la rutina IoCreateDevice ).

[in] DeviceType

Especifica una de las constantes FILE_DEVICE_XXX definidas por el sistema que indican el tipo de dispositivo (como FILE_DEVICE_DISK, FILE_DEVICE_KEYBOARD, etc.) o un valor definido por el proveedor para un nuevo tipo de dispositivo. Para obtener más información, vea Especificar tipos de dispositivo. (Dado que es posible que un controlador de autobús no tenga información sobre el tipo de un dispositivo, se puede especificar un valor de tipo de dispositivo para un PDO en una directiva AddReg inf).

[in] DeviceCharacteristics

Especifica una o varias constantes definidas por el sistema, ORed juntas, que proporcionan información adicional sobre el dispositivo del controlador. Para obtener una lista de las posibles características del dispositivo, consulte DEVICE_OBJECT. Para obtener más información sobre cómo especificar las características del dispositivo, consulte Especificación de características del dispositivo. La mayoría de los controladores especifican FILE_DEVICE_SECURE_OPEN para este parámetro.

[in] Exclusive

Especifica si el objeto de dispositivo representa un dispositivo exclusivo. La mayoría de los controladores establecen este valor en FALSE. Para obtener más información, vea Especificar el acceso exclusivo a objetos de dispositivo.

[in] DefaultSDDLString

Especifica una representación de cadena para la configuración de seguridad predeterminada del objeto de dispositivo. La seguridad que se aplica al objeto de dispositivo se deriva de esta cadena a menos que el administrador del sistema coloque una invalidación en la sección del registro identificado por el parámetro DeviceClassGuid .

La configuración de seguridad se especifica en un subconjunto del lenguaje de definición de descriptores de seguridad (SDDL). También se proporciona un conjunto de constantes predefinidas (SDDL_DEVOBJ_XXX). Para obtener más información, consulte Protección de objetos de dispositivo.

[in, optional] DeviceClassGuid

Puntero a un GUID que identifica una sección del registro que contiene posibles invalidaciones para los parámetros DefaultSDDLString, DeviceType, DeviceCharacteristics y Exclusive .

Nota Siempre debe especificar un GUID de clase personalizado. No debe especificar un GUID de clase existente. Si especifica un GUID de clase existente, otros controladores que intentan especificar que el GUID de clase existente podría no instalarse o podría instalarse con una configuración de seguridad incorrecta.

DeviceObject

Puntero a una variable que recibe un puntero a la estructura de DEVICE_OBJECT recién creada. La estructura DEVICE_OBJECT se asigna desde un grupo no paginado.

Valor devuelto

WdmlibIoCreateDeviceSecure devuelve STATUS_SUCCESS si se ha realizado correctamente o el código de error NTSTATUS adecuado en caso de error. Una lista parcial de los códigos de error que podría devolver esta función incluye:

Comentarios

WdmlibIoCreateDeviceSecure crea un objeto de dispositivo con nombre, aplica la configuración de seguridad especificada y devuelve un puntero al objeto . El autor de la llamada es responsable de eliminar el objeto cuando ya no es necesario mediante una llamada a IoDeleteDevice.

Esta rutina no forma parte del sistema operativo. Los controladores pueden usar la rutina vinculando a Wdmsec.lib en Microsoft Windows 2000 y versiones posteriores de Windows. (La biblioteca Wdmsec.lib se incluye primero con las ediciones Microsoft Windows XP Service Pack 1 [SP1] y Windows Server 2003 del Kit de desarrollo de controladores [DDK] y también se incluye con el Kit de controladores de Windows [WDK].)

Cualquier controlador que cree un objeto de dispositivo con nombre que no esté garantizado que tenga su descriptor de seguridad establecido por el archivo INF debe usar WdmlibIoCreateDeviceSecure. Para obtener más información, consulte Creación de un objeto de dispositivo. El autor de la llamada es responsable de establecer determinados miembros del objeto de dispositivo devuelto. Para obtener más información, consulte Inicialización de un objeto de dispositivo y la documentación específica del tipo de dispositivo para el dispositivo.

Tenga cuidado de especificar los valores DeviceType y DeviceCharacteristics en los parámetros correctos. Ambos parámetros usan constantes FILE_XXX definidas por el sistema y algunos escritores de controladores especifican los valores de los parámetros incorrectos por error.

El autor de la llamada es responsable de establecer determinados campos en el objeto de dispositivo devuelto, como el campo Marcas , y para inicializar la extensión del dispositivo con cualquier información definida por el controlador. Para otras operaciones necesarias en los nuevos objetos de dispositivo, consulte Inicialización de un objeto device y la documentación específica del tipo de dispositivo para el dispositivo.

El GUID especificado por el parámetro DeviceClassGuid determina la clase de configuración del dispositivo para el objeto de dispositivo. (Para obtener más información sobre las clases de configuración de dispositivos, consulte Clases de configuración de dispositivos). Los autores de llamadas deben proporcionar un valor para que los administradores del sistema puedan cambiar la configuración de seguridad del dispositivo (por ejemplo, para denegar el acceso a determinados usuarios). Para obtener más información, vea Establecer las propiedades del Registro de objetos de dispositivo después de la instalación.

Los controladores que no son WDM especifican un nuevo GUID, uno que aún no está en uso por una clase de configuración de dispositivo existente. Genere un nuevo GUID mediante la herramienta GuidGen.exe que se incluye en el Microsoft Windows SDK.

Los controladores de bus WDM que controlan dispositivos compatibles con modo sin procesar pueden especificar la clase de configuración del dispositivo, pero solo si se garantiza que esa clase ya se haya creado. De lo contrario, cree un nuevo GUID.

Los objetos de dispositivo para discos, cintas, CD-ROMs y discos RAM reciben un bloque de parámetros de volumen (VPB) que se inicializa para indicar que el volumen nunca se ha montado en el dispositivo.

Si la llamada de un controlador a WdmlibIoCreateDeviceSecure devuelve un error, el controlador debe liberar los recursos que haya asignado para ese dispositivo.

Requisitos

Requisito	Value
Cliente mínimo compatible	vea la sección Comentarios.
Plataforma de destino	Escritorio
Encabezado	wdmsec.h (include Wdmsec.h)
Library	Wdmsec.lib
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	AddDevice(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice