Funzione DevGetObjectProperties (devquery.h)

Recuperare in modo sincrono un set di proprietà per un oggetto specificato

Sintassi

HRESULT DevGetObjectProperties(
  [in]  DEV_OBJECT_TYPE      ObjectType,
  [in]  PCWSTR               pszObjectId,
  [in]  ULONG                QueryFlags,
  [in]  ULONG                cRequestedProperties,
  [in]  const DEVPROPCOMPKEY *pRequestedProperties,
  [out] PULONG               pcPropertyCount,
  [out] const DEVPROPERTY    **ppProperties
);

Parametri

[in] ObjectType

Valore del DEV_OBJECT_TYPE che determina il tipo di oggetto per cui recuperare le proprietà.

[in] pszObjectId

Identità dell'oggetto per cui recuperare le proprietà.

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

Fornisce una matrice di strutture DEVPROPCOMPKEY che specificano le proprietà che devono essere recuperate per l'oggetto specificato.

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

Se cRequestedProperties è 0, deve essere NULL.

[out] pcPropertyCount

Numero di strutture DEVPROPERTY restituite in ppProperties.

[out] ppProperties

Puntatore che riceve la matrice appena allocata di risultati DEVPROPERTY. I chiamanti devono liberare il puntatore usando DevFreeObjectProperties.

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 recuperare in modo sincrono un set di proprietà da un oggetto in base al tipo e all'identità. La matrice di proprietà restituite deve essere liberata usando DevFreeObjectProperties. Se una proprietà richiesta non esiste, ppProperties conterrà comunque una voce per tale proprietà, ma la voce avrà un tipo di DEVPROP_TYPE_EMPTY.

Esempio

Nell'esempio seguente viene illustrata la chiamata di DevGetObjectProperties per recuperare un set di proprietà richieste e quindi chiamare DevFindProperty per trovare una determinata proprietà all'interno di una matrice di strutture DEVPROPERTY.

void
Example1(PCWSTR DeviceInstancePath)
{
    HRESULT hr = S_OK;
    const DEVPROPERTY* TempProperty = NULL;
    ULONG PropertyCount = 0;
    const DEVPROPERTY* PropertyList = NULL;
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_Device_HardwareIds, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_Device_CompatibleIds, DEVPROP_STORE_SYSTEM, NULL }
    };

    hr = DevGetObjectProperties(DevObjectTypeDevice,
                                DeviceInstancePath,
                                DevQueryFlagNone,
                                RTL_NUMBER_OF(RequestedProperties),
                                RequestedProperties,
                                &PropertyCount,
                                &PropertyList);

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

    wprintf(L"Hardware IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_HardwareIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Hardware IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

    wprintf(L"\nCompatible IDs:\n");
    TempProperty = DevFindProperty(&DEVPKEY_Device_CompatibleIds,
                                   DEVPROP_STORE_SYSTEM,
                                   NULL,
                                   PropertyCount,
                                   PropertyList);

    if ((TempProperty == NULL) ||
        (TempProperty->Type == DEVPROP_TYPE_EMPTY) ||
        (TempProperty->Buffer == NULL))
    {
        wprintf(L"<none>\n");
    }
    else if ((TempProperty->Type != DEVPROP_TYPE_STRING_LIST) ||
             (TempProperty->BufferSize < sizeof(WCHAR)))
    {
        wprintf(L"Device '%ws' has a corrupted Compatible IDs property.\n",
                DeviceInstancePath);
    }
    else
    {
        for (PCWSTR CurrentId = (PCWSTR)TempProperty->Buffer;
             *CurrentId != L'\0';
             CurrentId += wcslen(CurrentId) + 1)
        {
            wprintf(L"%ws\n", CurrentId);
        }
    }

  exit:

    if (PropertyList != NULL)
    {
        DevFreeObjectProperties(PropertyCount, PropertyList);
    }

    return;
}

Fabbisogno