SetupDiOpenDevRegKey function (setupapi.h)

The SetupDiOpenDevRegKey function opens a registry key for device-specific configuration information.

Syntax

WINSETUPAPI HKEY SetupDiOpenDevRegKey(
  [in] HDEVINFO         DeviceInfoSet,
  [in] PSP_DEVINFO_DATA DeviceInfoData,
  [in] DWORD            Scope,
  [in] DWORD            HwProfile,
  [in] DWORD            KeyType,
  [in] REGSAM           samDesired
);

Parameters

[in] DeviceInfoSet

A handle to the device information set that contains a device information element that represents the device for which to open 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 open. The scope determines where the information is stored. The scope can be global or specific to a hardware profile. The scope is specified by one of the following values:

DICS_FLAG_GLOBAL

Open a key to store global configuration information. This information is not specific to a particular hardware profile. This opens a key that is rooted at HKEY_LOCAL_MACHINE. The exact key opened depends on the value of the KeyType parameter.

DICS_FLAG_CONFIGSPECIFIC

Open 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. The exact key opened depends on the value of the KeyType parameter.

[in] HwProfile

A hardware profile value, which is set as follows:

• If Scope is set to DICS_FLAG_CONFIGSPECIFIC, HwProfile specifies the hardware profile of the key that is to be opened.
• If HwProfile is 0, the key for the current hardware profile is opened.
• If Scope is DICS_FLAG_GLOBAL, HwProfile is ignored.

[in] KeyType

The type of registry storage key to open, which can be one of the following values:

DIREG_DEV

Open a hardware key for the device.

DIREG_DRV

Open a software key for the device.

For more information about a device's hardware and software keys, see Registry Trees and Keys for Devices and Drivers.

[in] samDesired

The registry security access that is required for the requested key. For information about registry security access values of type REGSAM, see the Microsoft Windows SDK documentation.

Return value

If the function is successful, it returns a handle to an opened registry key where private configuration data about this device instance can be stored/retrieved.

If the function fails, it returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

Depending on the value that is passed in the samDesired parameter, it might be necessary for the caller of this function to be a member of the Administrators group.

Close the handle returned from this function by calling RegCloseKey.

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

Requirements

See also

SetupDiCreateDevRegKey

SetupDiCreateDeviceInfo

SetupDiGetHwProfileList

SetupDiRegisterDeviceInfo