Função DevCreateObjectQueryFromIds (devquery.h)

Artigo
11/15/2024

Cria uma consulta de dispositivo para recuperar propriedades com base nos parâmetros de consulta especificados e em uma lista de IDs de objeto.

Sintaxe

HRESULT DevCreateObjectQueryFromIds(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCZZWSTR                        pszzObjectIds,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           PDEV_QUERY_RESULT_CALLBACK      pCallback,
  [in, optional] PVOID                           pContext,
  [out]          PHDEVQUERY                      phDevQuery
);

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] pszzObjectIds

Uma lista de vários sz de identificadores de objeto para objetos em que a consulta deve operar. Para obter informações sobre cadeias de caracteres de vários sz, consulte REG_MULTI_SZ.

[in] QueryFlags

Uma combinação de valores DEV_QUERY_FLAGS combinados usando uma operação OR bit a bit.

[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.

[in] pCallback

Uma função de retorno de chamada PDEV_QUERY_RESULT_CALLBACK para a qual os resultados dessa consulta devem ser enviados.

[in, optional] pContext

Contexto fornecido pelo chamador. Esse valor é passado para a função de retorno de chamada sem modificação.

[out] phDevQuery

Ponteiro que recebe o identificador que representa a consulta. Se DevQueryFlagsUpdateResults for especificado, a consulta receberá atualizações até que o identificador seja fechado. Chame DevCloseObjectQuery para fechar esse identificador para interromper a consulta.

Valor de retorno

S_OK será retornado se uma consulta tiver sido criada com êxito; caso contrário, um valor de erro apropriado.

Observações

Quando um cliente quiser recuperar dados sobre um conjunto específico de objetos que recebem sua identidade, use essa função em vez de DevCreateObjectQuery com um filtro. Essa função é mais eficiente.

Para obter mais informações, consulte a seção de comentários do DevCreateObjectQuery, que também se aplicam a essa função.

Exemplo

No exemplo a seguir, o método PDEV_QUERY_RESULT_CALLBACK é implementado para imprimir mensagens de status quando o estado da consulta é alterado, quando os itens são adicionados, atualizados ou removidos do resultado da consulta. Em seguida, um cenário de consulta simples é implementado em que DevCreateObjectQueryFromIds é chamado com uma lista multissz de IDs de objeto passadas para a função no argumento InterfacePaths.

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    UNREFERENCED_PARAMETER(hDevQuery);
    UNREFERENCED_PARAMETER(pContext);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query
        }
        break;

    case DevQueryResultAdd:
        wprintf(L"Object '%ws' has been added to the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultUpdate:
        wprintf(L"Object '%ws' was updated.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultRemove:
        wprintf(L"Object '%ws' has been removed from the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;
    }
}

void
Example1(PCZZWSTR InterfacePaths)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromIds(DevObjectTypeDeviceInterface,
                                             InterfacePaths,
                                             DevQueryFlagUpdateResults,
                                             RTL_NUMBER_OF(RequestedProperties),
                                             RequestedProperties,
                                             0,
                                             NULL,
                                             Example1Callback,
                                             NULL,
                                             &hDevQuery);

    if (FAILED(hr))
    {
        wprintf(L"Failed to create query. hr = 0x%08x\n", hr);
        goto exit;
    }

    // do other work while the query monitors system state in the background

  exit:

    if (hDevQuery != NULL)
    {
        DevCloseObjectQuery(hDevQuery);
    }

    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

Compartilhar via