IoCreateDevice

IoCreateDevice

NTSTATUS
IoCreateDevice(
IN PDRIVER_OBJECT DriverObject,
IN ULONG DeviceExtensionSize,
IN PUNICODE_STRING DeviceName,/* optional */
IN DEVICE_TYPE DeviceType,
IN ULONG DeviceCharacteristics,
IN BOOLEAN Exclusive,
OUT PDEVICE_OBJECT *DeviceObject
);

IoCreateDevice allocates memory for and initializes a device object for use by a driver. A device object represents a physical, virtual, or logical device whose driver is being loaded into the system, or it represents a virtual or logical device whose driver is required to support the reconfiguration of its device objects dynamically.

Parameters

DriverObject

Points to the driver object created by the I/O Manager when the driver was loaded. Each driver's DriverEntry routine is called with a pointer to the corresponding driver object.

DeviceExtensionSize

Specifies the driver-determined number of bytes to be allocated for the device extension of the device object. The internal structure of the device extension is driver-defined, used to maintain context about the I/O operations on the device represented by the DeviceObject.

DeviceName

Points to a buffer containing a zero-terminated Unicode string that names the device object. The string must be a full path name. Any device object that can be the target of an I/O request or that a higher-level driver can connect to must have a DeviceName. An unnamed device object is visible only to the driver that created it or to an FSD through a volume parameter block (VPB).

DeviceType

Specifies one of the system-defined FILE_DEVICE_XXX constants indicating the type of device (such as FILE_DEVICE_DISK, FILE_DEVICE_SERIAL, etc.) or a driver-defined value for a new type of device. For more information, see Part II of this manual.

DeviceCharacteristics

Specifies one or more (ORed) of the following system-defined constants: FILE_REMOVABLE_MEDIA, FILE_READ_ONLY_DEVICE, FILE_FLOPPY_DISKETTE, FILE_WRITE_ONCE_MEDIA, and FILE_REMOTE_DEVICE, describing the nature of the driver's device, if appropriate. Other types of drivers can ignore this field.

Exclusive

Indicates whether or not the device object represents an exclusive device. That is, only a single thread at a time can send I/O requests to the corresponding device.

DeviceObject

Points to the newly created device object if the call succeeds.

Return Value

IoCreateDevice can return one of the following NTSTATUS values:

STATUS_SUCCESS
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_EXISTS
STATUS_OBJECT_NAME_COLLISION

Comments

This routine allocates space in nonpaged pool for the driver-defined device extension associated with the device object, so that the device extension is accessible to the driver in any execution context and at any IRQL. The returned device extension is initialized with zeros.

In general, drivers that set Exclusive to TRUE control interactive devices, such as video, serial, parallel, or sound devices.

Device objects for disks, tapes, CD ROMs, and RAM disks are given a Volume Parameter Block (VPB) that is initialized to indicate that the volume has never been mounted on the device.

Each driver must create at least one named device object by calling IoCreateDevice. Otherwise, no I/O requests can be sent to the driver. An unnamed device object is invisible to other drivers except, possibly, FSDs and to user-mode protected subsystems because a symbolic link cannot be set up for an unnamed device object. Consequently, higher-level drivers cannot attach their device objects to an unnamed device object nor can the unnamed object be the target of an IRP.

If a driver's call to IoCreateDevice returns an error, it should release any resources it allocated for that device. If the driver cannot set up a device object to represent any of the devices it controls, that driver should not load.

Certain device drivers call IoCreateDevice from a Dispatch routine. In particular, disk drivers must call IoCreateDevice in response to a device control request to repartition a disk dynamically.

Callers of IoCreateDevice must be running at IRQL PASSIVE_LEVEL.