IoCreateDevice

Description

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