Función DevGetObjectsEx (devquery.h)

Recupera sincrónicamente un conjunto de estructuras de DEV_OBJECT basadas en las propiedades solicitadas proporcionadas, los parámetros extendidos y los criterios de filtro.

Sintaxis

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

Parámetros

[in] ObjectType

Valor de la enumeración DEV_OBJECT_TYPE que determina el tipo de objeto en el que debe funcionar esta consulta.

[in] QueryFlags

Combinación de DEV_QUERY_FLAGS valores que se combinan mediante una operación OR bit a bit. No es válido pasar DevQueryFlagUpdateResults o DevQueryFlagAsyncClose a esta función.

[in] cRequestedProperties

Número de estructuras de DEVPROPCOMPKEY proporcionadas en pRequestedProperties. Si se especifica DevQueryFlagAllProperties, debe establecerse en 0.

[in, optional] pRequestedProperties

Opcionalmente, proporciona una matriz de estructuras de DEVPROPCOMPKEY que especifican las propiedades que se deben recuperar para los objetos del conjunto de resultados de la consulta cuando se llama a pCallback para notificar a la consulta una adición de un objeto a su conjunto de resultados.
Si se especificó DevQueryFlagUpdateResults en QueryFlags, se notificará a la consulta si el valor de cualquiera de estas propiedades cambia para cualquier objeto del conjunto de resultados de la consulta.

El campo LocaleName del estructura de DEVPROPCOMPKEY se omite y debe establecerse en NULL.

Si cRequestedProperties es 0, debe ser NULL.

[in] cFilterExpressionCount

Número de estructuras de DEVPROP_FILTER_EXPRESSION proporcionadas en pFilter.

[in, optional] pFilter

Opcionalmente, proporciona una matriz de estructuras de DEVPROP_FILTER_EXPRESSION que especifican criterios de filtro para qué objetos deben formar parte del conjunto de resultados de la consulta. Si cFilterExpressionCount es 0, debe ser NULL.

[in] cExtendedParameterCount

Reservado para el uso del sistema. Debe establecerse en 0.

[in, optional] pExtendedParameters

Reservado para el uso del sistema. Debe establecerse en NULL.

[out] pcObjectCount

Número de estructuras de DEV_OBJECT devueltas en ppObjects.

[out] ppObjects

Puntero que recibe la matriz recién asignada de DEV_OBJECT resultados. Los llamadores deben liberar el puntero mediante DevFreeObjects. Si no se enumera ningún objeto, se devolverá NULL.

Valor devuelto

S_OK se devuelve si la función evaluó correctamente los criterios de búsqueda y devolvió objetos coincidentes; de lo contrario, es un valor de error adecuado.

Observaciones

Esta función es una manera eficaz de enumerar objetos de forma sincrónica al recuperar sus propiedades. La matriz de objetos devueltos debe liberarse mediante DevFreeObjects. Si no existe una propiedad solicitada para un objeto que cumpla los criterios de filtro, la entrada DEVPROPERTY en el DEV_OBJECT de esa propiedad tendrá un tipo de DEVPROP_TYPE_EMPTY.

Antes de usar esta función, considere la cantidad de datos que se pueden devolver en la matriz y cuánto tiempo puede bloquear la llamada. Puede ser mejor usar la función DevCreateObjectQueryEx, lo que permite que los datos se consuman por etapas y de forma asincrónica.

En el ejemplo siguiente se muestra el uso de DevGetObjectsEx para recuperar el conjunto de DEV_OBJECT que coincide con un conjunto de estructuras de 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;
}

Requisitos

Consulte también

DevCreateObjectQuery