Export (0) Print
Expand All
Expand Minimize

IoCreateDevice routine

The IoCreateDevice routine creates a device object for use by a driver.

Syntax


NTSTATUS IoCreateDevice(
  _In_      PDRIVER_OBJECT DriverObject,
  _In_      ULONG DeviceExtensionSize,
  _In_opt_  PUNICODE_STRING DeviceName,
  _In_      DEVICE_TYPE DeviceType,
  _In_      ULONG DeviceCharacteristics,
  _In_      BOOLEAN Exclusive,
  _Out_     PDEVICE_OBJECT *DeviceObject
);

Parameters

DriverObject [in]

Pointer to the driver object for the caller. Each driver receives a pointer to its driver object in a parameter to its DriverEntry routine. WDM function and filter drivers also receive a driver object pointer in their AddDevice routines.

DeviceExtensionSize [in]

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.

DeviceName [in, optional]

Optionally points to a buffer containing a null-terminated Unicode string that names the device object. The string must be a full path name. WDM filter and function drivers do not name their device objects. For more information, see Named Device Objects.

Note  If a device name is not supplied (that is, DeviceName is NULL), the device object created by IoCreateDevice will not (and cannot) have a discretionary access control list (DACL) associated with it. For additional information, see Security Descriptors.

DeviceType [in]

Specifies one of the system-defined FILE_DEVICE_XXX constants that indicate the type of device (such as FILE_DEVICE_DISK or FILE_DEVICE_KEYBOARD) or a vendor-defined value for a new type of device. For more information, see Specifying Device Types.

DeviceCharacteristics [in]

Specifies one or more system-defined constants, ORed together, that provide additional information about the driver's device. For a list of possible device characteristics, see DEVICE_OBJECT. For more information about how to specify device characteristics, see Specifying Device Characteristics. Most drivers specify FILE_DEVICE_SECURE_OPEN for this parameter.

Exclusive [in]

Specifies if the device object represents an exclusive device. Most drivers set this value to FALSE. For more information about exclusive access, see Specifying Exclusive Access to Device Objects.

DeviceObject [out]

Pointer to a variable that receives a pointer to the newly created DEVICE_OBJECT structure. The DEVICE_OBJECT structure is allocated from nonpaged pool.

Return value

IoCreateDevice returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. A partial list of the failure codes returned by this function includes:

STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_EXISTS
STATUS_OBJECT_NAME_COLLISION

Remarks

IoCreateDevice creates a device object and returns a pointer to the object. The caller is responsible for deleting the object when it is no longer needed by calling IoDeleteDevice.

IoCreateDevice can only be used to create an unnamed device object, or a named device object for which a security descriptor is set by an INF file. Otherwise, drivers must use IoCreateDeviceSecure to create named device objects. For more information, see Creating a Device Object. The caller is responsible for setting certain members of the returned device object. For more information, see Initializing a Device Object and the device-type-specific documentation for your device.

Be careful to specify the DeviceType and DeviceCharacteristics values in the correct parameters. Both parameters use system-defined FILE_XXX constants and some driver writers specify the values in the wrong parameters by mistake.

A remote file system that creates a named device object for a network redirector, and that registers using FsRtlRegisterUncProvider, must specify FILE_REMOTE_DEVICE as one of the options in the DeviceCharacteristics parameter of IoCreateDevice.

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.

If a driver's call to IoCreateDevice returns an error, the driver should release any resources that it allocated for that device.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= APC_LEVEL

DDI compliance rules

AddDevice, CheckDeviceObjectFlags, IrqlIoPassive1, MiniportOnlyWdmDevice, HwStorPortProhibitedDDIs

See also

DEVICE_OBJECT
FsRtlRegisterUncProvider
IoAttachDevice
IoAttachDeviceToDeviceStack
IoCreateDeviceSecure
IoCreateSymbolicLink
IoDeleteDevice

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft