SetupDiGetClassDevPropertySheetsA function (setupapi.h)

  • Article

The SetupDiGetClassDevPropertySheets function retrieves handles to the property sheets of a device information element or of the device setup class of a device information set.

Syntax

WINSETUPAPI BOOL SetupDiGetClassDevPropertySheetsA(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, optional]  PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            LPPROPSHEETHEADERA PropertySheetHeader,
  [in]            DWORD              PropertySheetHeaderPageListSize,
  [out, optional] PDWORD             RequiredSize,
  [in]            DWORD              PropertySheetType
);

Parameters

[in] DeviceInfoSet

A handle to the device information set for which to return property sheet handles. If DeviceInfoData does not specify a device information element in the device information set, the device information set must have an associated device setup class.

[in, optional] DeviceInfoData

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

This parameter is optional and can be NULL. If this parameter is specified, SetupDiGetClassDevPropertySheets retrieves the property sheets handles that are associated with the specified device. If this parameter is NULL, SetupDiGetClassDevPropertySheets retrieves the property sheets handles that are associated with the device setup class specified in DeviceInfoSet.

[in] PropertySheetHeader

A pointer to a PROPERTYSHEETHEADER structure. See the Remarks section for information about the caller-supplied array of property sheet handles that is associated with this structure.

For more documentation on this structure and property sheets in general, see the Microsoft Windows SDK.

[in] PropertySheetHeaderPageListSize

The maximum number of handles that the caller-supplied array of property sheet handles can hold.

[out, optional] RequiredSize

A pointer to a variable of type DWORD that receives the number of property sheets that are associated with the specified device information element or the device setup class of the specified device information set. The pointer is optional and can be NULL.

[in] PropertySheetType

A flag that indicates one of the following types of property sheets.

Property sheet type Meaning
DIGCDP_FLAG_ADVANCED Advanced property sheets.
DIGCDP_FLAG_BASIC Basic property sheets. Supported only in Microsoft Windows 95 and Windows 98. Do not use in Windows 2000 and later versions of Windows.
DIGCDP_FLAG_REMOTE_ADVANCED Advanced property sheets on a remote computer.

Return value

The function returns TRUE if successful. Otherwise, the function returns FALSE. Call GetLastError to obtain the error code.

Remarks

A PROPERTYSHEETHEADER structure contains two members that are associated with a caller-supplied array that the function uses to return the handles of property sheets. The phpages member is a pointer to a caller-supplied array of property sheet handles, and the input value of the nPages member specifies the number of handles that are already contained in the handle array. The function adds property sheet handles to the handle array beginning with the array element whose array index is the input value of nPages. The function adds handles to the array in consecutive order until either the array is full or the handles of all the requested property sheet pages have been added to the array. The maximum number of property sheet handles that the function can return is equal to (PropertySheetHeaderPageListSize - (input value of nPages)).

If the handle array is large enough to hold the handles of all the requested property sheet pages, the function:

  • Adds the handles to the handle array.
  • Sets nPages to the total number of handles in the array.
  • Sets RequiredSize to the number of handles that it returns.
  • Returns TRUE.
If the handle array is not large enough to hold the handles of all the specified property sheet pages, the function:
  • Adds as many handles as the array can hold.
  • Sets nPages to PropertySheetHeaderPageListSize.
  • Sets RequiredSize to the total number of requested property sheet pages. The number of handles that are not returned by the function is equal to (RequiredSize - PropertySheetHeaderPageListSize - (input value of nPages)).
  • Sets the error code to ERROR_INSUFFICIENT_BUFFER.
  • Returns FALSE.

Note

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

See also

SP_DEVINFO_DATA