Función SetupDiGetClassPropertyKeys (setupapi.h)

Artículo
03/15/2023

La función SetupDiGetClassPropertyKeys recupera una matriz de las claves de propiedad del dispositivo que representan las propiedades del dispositivo que se establecen para una clase de configuración de dispositivo o una clase de interfaz de dispositivo.

Sintaxis

WINSETUPAPI BOOL SetupDiGetClassPropertyKeys(
  [in]            const GUID *ClassGuid,
  [out, optional] DEVPROPKEY *PropertyKeyArray,
  [in]            DWORD      PropertyKeyCount,
  [out, optional] PDWORD     RequiredPropertyKeyCount,
  [in]            DWORD      Flags
);

Parámetros

[in] ClassGuid

Puntero a un GUID que representa una clase de configuración de dispositivo o una clase de interfaz de dispositivo. SetupDiGetClassPropertyKeys recupera una matriz de las claves de propiedad del dispositivo que representan las propiedades del dispositivo que se establecen para la clase especificada. Para obtener información sobre cómo especificar el tipo de clase, vea el parámetro Flags .

[out, optional] PropertyKeyArray

Puntero a un búfer que recibe una matriz de valores con tipo DEVPROPKEY, donde cada valor es una clave de propiedad de dispositivo que representa una propiedad de dispositivo que se establece para la clase de dispositivo. El puntero es opcional y puede ser NULL. Para obtener más información, vea la sección Comentarios más adelante en este tema.

[in] PropertyKeyCount

Tamaño, en valores con tipo DEVPROPKEY, del búfer PropertyKeyArray . Si PropertyKeyArray está establecido en NULL, PropertyKeyCount debe establecerse en cero.

[out, optional] RequiredPropertyKeyCount

Puntero a una variable con tipo DWORD que recibe el número de claves de propiedad solicitadas. El parámetro es opcional y se puede establecer en NULL.

[in] Flags

Uno de los siguientes valores, que especifica si se deben recuperar claves de propiedad para una clase de configuración de dispositivo o para una clase de interfaz de dispositivo:

DICLASSPROP_INSTALLER

ClassGuid especifica una clase de configuración de dispositivo. Esta marca no se puede usar con DICLASSPROP_INTERFACE.

DICLASSPROP_INTERFACE

ClassGuid especifica una clase de interfaz de dispositivo. Esta marca no se puede usar con DICLASSPROP_INSTALLER.

Valor devuelto

SetupDiGetClassPropertyKeys devuelve TRUE si se realiza correctamente. De lo contrario, devuelve FALSE y el error registrado se puede recuperar llamando a GetLastError.

En la tabla siguiente se incluyen algunos de los códigos de error más comunes que esta función podría registrar.

Código devuelto	Descripción
ERROR_INVALID_FLAGS	El valor de Flags no es válido.
ERROR_INVALID_CLASS	Si se especifica la marca DICLASSPROP_INSTALLER, este código de error indica que la clase de instalación del dispositivo especificada por ClassGuid no existe.
ERROR_INVALID_REFERENCE_STRING	La cadena de referencia de la interfaz de dispositivo especificada por ClassGuild no es válida. Este error se puede devolver si se especifica la marca DICLASSPROP_INTERFACE.
ERROR_INVALID_DATA	Un valor de datos no especificado no es válido. Una posibilidad es que el valor ClassGuid no sea válido.
ERROR_INVALID_PARAMETER	Un parámetro no especificado no es válido.
ERROR_INVALID_USER_BUFFER	Un búfer de usuario no es válido. Una posibilidad es que PropertyKeyArray sea NULL y PropertKeyCount no sea cero.
ERROR_NO_SUCH_INTERFACE_CLASS	Si se especifica la marca DICLASSPROP_INTERFACE, este código de error indica que la clase de interfaz de dispositivo especificada por ClassGuid no existe.
ERROR_INSUFFICENT_BUFFER	El búfer PropertyKeyArray no es lo suficientemente grande como para contener todas las claves de propiedad o un búfer de datos interno que se pasó a una llamada del sistema era demasiado pequeño.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria del sistema disponible para completar la operación.
ERROR_ACCESS_DENIED	El autor de la llamada no tiene privilegios de administrador.

Comentarios

SetupDiGetClassPropertyKeys forma parte del modelo de propiedades de dispositivo unificado.

Un llamador de SetupDiGetClassPropertyKeys debe ser miembro del grupo Administradores para recuperar las claves de propiedad del dispositivo para una clase de dispositivo.

Si el búfer PropertyKeyArray no es lo suficientemente grande como para contener todas las claves de propiedad solicitadas, SetupDiGetClassPropertyKeys no recupera ninguna clave de propiedad y devuelve ERROR_INSUFFICIENT_BUFFER. Si el autor de la llamada proporcionó un puntero RequiredPropertyKeyCount, SetupDiGetClassPropertyKeys establece el valor de *RequiredPropertyKeyCount en el tamaño necesario, en valores con tipo DEVPROPKEY, del búfer PropertyKeyArray.

Para recuperar una propiedad de clase de dispositivo en un equipo local, llame a SetupDiGetClassProperty. Para establecer una propiedad de clase de dispositivo en un equipo local, llame a SetupDiSetClassProperty.

Para recuperar las claves de propiedad de una clase de configuración de dispositivo o una clase de interfaz de dispositivo en un equipo remoto, llame a SetupDiGetClassPropertyKeysEx.

Requisitos


Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores de Windows.
Plataforma de destino	DesktopFor universal, call CM_Get_Class_Property_Keys
Encabezado	setupapi.h (incluya Setupapi.h)
Library	Setupapi.lib
Archivo DLL	Setupapi.dll