DevGetObjectsEx 함수(devquery.h)
제공된 요청된 속성, 확장 매개 변수 및 필터 조건에 따라 DEV_OBJECT 구조 집합을 동기적으로 검색합니다.
통사론
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
);
매개 변수
[in] ObjectType
이 쿼리가 작동해야 하는 개체 형식을 결정하는 DEV_OBJECT_TYPE 열거형의 값입니다.
[in] QueryFlags
비트 OR 연산을 사용하여 결합된 DEV_QUERY_FLAGS 값의 조합입니다. DevQueryFlagUpdateResults
[in] cRequestedProperties
pRequestedProperties제공된 DEVPROPCOMPKEY 구조의 수입니다. DevQueryFlagAllProperties 지정한 경우 0으로 설정해야 합니다.
[in, optional] pRequestedProperties
필요에 따라 pCallback 호출될 때 쿼리 결과 집합의 개체에 대해 검색해야 하는 속성을 지정하는 DEVPROPCOMPKEY 구조체의 배열을 제공하여 결과 집합에 개체가 추가되었음을 쿼리에 알립니다.
DevQueryFlagUpdateResultsQueryFlags지정한 경우 쿼리의 결과 집합에 있는 개체에 대해 이러한 속성 값이 변경되면 쿼리에 알림이 표시됩니다.
DEVPROPCOMPKEY 구조체의 LocaleName 필드는 무시되며 NULL로 설정해야 합니다.
cRequestedProperties 0이면 NULL이어야 합니다.
[in] cFilterExpressionCount
pFilter제공된 DEVPROP_FILTER_EXPRESSION 구조체의 수입니다.
[in, optional] pFilter
필요에 따라 쿼리 결과 집합의 일부여야 하는 개체에 대한 필터 조건을 지정하는 DEVPROP_FILTER_EXPRESSION 구조의 배열을 제공합니다. cFilterExpressionCount 0이면 NULL이어야 합니다.
[in] cExtendedParameterCount
시스템 사용을 위해 예약되어 있습니다. 0으로 설정해야 합니다.
[in, optional] pExtendedParameters
시스템 사용을 위해 예약되어 있습니다. NULL로 설정해야 합니다.
[out] pcObjectCount
ppObjects에서 반환된 DEV_OBJECT 구조체의 수입니다.
[out] ppObjects
새로 할당된 DEV_OBJECT 결과 배열을 수신하는 포인터입니다. 호출자는 DevFreeObjects사용하여 포인터를 해제해야 합니다. 열거된 개체가 없으면 NULL이 반환됩니다.
반환 값
함수가 검색 조건을 성공적으로 평가하고 일치하는 개체를 반환하면 S_OK 반환됩니다. 그렇지 않으면 적절한 오류 값입니다.
발언
이 함수는 속성을 검색하는 동안 개체를 동기적으로 열거하는 효율적인 방법입니다. 반환되는 개체의 배열은 DevFreeObjects사용하여 해제되어야 합니다. 필터 조건을 충족하는 개체에 대해 요청된 속성이 없으면 해당 속성에 대한 DEV_OBJECTDEVPROPERTY 항목에는 DEVPROP_TYPE_EMPTY형식이 있습니다.
이 함수를 사용하기 전에 배열에서 반환될 수 있는 데이터의 양과 호출이 차단할 수 있는 기간을 고려합니다. 데이터를 증분 및 비동기적으로 사용할 수 있는 DevCreateObjectQueryEx 함수를 사용하는 것이 더 좋을 수 있습니다.
다음 예제에서는 DevGetObjectsEx 사용하여 DEVPROP_FILTER_EXPRESSION 구조 집합과 일치하는 DEV_OBJECT 집합을 검색하는 방법을 보여 줍니다.
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;
}
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 10 버전 1809 |
| 지원되는 최소 서버 | Windows Server 2019 |
| 헤더 | devquery.h |
| 라이브러리 | Onecore.lib |
| DLL | Cfgmgr32.dll |