SetupDiCreateDevRegKeyA function (setupapi.h)

The SetupDiCreateDevRegKey function creates a registry key for device-specific configuration information and returns a handle to the key.

Syntax

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

Parameters

[in] DeviceInfoSet

A handle to a device information set that contains a device information element that represents the device for which to create a registry key.

[in] DeviceInfoData

A pointer to an SP_DEVINFO_DATA structure that specifies the device information element in DeviceInfoSet.

[in] Scope

The scope of the registry key to be created. The scope determines where the information is stored. The key created can be global or hardware profile-specific. Can be one of the following values:

DICS_FLAG_GLOBAL

Create a key to store global configuration information. This information is not specific to a particular hardware profile. On NT-based operating systems this creates a key that is rooted at HKEY_LOCAL_MACHINE. The exact key opened depends on the value of the KeyType parameter.

DICS_FLAG_CONFIGSPECIFIC

Create a key to store hardware profile-specific configuration information. This key is rooted at one of the hardware-profile specific branches, instead of HKEY_LOCAL_MACHINE.

[in] HwProfile

The hardware profile for which to create a key if HwProfileFlags is set to SPDICS_FLAG_CONFIGSPECIFIC. If HwProfile is 0, the key for the current hardware profile is created. If HwProfileFlags is SPDICS_FLAG_GLOBAL, HwProfile is ignored.

[in] KeyType

The type of registry storage key to create. Can be one of the following values:

DIREG_DEV

Create a hardware key for the device.

DIREG_DRV

Create a software key for the device.

[in, optional] InfHandle

The handle to an open INF file that contains an INF DDInstall section to be executed for the newly created key. This parameter is optional and can be NULL. If this parameter is specified, InfSectionName must be specified as well.

[in, optional] InfSectionName

The name of an INF DDInstall section in the INF file specified by InfHandle. This section is executed for the newly created key. This parameter is optional and can be NULL. If this parameter is specified, InfHandle must be specified as well.

Return value

If SetupDiCreateDevRegKey succeeds, the function returns a handle to the specified registry key in which device-specific configuration data can be stored and retrieved. If SetupDiCreateDevRegKey fails, the function returns INVALID_HANDLE_VALUE. Call GetLastError to get extended error information.

Remarks

The caller of SetupDiCreateDevRegKey must be a member of the Administrators group.

Close the handle returned from SetupDiCreateDevRegKey by calling RegCloseKey.

If the specified key already exists, SetupDiCreateDevRegKey returns a handle to that key. Otherwise, SetupDiCreateDevRegKey creates the specified key and returns a handle to the new key. For Windows Server 2003 and later versions of Windows, the key handle has KEY_READ and KEY_WRITE access only. For previous Windows versions, this handle has KEY_ALL_ACCESS access.

The specified device instance must be registered before SetupDiCreateDevRegKey is called. Note, however, that the operating system automatically registers PnP device instances. For information about how to register non-PnP device instances, see SetupDiRegisterDeviceInfo.

For installations that use layout files (specified by the LayoutFile entry in an INF Version section), the layout file must be opened by a call to SetupOpenAppendInfFile (described in the Microsoft Windows SDK documentation) before SetupDiCreateDevRegKey is called.

If the supplied device information set contains device information elements for a remote system, and InfHandle and InfSectionName are also specified, the create request will fail, and a subsequent call to GetLastError will return ERROR_REMOTE_REQUEST_UNSUPPORTED.

Requirements

See also

SetupDiCreateDeviceInfo

SetupDiGetHwProfileList

SetupDiOpenDevRegKey

SetupDiRegisterDeviceInfo