DevGetObjectsEx-Funktion (devquery.h)
Ruft synchron eine Reihe von DEV_OBJECT Strukturen basierend auf den bereitgestellten angeforderten Eigenschaften, erweiterten Parametern und Filterkriterien ab.
Syntax
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
);
Parameter
[in] ObjectType
Ein Wert aus der DEV_OBJECT_TYPE-Aufzählung, der den Objekttyp bestimmt, für den diese Abfrage ausgeführt werden soll.
[in] QueryFlags
Eine Kombination aus DEV_QUERY_FLAGS Werten, die mithilfe eines bitweisen OR-Vorgangs kombiniert werden. Es ist ungültig, entweder DevQueryFlagUpdateResults oder DevQueryFlagAsyncClose- an diese Funktion zu übergeben.
[in] cRequestedProperties
Die Anzahl der DEVPROPCOMPKEY- Strukturen, die in pRequestedPropertiesbereitgestellt werden. Wenn DevQueryFlagAllProperties- angegeben ist, muss dies auf 0 festgelegt werden.
[in, optional] pRequestedProperties
Stellt optional ein Array von DEVPROPCOMPKEY- Strukturen bereit, die die Eigenschaften angeben, die für Objekte im Resultset der Abfrage abgerufen werden sollen, wenn pCallback- aufgerufen wird, um die Abfrage über das Hinzufügen eines Objekts zu seinem Resultset zu benachrichtigen.
Wenn DevQueryFlagUpdateResults- in QueryFlags-angegeben wurde, wird die Abfrage benachrichtigt, wenn sich der Wert dieser Eigenschaften für ein Objekt im Resultset der Abfrage ändert.
Das LocaleName- Feld der DEVPROPCOMPKEY- Struktur wird ignoriert und muss auf NULL festgelegt werden.
Wenn cRequestedProperties 0 ist, muss dies NULL sein.
[in] cFilterExpressionCount
Die Anzahl der in pFilterbereitgestellten DEVPROP_FILTER_EXPRESSION Strukturen.
[in, optional] pFilter
Stellt optional ein Array von DEVPROP_FILTER_EXPRESSION Strukturen bereit, die Filterkriterien für die Objekte angeben, die Teil des Resultsets der Abfrage sein sollen. Wenn cFilterExpressionCount 0 ist, muss dies NULL sein.
[in] cExtendedParameterCount
Reserviert für die Systemverwendung. Muss auf 0 festgelegt sein.
[in, optional] pExtendedParameters
Reserviert für die Systemverwendung. Muss auf NULL festgelegt werden.
[out] pcObjectCount
Die Anzahl der in ppObjects zurückgegebenen DEV_OBJECT Strukturen.
[out] ppObjects
Zeiger, der das neu zugeordnete Array von DEV_OBJECT Ergebnissen empfängt. Aufrufer müssen den Zeiger mit DevFreeObjectsfreigeben. Wenn keine Objekte aufgezählt werden, wird NULL zurückgegeben.
Rückgabewert
S_OK wird zurückgegeben, wenn die Funktion die Suchkriterien erfolgreich ausgewertet und übereinstimmende Objekte zurückgegeben hat; andernfalls ein entsprechender Fehlerwert.
Bemerkungen
Diese Funktion ist eine effiziente Möglichkeit zum synchronen Aufzählen von Objekten beim Abrufen ihrer Eigenschaften. Das Array der zurückgegebenen Objekte muss mit DevFreeObjectsfreigegeben werden. Wenn für ein Objekt, das den Filterkriterien entspricht, keine angeforderte Eigenschaft vorhanden ist, weist der DEVPROPERTY Eintrag in der DEV_OBJECT für diese Eigenschaft einen Typ von DEVPROP_TYPE_EMPTYauf.
Bevor Sie diese Funktion verwenden, überlegen Sie, wie viele Daten im Array zurückgegeben werden können und wie lange der Aufruf blockiert werden kann. Es kann besser sein, die DevCreateObjectQueryEx--Funktion zu verwenden, wodurch die Daten asynchron genutzt werden können.
Im folgenden Beispiel wird die Verwendung von DevGetObjectsEx- veranschaulicht, um den Satz von DEV_OBJECT abzurufen, der einer Reihe von DEVPROP_FILTER_EXPRESSION Strukturen entspricht.
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;
}
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 10, Version 1809 |
| mindestens unterstützte Server- | Windows Server 2019 |
| Header- | devquery.h |
| Library | Onecore.lib |
| DLL- | Cfgmgr32.dll |