Função DevCreateObjectQueryFromId (devquery.h)

Artigo
11/15/2024

Cria uma consulta de dispositivo para recuperar propriedades com base nos parâmetros de consulta especificados e na ID do objeto.

Sintaxe

HRESULT DevCreateObjectQueryFromId(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCWSTR                          pszObjectId,
  [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] pszObjectId

O identificador de cadeia de caracteres para o objeto no qual a consulta deve operar.

[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 objeto específico dada a 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.

Exemplos

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 DevCreateObjectQueryFromId é chamado com a ID do objeto especificada pela variável InterfacePath.

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(PCWSTR InterfacePath)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromId(DevObjectTypeDeviceInterface,
                                            InterfacePath,
                                            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
cabeçalho	devquery.h
biblioteca	Onecore.lib
de DLL	Cfgmgr32.dll

Consulte também

DevCreateObjectQuery

Compartilhar via