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

使用按位 OR 运算组合的 DEV_QUERY_FLAGS 值。 将 DevQueryFlagUpdateResults 或 DevQueryFlagAsyncClose 传递给此函数无效。

[in] cRequestedProperties

pRequestedProperties中提供的 DEVPROPCOMPKEY 结构的数目。 如果指定了 devQueryFlagAllProperties ，则必须将其设置为 0。

[in, optional] pRequestedProperties

（可选）提供一组 DEVPROPCOMPKEY 结构，该结构指定在调用 pCallback pCallback 时应为查询中对象检索的属性，以通知查询将对象添加到其结果集。
如果在 QueryFlags中指定了 DevQueryFlagUpdateResults，则查询将在查询结果集中的任何对象的任何属性的值发生更改时收到通知。

DEVPROPCOMPKEY 结构的 LocaleName 字段将被忽略，必须设置为 NULL。

如果 cRequestedProperties 为 0，则必须为 NULL。

[in] cFilterExpressionCount

pFilter中提供的 DEVPROP_FILTER_EXPRESSION 结构数。

[in, optional] pFilter

（可选）提供一个由 DEVPROP_FILTER_EXPRESSION 结构构成的数组，这些结构指定哪些对象应是查询结果集的一部分的筛选条件。 如果 cFilterExpressionCount 为 0，则必须为 NULL。

[in] cExtendedParameterCount

保留供系统使用。 必须设置为 0。

[in, optional] pExtendedParameters

保留供系统使用。 必须设置为 NULL。

[out] pcObjectCount

ppObjects 中返回的 DEV_OBJECT 结构数。

[out] ppObjects

接收新分配的 DEV_OBJECT 结果数组的指针。 调用方必须使用 DevFreeObjects释放指针。 如果未枚举任何对象，将返回 NULL。

返回值

如果函数成功计算了搜索条件并返回匹配对象，则返回S_OK;否则为适当的错误值。

言论

此函数是一种在检索对象属性时同步枚举对象的高效方法。 返回的对象数组必须使用 DevFreeObjects释放。 如果满足筛选条件的对象不存在请求的属性，则该属性的 DEV_OBJECT 中的 DEVPROPERTY 条目将具有 DEVPROP_TYPE_EMPTY类型。

使用此函数之前，请考虑数组中可能返回的数据量以及调用可以阻止多长时间。 最好使用 DevCreateObjectQueryEx 函数，从而允许数据以片段方式和异步方式使用。

以下示例演示如何使用 DevGetObjectsEx 检索与一组 DEVPROP_FILTER_EXPRESSION 结构匹配的 DEV_OBJECT 集。

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