Funzione DevCreateObjectQueryFromIds (devquery.h)

Articolo
11/15/2024

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

Sintassi

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

Parametri

[in] ObjectType

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

[in] pszzObjectIds

Un elenco a più sz di identificatori di oggetto per gli oggetti su cui deve operare la query. Per informazioni sulle stringhe a più sz, vedere REG_MULTI_SZ.

[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 vuole recuperare dati su un set specifico di oggetti 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.

Esempio

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. Successivamente, viene implementato uno scenario di query semplice in cui DevCreateObjectQueryFromIds viene chiamato con un elenco multisz di ID oggetto passati alla funzione nell'argomento 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;
}

Fabbisogno

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

Vedere anche

DevCreateObjectQuery

Condividi tramite