IO Create Device

IoCreateDevice

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

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

    );

Parameters

DriverObject

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

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

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.

DeviceType

Specifies one of the system-defined FILE_DEVICE_XXX constants that indicate the type of device (such as

FILE_DEVICE_DISK, FILE_DEVICE_KEYBOARD, etc.) or a vendor-defined value for a new type of device. For

more information, see Specifying Device Types.

DeviceCharacteristics

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

Reserved for system use. Drivers set this parameter to FALSE.

DeviceObject

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 include:

STATUS_INSUFFICIENT_RESOURCES

STATUS_OBJECT_NAME_EXISTS

STATUS_OBJECT_NAME_COLLISION

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

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￾Kernel-Mode Driver Architecture: Windows DDK

IoCreateDevice Page 1 of 2

mk:@MSITStore:E:\WINDDK\3790.1830\help\kmarch.chm::/hh/kmarch/k104_1e38a631-... 9/19/2010