SetupDiOpenClassRegKeyExA function (setupapi.h)

Article
02/09/2023

The SetupDiOpenClassRegKeyEx function opens the device setup class registry key, the device interface class registry key, or a specific class's subkey. This function opens the specified key on the local computer or on a remote computer.

Syntax

WINSETUPAPI HKEY SetupDiOpenClassRegKeyExA(
  [in, optional] const GUID *ClassGuid,
  [in]           REGSAM     samDesired,
  [in]           DWORD      Flags,
  [in, optional] PCSTR      MachineName,
                 PVOID      Reserved
);

Parameters

[in, optional] ClassGuid

A pointer to the GUID of the class whose registry key is to be opened. This parameter is optional and can be NULL. If this parameter is NULL, the root of the class tree (HKLM\SYSTEM\CurrentControlSet\Control\Class) is opened.

[in] samDesired

The registry security access for the key to be opened. For information about registry security access values of type REGSAM, see the Microsoft Windows SDK documentation.

[in] Flags

The type of registry key to be opened, which is specified by one of the following:

DIOCR_INSTALLER

Open a setup class key. If ClassGuid is NULL, open the root key of the class installer branch.

DIOCR_INTERFACE

Open an interface class key. If ClassGuid is NULL, open the root key of the interface class branch.

[in, optional] MachineName

Optionally points to a string that contains the name of a remote computer on which to open the specified key.

Caution

Using this function to access remote machines is not supported beginning with Windows 8 and Windows Server 2012, as this functionality has been removed.

Reserved

Reserved. Must be NULL.

Return value

SetupDiOpenClassRegKeyEx returns a handle to an opened registry key where information about this setup class 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.

SetupDiOpenClassRegKeyEx does not create a registry key if it does not already exist.

Callers of this function must close the handle returned from this function by calling RegCloseKey.

Note

The setupapi.h header defines SetupDiOpenClassRegKeyEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows 2000 and later versions of Windows.
Target Platform	Desktop
Header	setupapi.h (include Setupapi.h)
Library	Setupapi.lib