Funzione DevGetObjectsEx (devquery.h)

Recupera in modo sincrono un set di strutture DEV_OBJECT in base alle proprietà richieste, ai parametri estesi e ai criteri di filtro specificati.

Sintassi

HRESULT DevGetObjectsEx(
  [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,
  [in]           ULONG                           cExtendedParameterCount,
  [in, optional] const DEV_QUERY_PARAMETER       *pExtendedParameters,
  [out]          PULONG                          pcObjectCount,
  [out]          const DEV_OBJECT                **ppObjects
);

Parametri

[in] ObjectType

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

[in] QueryFlags

Combinazione di valori DEV_QUERY_FLAGS combinati tramite un'operazione OR bit per bit. Non è valido passare DevQueryFlagUpdateResults o DevQueryFlagAsyncClose a questa funzione.

[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] cExtendedParameterCount

Riservato per l'utilizzo del sistema. Deve essere impostato su 0.

[in, optional] pExtendedParameters

Riservato per l'utilizzo del sistema. Deve essere impostato su NULL.

[out] pcObjectCount

Numero di strutture DEV_OBJECT restituite in ppObjects.

[out] ppObjects

Puntatore che riceve la matrice appena allocata di DEV_OBJECT risultati. I chiamanti devono liberare il puntatore usando DevFreeObjects. Se non vengono enumerati oggetti, verrà restituito NULL.

Valore restituito

S_OK viene restituito se la funzione ha valutato correttamente i criteri di ricerca e gli oggetti corrispondenti restituiti; in caso contrario, un valore di errore appropriato.

Osservazioni

Questa funzione è un modo efficiente per enumerare in modo sincrono gli oggetti durante il recupero delle relative proprietà. La matrice di oggetti restituiti deve essere liberata usando DevFreeObjects. Se una proprietà richiesta non esiste per un oggetto che soddisfa i criteri di filtro, la voce DEVPROPERTY nella DEV_OBJECT per tale proprietà avrà un tipo di DEVPROP_TYPE_EMPTY.

Prima di usare questa funzione, valutare la quantità di dati che possono essere restituiti nella matrice e quanto tempo la chiamata può bloccare. Potrebbe essere preferibile usare la funzione devCreateObjectQueryEx , che consente l'utilizzo dei dati a fasi e in modo asincrono.

Nell'esempio seguente viene illustrato l'utilizzo di DevGetObjectsEx per recuperare il set di DEV_OBJECT che corrisponde a un set di strutture 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 = DevGetObjectsEx(DevObjectTypeDeviceInterface,
                         DevQueryFlagNone,
                         RTL_NUMBER_OF(RequestedProperties),
                         RequestedProperties,
                         RTL_NUMBER_OF(ObjectFilter),
                         ObjectFilter,
                         0,
                         NULL,
                         &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;
}

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