WdmlibIoCreateDeviceSecure function (wdmsec.h)

Article
04/18/2022

The WdmlibIoCreateDeviceSecure function (or IoCreateDeviceSecure) creates a named device object and applies the specified security settings.

Syntax

NTSTATUS WdmlibIoCreateDeviceSecure(
  [in]           PDRIVER_OBJECT   DriverObject,
  [in]           ULONG            DeviceExtensionSize,
  [in, optional] PUNICODE_STRING  DeviceName,
  [in]           DEVICE_TYPE      DeviceType,
  [in]           ULONG            DeviceCharacteristics,
  [in]           BOOLEAN          Exclusive,
  [in]           PCUNICODE_STRING DefaultSDDLString,
  [in, optional] LPCGUID          DeviceClassGuid,
                 PDEVICE_OBJECT   *DeviceObject
);

Parameters

[in] 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.

[in] 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.

[in, optional] DeviceName

Optionally points to a buffer that contains a null-terminated Unicode string that names the device object. The string must be a full path name. If a name is not supplied, the FILE_AUTOGENERATED_DEVICE_NAME flag must be present in the DeviceCharacteristics parameter. (To create an unnamed device object, use the IoCreateDevice routine.)

[in] 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, and so on), or a vendor-defined value for a new type of device. For more information, see Specifying Device Types. (Because a bus driver might not have information about a device's type, a device type value for a PDO can be specified in an INF AddReg directive.)

[in] 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.

[in] Exclusive

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

[in] DefaultSDDLString

Specifies a string representation for the default security settings of the device object. The security that is applied to the device object is derived from this string unless the system administrator places an override in the section of the registry identified by the DeviceClassGuid parameter.

The security setting is specified in a subset of Security Descriptor Definition Language (SDDL). A set of predefined constants (SDDL_DEVOBJ_XXX) are also provided. For more information, see Securing Device Objects.

[in, optional] DeviceClassGuid

Pointer to a GUID that identifies a section of the registry containing possible overrides for the DefaultSDDLString, DeviceType, DeviceCharacteristics, and Exclusive parameters.

Note You should always specify a custom class GUID. You should not specify an existing class GUID. If you specify an existing class GUID, other drivers that attempt to specify that existing class GUID might fail to install or might install with incorrect security settings.

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

WdmlibIoCreateDeviceSecure returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. A partial list of the failure codes that could be returned by this function include:

Remarks

WdmlibIoCreateDeviceSecure creates a named device object, applies the specified security settings, and returns a pointer to the object. The caller is responsible for deleting the object when it is no longer needed by calling IoDeleteDevice.

This routine is not part of the operating system. Drivers can use the routine by linking to Wdmsec.lib on Microsoft Windows 2000 and later versions of Windows. (The Wdmsec.lib library first shipped with the Microsoft Windows XP Service Pack 1 [SP1] and Windows Server 2003 editions of the Driver Development Kit [DDK] and also ships with the Windows Driver Kit [WDK].)

Any driver that creates a named device object which is not guaranteed to have its security descriptor set by the INF file must use WdmlibIoCreateDeviceSecure. 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.

The caller is responsible for setting certain fields in the returned device object, such as the Flags field, and for initializing the device extension with any driver-defined information. For other operations that are required on new device objects, see Initializing a Device Object and the device-type-specific documentation for your device.

The GUID specified by the DeviceClassGuid parameter determines the device setup class for the device object. (For more information about device setup classes, see Device Setup Classes.) Callers must provide a value so that system administrators can change the security settings for the device (for instance, to deny access to certain users). For more information, see Setting Device Object Registry Properties After Installation.

Non-WDM drivers specify a new GUID, one not already in use by an existing device setup class. Generate a new GUID by using the GuidGen.exe tool that is included in the Microsoft Windows SDK.

WDM bus drivers that handle raw-mode capable devices can specify the device setup class of the device, but only if that class is guaranteed to already have been created. Otherwise, create a new GUID.

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 WdmlibIoCreateDeviceSecure returns an error, the driver should release any resources that it allocated for that device.

Requirements

Requirement	Value
Minimum supported client	See Remarks section.
Target Platform	Desktop
Header	wdmsec.h (include Wdmsec.h)
Library	Wdmsec.lib
IRQL	PASSIVE_LEVEL
DDI compliance rules	AddDevice(wdm), HwStorPortProhibitedDDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice