DevGetObjectPropertiesEx 函式 （devquery.h）

根據指定的擴充參數選擇性地擷取指定物件的一組屬性。

語法

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

參數

[in] ObjectType

DEV_OBJECT_TYPE 的值，決定要擷取屬性的物件類型。

[in] pszObjectId

要擷取屬性之對象的識別。

[in] QueryFlags

使用位 OR 運算結合 DEV_QUERY_FLAGS 值的組合。 DevQueryFlagUpdateResults 或 DevQueryFlagAsyncClose 傳遞至此函式並無效。

[in] cRequestedProperties

pRequestedProperties中提供的 DEVPROPCOMPKEY 結構數目。 如果指定 DevQueryFlagAllProperties，則必須將此值設定為 0。

[in] pRequestedProperties

提供 DEVPROPCOMPKEY 結構陣列，指定應針對指定物件擷取的屬性。

DEVPROPCOMPKEY 結構的 LocaleName 字段會被忽略，而且必須設定為 NULL。

如果 cRequestedProperties 為 0，這必須是 NULL。

[in] cExtendedParameterCount

保留給系統使用量。 必須設定為 0。

[in] pExtendedParameters

保留給系統使用量。 必須設定為 NULL。

[out] pcPropertyCount

ppProperties中傳回 DEVPROPERTY 結構的數目。

[out] ppProperties

接收新配置的 DEVPROPERTY 陣列 結果的指標。 呼叫端必須使用 DevFreeObjectProperties釋放指標。

傳回值

如果函式成功評估搜尋準則並傳回相符物件，則會傳回S_OK;否則為適當的錯誤值。

言論

此函式是一種有效率的方式，可從物件中同步擷取一組屬性，並指定其類型和身分識別。 傳回的屬性陣列必須使用 DevFreeObjectProperties釋放。 如果要求的屬性不存在，ppProperties 仍會包含該屬性的專案，但專案的類型為 DEVPROP_TYPE_EMPTY。

例

下列範例示範如何呼叫 DevGetObjectPropertiesEx 來擷取一組要求的屬性，然後呼叫 DevFindProperty，以在 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 = DevGetObjectPropertiesEx(DevObjectTypeDevice,
                                  DeviceInstancePath,
                                  DevQueryFlagNone,
                                  RTL_NUMBER_OF(RequestedProperties),
                                  RequestedProperties,
                                  0,
                                  NULL,
                                  &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;
}

要求

要求	價值
最低支援的用戶端	Windows 10 版本 1809
支援的最低伺服器	Windows Server 2019
標頭	devquery.h
連結庫	Onecore.lib
DLL	Cfgmgr32.dll