SetupDiGetClassPropertyKeysExW 函数 (setupapi.h)

  • 项目

SetupDiGetClassPropertyKeysEx 函数检索设备属性键数组，这些键表示为本地或远程计算机上的设备安装程序类或设备接口类设置的设备属性。

语法

WINSETUPAPI BOOL SetupDiGetClassPropertyKeysExW(
  [in]            const GUID *ClassGuid,
  [out, optional] DEVPROPKEY *PropertyKeyArray,
  [in]            DWORD      PropertyKeyCount,
  [out, optional] PDWORD     RequiredPropertyKeyCount,
  [in]            DWORD      Flags,
  [in, optional]  PCWSTR     MachineName,
                  PVOID      Reserved
);

参数

[in] ClassGuid

指向 GUID 的指针，该 GUID 表示设备安装程序类或设备接口类。 SetupDiGetClassPropertyKeysEx 检索设备属性键的数组，这些键表示为指定类设置的设备属性。 有关指定类类型的信息，请参阅 Flags 参数。

[out, optional] PropertyKeyArray

指向接收 DEVPROPKEY 类型值数组的缓冲区的指针，其中每个值都是表示为设备安装类设置的设备属性的设备属性键。 指针是可选的，可以为 NULL。 有关详细信息，请参阅本主题后面的 “备注 ”部分。

[in] PropertyKeyCount

PropertyKeyArray 缓冲区的大小（以 DEVPROPKEY 类型值为单位）。 如果 PropertyKeyArray 设置为 NULL，则必须将 PropertyKeyCount 设置为零。

[out, optional] RequiredPropertyKeyCount

指向接收所请求属性键数的 DWORD 类型变量的指针。 指针是可选的，可以设置为 NULL。

[in] Flags

以下值之一，指定是检索设备安装程序类的类属性键还是检索设备接口类的类属性键。

DICLASSPROP_INSTALLER

ClassGuid 指定设备安装类。 此标志不能与DICLASSPROP_INTERFACE一起使用。

DICLASSPROP_INTERFACE

ClassGuid 指定设备接口类。 此标志不能与DICLASSPROP_INSTALLER一起使用。

[in, optional] MachineName

指向以 NULL 结尾的字符串的指针，该字符串包含计算机的 UNC 名称（包括“\”前缀）。 指针可以为 NULL。 如果指针为 NULL， 则 SetupDiGetClassPropertyKeysEx 将从本地计算机检索请求的信息。

注意

从Windows 8和Windows Server 2012开始，不支持使用此函数访问远程计算机，因为此功能已被删除。

Reserved

此参数必须设置为 NULL。

返回值

SetupDiGetClassPropertyKeysEx 如果成功，则返回 TRUE 。 否则，它将返回 FALSE，并且可以通过调用 GetLastError 来检索记录的错误。

下表包含此函数可能记录的一些更常见的错误代码。

返回代码 说明
ERROR_INVALID_FLAGS
 Flags 的值无效。
ERROR_INVALID_CLASS
 如果指定了 DICLASSPROP_INSTALLER 标志，则此错误代码指示 不存在由 ClassGuid 指定的设备安装类。
ERROR_INVALID_REFERENCE_STRING
 ClassGuild 指定的设备接口的引用字符串无效。 指定DICLASSPROP_INTERFACE标志时，可能会返回此错误。
ERROR_INVALID_DATA
 未指定的数据值无效。 一种可能性是 ClassGuid 值无效。
ERROR_INVALID_PARAMETER
 未指定的参数无效。
ERROR_INVALID_USER_BUFFER
 用户缓冲区无效。 一种可能性是 PropertyKeyArray 为 NULL， 而 PropertKeyCount 不为零。
ERROR_INVALID_MACHINENAME
 由 MachineName 指定的计算机名无效。
ERROR_NO_SUCH_INTERFACE_CLASS
 如果指定了DICLASSPROP_INTERFACE标志，则此错误代码指示 ClassGuid 指定的设备接口类不存在。
ERROR_INSUFFICENT_BUFFER
 PropertyKeyArray 缓冲区不够大，无法容纳所有属性键，或者传递给系统调用的内部数据缓冲区太小。
ERROR_NOT_ENOUGH_MEMORY
 系统内存不足，无法完成操作。
ERROR_ACCESS_DENIED
 调用方没有管理员权限。

注解

SetupDiGetClassPropertyKeysEx 是 统一设备属性模型的一部分。

SetupDiGetClassPropertyKeysEx 的调用方必须是 Administrators 组的成员才能检索设备类的设备属性键。

如果 PropertyKeyArray 缓冲区不够大，无法容纳所有请求的属性键， 则 SetupDiGetClassPropertyKeysEx 不会检索任何属性键并返回ERROR_INSUFFICIENT_BUFFER。 如果调用方提供了 RequiredPropertyKeyCount 指针， 则 SetupDiGetClassPropertyKeysEx 会将 *RequiredPropertyKeyCount 的值设置为 PropertyKeyArray 缓冲区的所需大小（以 DEVPROPKEY 类型值为单位）。

若要检索远程计算机上的设备类属性，请调用 SetupDiGetClassPropertyEx，若要在远程计算机上设置设备类属性，请调用 SetupDiSetClassPropertyEx。

若要检索本地计算机上的设备安装程序类或设备接口类的属性键，请调用 SetupDiGetClassPropertyKeys。

要求

要求 值
最低受支持的客户端 在 Windows Vista 和更高版本的 Windows 中可用。
目标平台 桌面对于通用，请调用 CM_Get_Class_Property_Keys_Ex
标头 setupapi.h (包括 Setupapi.h)
Library Setupapi.lib

另请参阅

SetupDiGetClassPropertyEx

SetupDiGetClassPropertyKeys

SetupDiSetClassPropertyEx