DevGetObjectsEx, fonction (devquery.h)
Récupère de façon synchrone un ensemble de structures DEV_OBJECT en fonction des propriétés demandées fournies, des paramètres étendus et des critères de filtre fournis.
Syntaxe
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
);
Paramètres
[in] ObjectType
Valeur de l’énumération DEV_OBJECT_TYPE qui détermine le type d’objet sur lequel cette requête doit fonctionner.
[in] QueryFlags
Combinaison de valeurs DEV_QUERY_FLAGS combinées à l’aide d’une opération OR au niveau du bit. Il n’est pas valide de passer DevQueryFlagUpdateResults ou DevQueryFlagAsyncClose à cette fonction.
[in] cRequestedProperties
Nombre de structures DEVPROPCOMPKEY fournies dans pRequestedProperties. Si DevQueryFlagAllProperties est spécifié, cette valeur doit être définie sur 0.
[in, optional] pRequestedProperties
Fournit éventuellement un tableau de structures DEVPROPCOMPKEY qui spécifient les propriétés qui doivent être récupérées pour les objets dans le jeu de résultats de la requête lorsque pCallback est appelé pour notifier la requête d’un ajout d’un objet à son jeu de résultats.
Si DevQueryFlagUpdateResults a été spécifié dans QueryFlags, la requête est avertie si la valeur de l’une de ces propriétés change pour un objet dans le jeu de résultats de la requête.
Le champ
Si cRequestedProperties est 0, cette valeur doit être NULL.
[in] cFilterExpressionCount
Nombre de structures DEVPROP_FILTER_EXPRESSION fournies dans pFilter .
[in, optional] pFilter
Fournit éventuellement un tableau de structures DEVPROP_FILTER_EXPRESSION qui spécifient des critères de filtre pour les objets qui doivent faire partie du jeu de résultats de la requête. Si cFilterExpressionCount est 0, cette valeur doit être NULL.
[in] cExtendedParameterCount
Réservé à l’utilisation du système. Doit être défini sur 0.
[in, optional] pExtendedParameters
Réservé à l’utilisation du système. Doit être défini sur NULL.
[out] pcObjectCount
Nombre de structures DEV_OBJECT retournées dans ppObjects.
[out] ppObjects
Pointeur qui reçoit le tableau nouvellement alloué de résultats DEV_OBJECT. Les appelants doivent libérer le pointeur à l’aide de DevFreeObjects. Si aucun objet n’est énuméré, NULL est retourné.
Valeur de retour
S_OK est retourné si la fonction a correctement évalué les critères de recherche et retourné des objets correspondants ; sinon, valeur d’erreur appropriée.
Remarques
Cette fonction est un moyen efficace d’énumérer de manière synchrone les objets lors de la récupération de leurs propriétés. Le tableau d’objets retournés doit être libéré à l’aide de DevFreeObjects. Si une propriété demandée n’existe pas pour un objet qui répond aux critères de filtre, l’entrée DEVPROPERTY dans le DEV_OBJECT de cette propriété aura un type de DEVPROP_TYPE_EMPTY.
Avant d’utiliser cette fonction, tenez compte de la quantité de données qui peuvent être retournées dans le tableau et de la durée pendant laquelle l’appel peut être bloqué. Il peut être préférable d’utiliser la fonction DevCreateObjectQueryEx, ce qui permet aux données d’être consommées de manière fragmentaire et asynchrone.
L’exemple suivant illustre l’utilisation de DevGetObjectsEx pour récupérer l’ensemble de DEV_OBJECT qui correspond à un ensemble de structures 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;
}
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 10 version 1809 |
| serveur minimum pris en charge | Windows Server 2019 |
| d’en-tête | devquery.h |
| bibliothèque | Onecore.lib |
| DLL | Cfgmgr32.dll |