Funzione DevCreateObjectQueryFromId (devquery.h)

Crea una query del dispositivo per recuperare le proprietà in base ai parametri di query e all'ID oggetto specificati.

Sintassi

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

Parametri

[in] ObjectType

Valore dell'enumerazione DEV_OBJECT_TYPE che determina il tipo di oggetto su cui deve operare la query.

[in] pszObjectId

Identificatore di stringa per l'oggetto su cui deve operare la query.

[in] QueryFlags

Combinazione di valori DEV_QUERY_FLAGS combinati tramite un'operazione OR bit per bit.

[in] cRequestedProperties

Numero di strutture di DEVPROPCOMPKEY fornite in pRequestedProperties. Se si specifica DevQueryFlagAllProperties, deve essere impostato su 0.

[in, optional] pRequestedProperties

Facoltativamente, fornisce una matrice di strutture DEVPROPCOMPKEY che specificano le proprietà che devono essere recuperate per gli oggetti nel set di risultati della query quando viene chiamato pCallback per notificare alla query un'aggiunta di un oggetto al relativo set di risultati.
Se DevQueryFlagUpdateResults è stato specificato in QueryFlags, la query riceverà una notifica se il valore di una di queste proprietà cambia per qualsiasi oggetto nel set di risultati della query.

Il campo LocaleName della struttura DEVPROPCOMPKEY viene ignorato e deve essere impostato su NULL.

Se cRequestedProperties è 0, deve essere NULL.

[in] cFilterExpressionCount

Numero di strutture DEVPROP_FILTER_EXPRESSION fornite in pFilter.

[in, optional] pFilter

Facoltativamente, fornisce una matrice di strutture di DEVPROP_FILTER_EXPRESSION che specificano i criteri di filtro per gli oggetti che devono far parte del set di risultati della query. Se cFilterExpressionCount è 0, deve essere NULL.

[in] pCallback

Una funzione di callback PDEV_QUERY_RESULT_CALLBACK a cui devono essere inviati i risultati per questa query.

[in, optional] pContext

Contesto fornito dal chiamante. Questo valore viene passato alla funzione di callback non modificata.

[out] phDevQuery

Puntatore che riceve l'handle che rappresenta la query. Se viene specificato DevQueryFlagsUpdateResults, la query riceverà gli aggiornamenti fino alla chiusura dell'handle. Chiamare DevCloseObjectQuery per chiudere questo handle per arrestare la query.

Valore restituito

S_OK viene restituito se una query è stata creata correttamente; in caso contrario, un valore di errore appropriato.

Osservazioni

Quando un client desidera recuperare dati su un oggetto specifico in base alla relativa identità, usare questa funzione anziché DevCreateObjectQuery con un filtro. Questa funzione è più efficiente.

Per altre informazioni, vedere la sezione osservazioni di DevCreateObjectQuery, che si applicano anche a questa funzione.

Esempi

Nell'esempio seguente il metodo PDEV_QUERY_RESULT_CALLBACK viene implementato per stampare i messaggi di stato quando lo stato della query cambia, quando gli elementi sono stati aggiunti, aggiornati o rimossi dal risultato della query. Viene quindi implementato uno scenario di query semplice in cui DevCreateObjectQueryFromId viene chiamato con l'ID oggetto specificato dalla variabile 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;
}

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 10 versione 1809
intestazione	devquery.h
libreria	Onecore.lib
dll	Cfgmgr32.dll

Vedere anche

DevCreateObjectQuery