Função DevGetObjects (devquery.h)

Recupera de forma síncrona um conjunto de estruturas de DEV_OBJECT com base nas propriedades solicitadas e nos critérios de filtro fornecidos.

Sintaxe

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

Parâmetros

[in] ObjectType

Um valor da enumeração DEV_OBJECT_TYPE que determina o tipo de objeto no qual essa consulta deve operar.

[in] QueryFlags

Uma combinação de valores DEV_QUERY_FLAGS combinados usando uma operação OR bit a bit. Não é válido passar DevQueryFlagUpdateResults ou DevQueryFlagAsyncClose para essa função.

[in] cRequestedProperties

O número de estruturas de DEVPROPCOMPKEY fornecidas em pRequestedProperties. Se DevQueryFlagAllProperties for especificado, isso deverá ser definido como 0.

[in, optional] pRequestedProperties

Opcionalmente, fornece uma matriz de estruturas de DEVPROPCOMPKEY que especificam as propriedades que devem ser recuperadas para objetos no conjunto de resultados da consulta quando pCallback é chamado para notificar a consulta de uma adição de um objeto ao conjunto de resultados.
Se DevQueryFlagUpdateResults tiver sido especificado noQueryFlags, a consulta será notificada se o valor de qualquer uma dessas propriedades for alterado para qualquer objeto no conjunto de resultados da consulta.

O campo LocaleName da estrutura de DEVPROPCOMPKEY é ignorado e deve ser definido como NULL.

Se cRequestedProperties for 0, isso deverá ser NULL.

[in] cFilterExpressionCount

O número de estruturas de DEVPROP_FILTER_EXPRESSION fornecidas nopFilter .

[in, optional] pFilter

Opcionalmente, fornece uma matriz de estruturas de DEVPROP_FILTER_EXPRESSION que especificam critérios de filtro para quais objetos devem fazer parte do conjunto de resultados da consulta. Se cFilterExpressionCount for 0, isso deverá ser NULL.

[out] pcObjectCount

O número de estruturas de DEV_OBJECT retornadas em ppObjects.

[out] ppObjects

Ponteiro que recebe a matriz recém-alocada de resultados DEV_OBJECT. Os chamadores devem liberar o ponteiro usando DevFreeObjects. Se nenhum objeto for enumerado, NULL será retornado.

Valor de retorno

S_OK será retornado se a função tiver avaliado com êxito os critérios de pesquisa e retornado objetos correspondentes; caso contrário, um valor de erro apropriado.

Observações

Essa função é uma maneira eficiente de enumerar objetos de forma síncrona ao recuperar suas propriedades. A matriz de objetos retornados deve ser liberada usando DevFreeObjects. Se uma propriedade solicitada não existir para um objeto que atenda aos critérios de filtro, a entrada DEVPROPERTY no DEV_OBJECT dessa propriedade terá um tipo de DEVPROP_TYPE_EMPTY.

Antes de usar essa função, considere a quantidade de dados que podem ser retornados na matriz e por quanto tempo a chamada pode ser bloqueada. Talvez seja melhor usar a função de DevCreateObjectQuery, que permite que os dados sejam consumidos por etapas e de forma assíncrona.

Exemplo

O exemplo a seguir demonstra o uso de DevGetObjects para recuperar o conjunto de DEV_OBJECT que corresponde a um conjunto de estruturas 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 = 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;
}

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 10 versão 1809
servidor com suporte mínimo	Windows Server 2019
cabeçalho	devquery.h
biblioteca	Onecore.lib
de DLL	Cfgmgr32.dll

Consulte também

DevCreateObjectQuery