DevGetObjects 函式 （devquery.h）

根據提供的要求屬性和篩選準則，同步擷取一組 DEV_OBJECT 結構。

語法

HRESULT DevGetObjects(
  [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,
  [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。

[out] pcObjectCount

ppObjects 中傳回的 DEV_OBJECT 結構數目。

[out] ppObjects

接收新配置的 DEV_OBJECT 結果陣列的指標。 呼叫端必須使用 DevFreeObjects釋放指標。 如果未列舉任何物件，則會傳回 NULL。

傳回值

如果函式成功評估搜尋準則並傳回相符物件，則會傳回S_OK;否則為適當的錯誤值。

言論

此函式是在擷取物件屬性時同步列舉物件的有效率方式。 傳回的物件陣列必須使用 DevFreeObjects釋放。 如果符合篩選準則的物件不存在要求的屬性，則該屬性的 DEV_OBJECTDEVPROPERTY 專案會有 DEVPROP_TYPE_EMPTY類型。

使用這個函式之前，請考慮數位中可能會傳回多少數據，以及呼叫可以封鎖的時間長度。 最好是使用 DevCreateObjectQuery 函式，以異步方式取用數據。

例

下列範例示範如何使用 DevGetObjects 來擷取符合一組 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 = DevGetObjects(DevObjectTypeDeviceInterface,
                       DevQueryFlagNone,
                       RTL_NUMBER_OF(RequestedProperties),
                       RequestedProperties,
                       RTL_NUMBER_OF(ObjectFilter),
                       ObjectFilter,
                       &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