Función SetupDiGetClassPropertyKeysExW (setupapi.h)
La función SetupDiGetClassPropertyKeysEx 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 en un equipo local o remoto.
Sintaxis
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
);
Parámetros
[in] ClassGuid
Puntero a un GUID que representa una clase de configuración de dispositivo o una clase de interfaz de dispositivo. SetupDiGetClassPropertyKeysEx recupera una matriz de las claves de propiedad del dispositivo que representan las propiedades de dispositivo establecidas 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 configuración del 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 de tipo DEVPROPKEY, del búfer PropertyKeyArray . Si PropertyKeyArray se establece 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 puntero es opcional y se puede establecer en NULL.
[in] Flags
Uno de los valores siguientes, que especifica si se deben recuperar claves de propiedad de clase 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.
[in, optional] MachineName
Puntero a una cadena terminada en NULL que contiene el nombre UNC, incluido el prefijo "\", de un equipo. El puntero puede ser NULL. Si el puntero es NULL, SetupDiGetClassPropertyKeysEx recupera la información solicitada del equipo local.
Precaución
No se admite el uso de esta función para acceder a máquinas remotas a partir de Windows 8 y Windows Server 2012, ya que esta funcionalidad se ha quitado.
Reserved
Este parámetro debe establecerse en NULL.
Valor devuelto
SetupDiGetClassPropertyKeysEx 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 |
|---|---|
|
El valor de Flags no es válido. |
|
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. |
|
La cadena de referencia de la interfaz de dispositivo especificada por ClassGuild no es válida. Este error puede devolverse cuando se especifica la marca DICLASSPROP_INTERFACE. |
|
Un valor de datos no especificado no es válido. Una posibilidad es que el valor ClassGuid no sea válido. |
|
Un parámetro no especificado no es válido. |
|
Un búfer de usuario no es válido. Una posibilidad es que PropertyKeyArray sea NULL y PropertKeyCount no sea cero. |
|
El nombre de equipo especificado por MachineName no es válido. |
|
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. |
|
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. |
|
No había suficiente memoria del sistema disponible para completar la operación. |
|
El autor de la llamada no tiene privilegios de administrador. |
Comentarios
SetupDiGetClassPropertyKeysEx forma parte del modelo de propiedades de dispositivo unificado.
Un autor de llamada de SetupDiGetClassPropertyKeysEx 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, SetupDiGetClassPropertyKeysEx no recupera ninguna clave de propiedad y devuelve ERROR_INSUFFICIENT_BUFFER. Si el autor de la llamada proporcionó un puntero RequiredPropertyKeyCount, SetupDiGetClassPropertyKeysEx 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 remoto, llame a SetupDiGetClassPropertyEx y para establecer una propiedad de clase de dispositivo en un equipo remoto, llame a SetupDiSetClassPropertyEx.
Para recuperar las claves de propiedad de una clase de configuración de dispositivo o una clase de interfaz de dispositivo en un equipo local, llame a SetupDiGetClassPropertyKeys.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible en Windows Vista y versiones posteriores de Windows. |
| Plataforma de destino | DesktopFor universal, call CM_Get_Class_Property_Keys_Ex |
| Encabezado | setupapi.h (incluya Setupapi.h) |
| Library | Setupapi.lib |