Función IoCreateDevice (wdm.h)

Artículo
02/27/2024

La rutina IoCreateDevice crea un objeto de dispositivo para que lo use un controlador.

Sintaxis

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

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. Los controladores de función y filtro WDM no asignan un nombre a sus objetos de dispositivo. Para obtener más información, vea Objetos de dispositivo con nombre.

Si no se proporciona un nombre de dispositivo (es decir, DeviceName es NULL), el objeto de dispositivo creado por IoCreateDevice no (y no puede) tener asociada una lista de control de acceso discrecional (DACL). Para obtener más información, consulte Descriptores de seguridad.

[in] DeviceType

Especifica una de las constantes FILE_DEVICE_XXX definidas por el sistema que indican el tipo de dispositivo (como FILE_DEVICE_DISK o FILE_DEVICE_KEYBOARD) o un valor definido por el proveedor para un nuevo tipo de dispositivo. Para obtener más información, vea Especificar tipos de dispositivo.

[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 sobre el acceso exclusivo, vea Especificar el acceso exclusivo a objetos de dispositivo.

[out] 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. La extensión de dispositivo del objeto de dispositivo está a cero.

Valor devuelto

IoCreateDevice 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 devueltos por esta función incluye:

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_COLLISION

Comentarios

IoCreateDevice crea un objeto de dispositivo 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.

IoCreateDevice solo se puede usar para crear un objeto de dispositivo sin nombre o un objeto de dispositivo con nombre para el que un archivo INF establece un descriptor de seguridad. De lo contrario, los controladores deben usar IoCreateDeviceSecure para crear objetos de dispositivo con nombre. 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.

Un sistema de archivos remoto que crea un objeto de dispositivo con nombre para un redirector de red y que se registra mediante FsRtlRegisterUncProvider, debe especificar FILE_REMOTE_DEVICE como una de las opciones del parámetro DeviceCharacteristics de IoCreateDevice.

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 IoCreateDevice devuelve un error, el controlador debe liberar los recursos que haya asignado para ese dispositivo.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL
Reglas de cumplimiento de DDI	AddDevice(wdm), CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice(kmdf)