Función SetupDiGetCustomDevicePropertyA (setupapi.h)

Artículo
08/26/2023

La función SetupDiGetCustomDeviceProperty recupera una propiedad de dispositivo personalizada especificada del Registro.

Sintaxis

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

Parámetros

[in] DeviceInfoSet

Identificador del conjunto de información del dispositivo que contiene un elemento de información del dispositivo que representa el dispositivo para el que se va a recuperar una propiedad de dispositivo personalizada.

[in] DeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA que especifica el elemento de información del dispositivo en DeviceInfoSet.

[in] CustomPropertyName

Nombre de valor del Registro que representa una propiedad personalizada.

[in] Flags

Valor de marca que indica cómo se debe devolver la información solicitada. La marca puede ser cero o una de las siguientes:

DICUSTOMDEVPROP_MERGE_MULTISZ

Si se establece, la función recupera los valores de propiedad específicos de la instancia de dispositivo y los valores de propiedad específicos del identificador de hardware, concatenados como una cadena con tipo REG_MULTI_SZ. (Para obtener más información, vea la sección Comentarios de esta página de referencia).

[out, optional] PropertyRegDataType

Puntero a una variable de tipo DWORD que recibe el tipo de datos de la propiedad recuperada. El tipo de datos se especifica como una de las constantes con prefijo REG_ que representa los tipos de datos del Registro. Este parámetro es opcional y puede ser NULL.

[out] PropertyBuffer

Puntero a un búfer que recibe información de propiedad solicitada.

[in] PropertyBufferSize

Tamaño, en bytes, del búfer PropertyBuffer .

[out, optional] RequiredSize

Puntero a una variable de tipo DWORD que recibe el tamaño del búfer, en bytes, necesario para recibir la información solicitada. Este parámetro es opcional y puede ser NULL. Si se especifica este parámetro, SetupDiGetCustomDeviceProperty devuelve el tamaño necesario, independientemente de si el búfer PropertyBuffer es lo suficientemente grande como para recibir la información solicitada.

Valor devuelto

Si la operación se realiza correctamente, SetupDiGetCustomDeviceProperty devuelve TRUE. De lo contrario, la función devuelve FALSE y el error registrado se puede recuperar con una llamada a GetLastError. Si el búfer PropertyBuffer no es lo suficientemente grande como para recibir la información solicitada, SetupDiGetCustomDeviceProperty devuelve FALSE y una llamada posterior a GetLastError devolverá ERROR_INSUFFICIENT_BUFFER.

Comentarios

SetupDiGetCustomDeviceProperty recupera las propiedades del dispositivo asociadas a una sola instancia de dispositivo o con todos los dispositivos que coinciden con un determinado identificador de hardware. (Para obtener información sobre los identificadores de hardware, consulte Cadenas de identificación de dispositivos).

Los proveedores pueden establecer propiedades para una instancia de dispositivo mediante directivas ADDReg inf en las secciones INF DDInstall.HW y especificando la raíz del registro HKR .

Solo el sistema puede establecer propiedades para los identificadores de hardware. El sistema proporciona una propiedad "Icon" para algunos identificadores de hardware.

La función comprueba primero si la propiedad especificada existe para la instancia de dispositivo especificada. Si es así, se devuelve el valor de la propiedad. Si no es así, la función comprueba si la propiedad existe para todos los dispositivos que coincidan con el identificador de hardware de la instancia de dispositivo especificada. Si es así, se devuelve el valor de la propiedad. Si DICUSTOMDEVPROP_MERGE_MULTISZ se establece en Flags, la función devuelve los valores de propiedad asociados a la instancia del dispositivo y al identificador de hardware, si ambos existen.

Nota

El encabezado setupapi.h define SetupDiGetCustomDeviceProperty como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows XP y versiones posteriores de Windows.
Plataforma de destino	Escritorio
Encabezado	setupapi.h (incluya Setupapi.h)
Library	Setupapi.lib
Archivo DLL	Setupapi.dll