Функция DevGetObjectPropertiesEx (devquery.h)

Синхронно извлекает набор свойств для указанного объекта при необходимости на основе указанных расширенных параметров.

Синтаксис

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
);

Параметры

[in] ObjectType

Значение из DEV_OBJECT_TYPE, определяющего тип объекта, для которого извлекаются свойства.

[in] pszObjectId

Удостоверение объекта, для которого извлекаются свойства.

[in] QueryFlags

Сочетание значений DEV_QUERY_FLAGS, объединенных с помощью побитовой операции OR. Недопустимо передать DevQueryFlagUpdateResults или DevQueryFlagAsyncClose этой функции.

[in] cRequestedProperties

Количество структур DEVPROPCOMPKEY, предоставляемых в pRequestedProperties. Если указан DevQueryFlagAllProperties, это значение должно иметь значение 0.

[in] pRequestedProperties

Предоставляет массив структуры DEVPROPCOMPKEY, указывающие свойства, которые должны быть получены для указанного объекта.

Поле LocaleName структуры DEVPROPCOMPKEY игнорируется и должно иметь значение NULL.

Если cRequestedProperties равно 0, это значение должно иметь значение NULL.

[in] cExtendedParameterCount

Зарезервировано для использования системы. Должно быть задано значение 0.

[in] pExtendedParameters

Зарезервировано для использования системы. Необходимо задать значение NULL.

[out] pcPropertyCount

Количество структур DEVPROPERTY, возвращенных в ppProperties.

[out] ppProperties

Указатель, который получает только что выделенный массив результатов DEVPROPER TY. Вызывающие объекты должны освободить указатель с помощью DevFreeObjectProperties.

Возвращаемое значение

S_OK возвращается, если функция успешно оценила критерии поиска и возвращала соответствующие объекты; в противном случае соответствующее значение ошибки.

Замечания

Эта функция является эффективным способом синхронного извлечения набора свойств из объекта, заданного его типом и удостоверением. Массив возвращаемых свойств должен быть освобожден с помощью DevFreeObjectProperties. Если запрошенное свойство не существует, ppProperties по-прежнему будет содержать запись для этого свойства, но запись будет иметь тип DEVPROP_TYPE_EMPTY.

Пример

В следующем примере демонстрируется вызов DevGetObjectPropertiesEx для получения набора запрошенных свойств, а затем вызова DevFindProperty для поиска определенного свойства в массиве структур 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;
}

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 10 версии 1809
минимальный поддерживаемый сервер	Windows Server 2019
заголовка	devquery.h
библиотеки	Onecore.lib
DLL	Cfgmgr32.dll