Función DevGetObjectPropertiesEx (devquery.h)

Recupera sincrónicamente un conjunto de propiedades para un objeto especificado opcionalmente en función de los parámetros extendidos especificados.

Sintaxis

HRESULT DevGetObjectPropertiesEx(
  [in]  DEV_OBJECT_TYPE           ObjectType,
  [in]  PCWSTR                    pszObjectId,
  [in]  ULONG                     QueryFlags,
  [in]  ULONG                     cRequestedProperties,
  [in]  const DEVPROPCOMPKEY      *pRequestedProperties,
  [in]  ULONG                     cExtendedParameterCount,
  [in]  const DEV_QUERY_PARAMETER *pExtendedParameters,
  [out] PULONG                    pcPropertyCount,
  [out] const DEVPROPERTY         **ppProperties
);

Parámetros

[in] ObjectType

Valor de la DEV_OBJECT_TYPE que determina el tipo de objeto para el que se van a recuperar las propiedades.

[in] pszObjectId

Identidad del objeto para el que se van a recuperar las propiedades.

[in] QueryFlags

Combinación de DEV_QUERY_FLAGS valores que se combinan mediante una operación OR bit a bit. No es válido pasar DevQueryFlagUpdateResults o DevQueryFlagAsyncClose a esta función.

[in] cRequestedProperties

Número de estructuras de DEVPROPCOMPKEY proporcionadas en pRequestedProperties. Si se especifica DevQueryFlagAllProperties, debe establecerse en 0.

[in] pRequestedProperties

Proporciona una matriz de estructuras de DEVPROPCOMPKEY que especifican las propiedades que se deben recuperar para el objeto especificado.

El campo LocaleName del estructura de DEVPROPCOMPKEY se omite y debe establecerse en NULL.

Si cRequestedProperties es 0, debe ser NULL.

[in] cExtendedParameterCount

Reservado para el uso del sistema. Debe establecerse en 0.

[in] pExtendedParameters

Reservado para el uso del sistema. Debe establecerse en NULL.

[out] pcPropertyCount

Número de estructuras de DEVPROPERTY devueltas en ppProperties.

[out] ppProperties

Puntero que recibe la matriz recién asignada de resultados DEVPROPERTY. Los llamadores deben liberar el puntero mediante DevFreeObjectProperties.

Valor devuelto

S_OK se devuelve si la función evaluó correctamente los criterios de búsqueda y devolvió objetos coincidentes; de lo contrario, es un valor de error adecuado.

Observaciones

Esta función es una manera eficaz de recuperar de forma sincrónica un conjunto de propiedades de un objeto dado su tipo e identidad. La matriz de propiedades devueltas debe liberarse mediante DevFreeObjectProperties. Si no existe una propiedad solicitada, ppProperties seguirán contienendo una entrada para esa propiedad, pero la entrada tendrá un tipo de DEVPROP_TYPE_EMPTY.

Ejemplo

En el ejemplo siguiente se muestra cómo llamar a DevGetObjectPropertiesEx para recuperar un conjunto de propiedades solicitadas y, a continuación, llamar a DevFindProperty para buscar una propiedad determinada dentro de una matriz de estructuras DEVPROPERTY.

void
Example1(PCWSTR DeviceInstancePath)
{
    HRESULT hr = S_OK;
    const DEVPROPERTY* TempProperty = NULL;
    ULONG PropertyCount = 0;
    const DEVPROPERTY* PropertyList = NULL;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_HardwareIds, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_Device_CompatibleIds, DEVPROP_STORE_SYSTEM, NULL }
    };

    hr = DevGetObjectPropertiesEx(DevObjectTypeDevice,
                                  DeviceInstancePath,
                                  DevQueryFlagNone,
                                  RTL_NUMBER_OF(RequestedProperties),
                                  RequestedProperties,
                                  0,
                                  NULL,
                                  &PropertyCount,
                                  &PropertyList);

    if (FAILED(hr))
    {
        wprintf(L"Failed to retrieve properties. hr = 0x%08x\n", hr);
        goto exit;
    }

    wprintf(L"Hardware IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_HardwareIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Hardware IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

    wprintf(L"\nCompatible IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_CompatibleIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Compatible IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

  exit:

    if (PropertyList != NULL)
    {
        DevFreeObjectProperties(PropertyCount, PropertyList);
    }

    return;
}

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 10, versión 1809
servidor mínimo admitido	Windows Server 2019
encabezado de	devquery.h
biblioteca de	Onecore.lib
DLL de	Cfgmgr32.dll