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

Статья
11/15/2024

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

Синтаксис

HRESULT DevCreateObjectQueryFromIds(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCZZWSTR                        pszzObjectIds,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           PDEV_QUERY_RESULT_CALLBACK      pCallback,
  [in, optional] PVOID                           pContext,
  [out]          PHDEVQUERY                      phDevQuery
);

Параметры

[in] ObjectType

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

[in] pszzObjectIds

Список идентификаторов объектов с несколькими sz для объектов, с которыми должен работать запрос. Сведения о строках с несколькими sz см. в REG_MULTI_SZ.

[in] QueryFlags

Сочетание значений DEV_QUERY_FLAGS, объединенных с помощью побитовой операции OR.

[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] pCallback

Функция обратного вызова PDEV_QUERY_RESULT_CALLBACK, в которую должны быть отправлены результаты этого запроса.

[in, optional] pContext

Контекст, предоставленный вызывающей компанией. Это значение передается функции обратного вызова, не измененной.

[out] phDevQuery

Указатель, который получает дескриптор, представляющий запрос. Если DevQueryFlagsUpdateResults, запрос получит обновления до закрытия дескриптора. Вызовите DevCloseObjectQuery, чтобы закрыть этот дескриптор, чтобы остановить запрос.

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

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

Замечания

Если клиент хочет получить данные о определенном наборе объектов с учетом удостоверения, используйте эту функцию, а не DevCreateObjectQuery с фильтром. Эта функция более эффективна.

Дополнительные сведения см. в разделе примечаний DevCreateObjectQuery, которые также применяются к этой функции.

Пример

В следующем примере метод PDEV_QUERY_RESULT_CALLBACK реализуется для вывода сообщений о состоянии запроса при изменении состояния запроса, когда элементы были добавлены, обновлены или удалены из результата запроса. Далее реализуется простой сценарий запроса, в котором DevCreateObjectQueryFromId s вызывается с несколькими идентификаторами объектов, передаваемыми в функцию в аргументе InterfacePaths.

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    UNREFERENCED_PARAMETER(hDevQuery);
    UNREFERENCED_PARAMETER(pContext);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query
        }
        break;

    case DevQueryResultAdd:
        wprintf(L"Object '%ws' has been added to the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultUpdate:
        wprintf(L"Object '%ws' was updated.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultRemove:
        wprintf(L"Object '%ws' has been removed from the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;
    }
}

void
Example1(PCZZWSTR InterfacePaths)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromIds(DevObjectTypeDeviceInterface,
                                             InterfacePaths,
                                             DevQueryFlagUpdateResults,
                                             RTL_NUMBER_OF(RequestedProperties),
                                             RequestedProperties,
                                             0,
                                             NULL,
                                             Example1Callback,
                                             NULL,
                                             &hDevQuery);

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

    // do other work while the query monitors system state in the background

  exit:

    if (hDevQuery != NULL)
    {
        DevCloseObjectQuery(hDevQuery);
    }

    return;
}

Требования

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

См. также

DevCreateObjectQuery

Поделиться через