Função DevGetObjectPropertiesEx (devquery.h)

Recupere de forma síncrona um conjunto de propriedades para um objeto especificado opcionalmente com base nos parâmetros estendidos especificados.

Sintaxe

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

Um valor do DEV_OBJECT_TYPE que determina o tipo de objeto para o qual as propriedades devem ser recuperadas.

[in] pszObjectId

A identidade do objeto para o qual as propriedades devem ser recuperadas.

[in] QueryFlags

Uma combinação de valores DEV_QUERY_FLAGS combinados usando uma operação OR bit a bit. Não é válido passar DevQueryFlagUpdateResults ou DevQueryFlagAsyncClose para essa função.

[in] cRequestedProperties

O número de estruturas de DEVPROPCOMPKEY fornecidas em pRequestedProperties. Se DevQueryFlagAllProperties for especificado, isso deverá ser definido como 0.

[in] pRequestedProperties

Fornece uma matriz de estruturas de DEVPROPCOMPKEY que especificam as propriedades que devem ser recuperadas para o objeto especificado.

O campo LocaleName da estrutura de DEVPROPCOMPKEY é ignorado e deve ser definido como NULL.

Se cRequestedProperties for 0, isso deverá ser NULL.

[in] cExtendedParameterCount

Reservado para uso do sistema. Deve ser definido como 0.

[in] pExtendedParameters

Reservado para uso do sistema. Deve ser definido como NULL.

[out] pcPropertyCount

O número de estruturas de DEVPROPERTY retornadas em ppProperties.

[out] ppProperties

Ponteiro que recebe a matriz recém-alocada de resultados de DEVPROPERTY. Os chamadores devem liberar o ponteiro usando DevFreeObjectProperties.

Valor de retorno

S_OK será retornado se a função tiver avaliado com êxito os critérios de pesquisa e retornado objetos correspondentes; caso contrário, um valor de erro apropriado.

Observações

Essa função é uma maneira eficiente de recuperar de forma síncrona um conjunto de propriedades de um objeto dado seu tipo e identidade. A matriz de propriedades retornadas deve ser liberada usando DevFreeObjectProperties. Se uma propriedade solicitada não existir, ppProperties ainda conterá uma entrada para essa propriedade, mas a entrada terá um tipo de DEVPROP_TYPE_EMPTY.

Exemplo

O exemplo a seguir demonstra a chamada DevGetObjectPropertiesEx para recuperar um conjunto de propriedades solicitadas e, em seguida, chamar DevFindProperty para encontrar uma propriedade específica dentro de uma matriz de estruturas de 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
de cliente com suporte mínimo	Windows 10 versão 1809
servidor com suporte mínimo	Windows Server 2019
cabeçalho	devquery.h
biblioteca	Onecore.lib
de DLL	Cfgmgr32.dll