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

Синхронно извлекает набор структур DEV_OBJECT на основе предоставленных запрошенных свойств, расширенных параметров и критериев фильтрации.

Синтаксис

HRESULT DevGetObjectsEx(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           ULONG                           cExtendedParameterCount,
  [in, optional] const DEV_QUERY_PARAMETER       *pExtendedParameters,
  [out]          PULONG                          pcObjectCount,
  [out]          const DEV_OBJECT                **ppObjects
);

Параметры

[in] ObjectType

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

[in] QueryFlags

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

[in] cRequestedProperties

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

[in, optional] pRequestedProperties

При необходимости предоставляет массив структуры DEVPROPCOMP KEY, указывающие свойства, которые следует извлечь для объектов в результирующем наборе запроса при вызове pCallback, чтобы уведомить запрос о добавлении объекта в результирующий набор.
Если devQueryFlagUpdateResults был указан в QueryFlags, запрос будет уведомлен, если значение любого из этих свойств изменяется для любого объекта в результирующем наборе запроса.

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

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

[in] cFilterExpressionCount

Количество структур DEVPROP_FILTER_EXPRESSION, предоставляемых в pFilter.

[in, optional] pFilter

При необходимости предоставляет массив структур DEVPROP_FILTER_EXPRESSION, определяющих критерии фильтрации для объектов, которые должны быть частью результирующий набор запроса. Если cFilterExpressionCount равно 0, это значение должно иметь значение NULL.

[in] cExtendedParameterCount

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

[in, optional] pExtendedParameters

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

[out] pcObjectCount

Число DEV_OBJECT структур, возвращаемых в ppObjects.

[out] ppObjects

Указатель, который получает только что выделенный массив результатов DEV_OBJECT. Вызывающие объекты должны освободить указатель с помощью DevFreeObjects. Если объекты не перечисляются, возвращается значение NULL.

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

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

Замечания

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

Прежде чем использовать эту функцию, рассмотрите, сколько данных может быть возвращено в массиве и сколько времени вызов может блокировать. Возможно, лучше использовать функцию DevCreateObjectQueryEx, что позволяет использовать данные по фрагментам и асинхронно.

В следующем примере показано использование DevGetObjectsEx для получения набора DEV_OBJECT, соответствующего набору структур DEVPROP_FILTER_EXPRESSION.

void
Example1()
{
    HRESULT hr = S_OK;
    ULONG ObjectCount = 0;
    const DEV_OBJECT* ObjectList = NULL;
    DEVPROP_BOOLEAN DevPropTrue = DEVPROP_TRUE;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_InstanceId, DEVPROP_STORE_SYSTEM, NULL }
    };
    DEVPROP_FILTER_EXPRESSION ObjectFilter[] =
    {
        {
            DEVPROP_OPERATOR_AND_OPEN, {0}
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_BOOLEAN,
                sizeof(DevPropTrue),
                (void*)&DevPropTrue
            }
        },
        {
            DEVPROP_OPERATOR_OR_OPEN, {0}
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVINTERFACE_MOUSE
            }
        },
        {
            DEVPROP_OPERATOR_EQUALS,
            {
                { DEVPKEY_DeviceInterface_ClassGuid, DEVPROP_STORE_SYSTEM, NULL },
                DEVPROP_TYPE_GUID,
                sizeof(GUID),
                (void*)&GUID_DEVINTERFACE_KEYBOARD
            }
        },
        {
            DEVPROP_OPERATOR_OR_CLOSE, {0}
        },
        {
            DEVPROP_OPERATOR_AND_CLOSE, {0}
        }
    };

    hr = DevGetObjectsEx(DevObjectTypeDeviceInterface,
                         DevQueryFlagNone,
                         RTL_NUMBER_OF(RequestedProperties),
                         RequestedProperties,
                         RTL_NUMBER_OF(ObjectFilter),
                         ObjectFilter,
                         0,
                         NULL,
                         &ObjectCount,
                         &ObjectList);

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

    for (ULONG i = 0; i < ObjectCount; i++)
    {
        wprintf(L"Retrieved object '%ws'\n",
                ObjectList[i].pszObjectId);
    }

  exit:

    if (ObjectList != NULL)
    {
        DevFreeObjects(ObjectCount, ObjectList);
    }

    return;
}

Требования

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

См. также

DevCreateObjectQuery