SetupDiGetClassDescriptionExA function (setupapi.h)

Article
02/09/2023

The SetupDiGetClassDescriptionEx function retrieves the description of a setup class installed on a local or remote computer.

Syntax

WINSETUPAPI BOOL SetupDiGetClassDescriptionExA(
  [in]            const GUID *ClassGuid,
  [out]           PSTR       ClassDescription,
  [in]            DWORD      ClassDescriptionSize,
  [out, optional] PDWORD     RequiredSize,
  [in, optional]  PCSTR      MachineName,
                  PVOID      Reserved
);

Parameters

[in] ClassGuid

A pointer to the GUID for the setup class whose description is to be retrieved.

[out] ClassDescription

A pointer to a character buffer that receives the class description.

[in] ClassDescriptionSize

The size, in characters, of the buffer that is pointed to by the ClassDescription parameter. The maximum length, in characters, of a NULL-terminated class description is LINE_LEN. For more information, see the following Remarks section.

[out, optional] RequiredSize

A pointer to a DWORD-typed variable that receives the size, in characters, that is required to store the requested NULL-terminated class description. This pointer is optional and can be NULL.

[in, optional] MachineName

A pointer to a NULL-terminated string that supplies the name of a remote computer on which the setup class resides. This pointer is optional and can be NULL. If the class is installed on a local computer, set the pointer to NULL.

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 for system use. A caller of this function must set this parameter to NULL.

Return value

The function returns TRUE if it is successful. Otherwise, it returns FALSE and the logged error can be retrieved with a call to GetLastError.

Remarks

If there is a friendly name in the registry key for the class, this routine returns the friendly name. Otherwise, this routine returns the class name.

SetupDiGetClassDescriptionEx does not enforce a restriction on the length of the class description that it can return. This function returns the required size for a NULL-terminated class description even if it is greater than LINE_LEN. However, LINE_LEN is the maximum length of a valid NULL-terminated class description. A caller should never need a buffer that is larger than LINE_LEN.

Note

The setupapi.h header defines SetupDiGetClassDescriptionEx 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