DevGetObjects function (devquery.h)

Article
11/15/2024

Synchronously retrieves a set of DEV_OBJECT structures based on the supplied requested properties and filter criteria.

Syntax

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

Parameters

[in] ObjectType

A value from the DEV_OBJECT_TYPE enumeration that determines the object type that this query should operate on.

[in] QueryFlags

A combination of DEV_QUERY_FLAGS values that are combined by using a bitwise OR operation. It is not valid to pass either DevQueryFlagUpdateResults or DevQueryFlagAsyncClose to this function.

[in] cRequestedProperties

The number of DEVPROPCOMPKEY structures provided in pRequestedProperties. If DevQueryFlagAllProperties is specified, this must be set to 0.

[in, optional] pRequestedProperties

Optionally provides an array of DEVPROPCOMPKEY structures that specify the properties that should be retrieved for objects in the query’s result set when pCallback is called to notify the query of an addition of an object to its result set.
If DevQueryFlagUpdateResults was specified in QueryFlags, the query will be notified if the value of any of these properties changes for any object in the query’s result set.

The LocaleName field of the DEVPROPCOMPKEY structure is ignored and must be set to NULL.

If cRequestedProperties is 0, this must be NULL.

[in] cFilterExpressionCount

The number of DEVPROP_FILTER_EXPRESSION structures provided in pFilter.

[in, optional] pFilter

Optionally provides an array of DEVPROP_FILTER_EXPRESSION structures that specify filter criteria for what objects should be part of the query’s result set. If cFilterExpressionCount is 0, this must be NULL.

[out] pcObjectCount

The number of DEV_OBJECT structures returned in ppObjects.

[out] ppObjects

Pointer that receives the newly allocated array of DEV_OBJECT results. Callers must free the pointer using DevFreeObjects. If no objects are enumerated, NULL will be returned.

Return value

S_OK is returned if the function successfully evaluated the search criteria and returned matching objects; otherwise, an appropriate error value.

Remarks

This function is an efficient way to synchronously enumerate objects while retrieving their properties. The array of objects that are returned must be freed using DevFreeObjects. If a requested property does not exist for an object that meets the filter criteria, then the DEVPROPERTY entry in the DEV_OBJECT for that property will have a type of DEVPROP_TYPE_EMPTY.

Before using this function, consider how much data may be returned in the array and how long the call can block. It may be better to use the DevCreateObjectQuery function, which allows the data to be consumed piecemeal and asynchronously.

Example

The following example demonstrates the usage of DevGetObjects to retrieve the set of DEV_OBJECT that matches a set of DEVPROP_FILTER_EXPRESSION structures.

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

Requirements

Requirement	Value
Minimum supported client	Windows 10 version 1809
Minimum supported server	Windows Server 2019
Header	devquery.h
Library	Onecore.lib
DLL	Cfgmgr32.dll

Share via