DevCreateObjectQueryFromIds, fonction (devquery.h)

Crée une requête d’appareil pour récupérer des propriétés en fonction des paramètres de requête spécifiés et d’une liste d’ID d’objet.

Syntaxe

HRESULT DevCreateObjectQueryFromIds(
  [in]           DEV_OBJECT_TYPE                 ObjectType,
  [in]           PCZZWSTR                        pszzObjectIds,
  [in]           ULONG                           QueryFlags,
  [in]           ULONG                           cRequestedProperties,
  [in, optional] const DEVPROPCOMPKEY            *pRequestedProperties,
  [in]           ULONG                           cFilterExpressionCount,
  [in, optional] const DEVPROP_FILTER_EXPRESSION *pFilter,
  [in]           PDEV_QUERY_RESULT_CALLBACK      pCallback,
  [in, optional] PVOID                           pContext,
  [out]          PHDEVQUERY                      phDevQuery
);

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] pszzObjectIds

Une liste multi-sz d’identificateurs d’objets pour les objets sur lesquels la requête doit fonctionner. Pour plus d’informations sur les chaînes multi-sz, consultez REG_MULTI_SZ.

[in] QueryFlags

Combinaison de valeurs DEV_QUERY_FLAGS combinées à l’aide d’une opération OR au niveau du bit.

[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 LocaleName de la structure DEVPROPCOMPKEY est ignoré et doit être défini sur NULL.

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] pCallback

Une fonction de rappel PDEV_QUERY_RESULT_CALLBACK à laquelle les résultats de cette requête doivent être envoyés.

[in, optional] pContext

Contexte fourni par l’appelant. Cette valeur est passée à la fonction de rappel non modifiée.

[out] phDevQuery

Pointeur qui reçoit le handle représentant la requête. Si DevQueryFlagsUpdateResults est spécifié, la requête reçoit les mises à jour jusqu’à ce que le handle soit fermé. Appelez DevCloseObjectQuery pour fermer ce handle pour arrêter la requête.

Valeur de retour

S_OK est retourné si une requête a été créée avec succès ; sinon, valeur d’erreur appropriée.

Remarques

Lorsqu’un client souhaite récupérer des données sur un ensemble spécifique d’objets en fonction de son identité, utilisez cette fonction plutôt que DevCreateObjectQuery avec un filtre. Cette fonction est plus efficace.

Pour plus d’informations, consultez la section remarques de DevCreateObjectQuery, qui s’applique également à cette fonction.

Exemple

Dans l’exemple suivant, la méthode PDEV_QUERY_RESULT_CALLBACK est implémentée pour imprimer les messages d’état lorsque l’état de la requête change, lorsque les éléments ont été ajoutés, mis à jour ou supprimés du résultat de la requête. Ensuite, un scénario de requête simple est implémenté où DevCreateObjectQueryFromIds est appelé avec une liste multi-sz d’ID d’objet passée dans la fonction dans l’argument InterfacePaths.

void WINAPI
Example1Callback(
    HDEVQUERY hDevQuery,
    PVOID pContext,
    const DEV_QUERY_RESULT_ACTION_DATA *pActionData
    )
{
    UNREFERENCED_PARAMETER(hDevQuery);
    UNREFERENCED_PARAMETER(pContext);

    switch (pActionData->Action)
    {
    case DevQueryResultStateChange:
        if (pActionData->Data.State == DevQueryStateEnumCompleted)
        {
            wprintf(L"Enumeration of current system state complete.\n");
        }
        else if (pActionData->Data.State == DevQueryStateAborted)
        {
            wprintf(L"Query has aborted. No further results will be received.\n");
            // Communicate back to the creator of the query that it has aborted
            // so it can handle that appropriately, such as by recreating the
            // query
        }
        break;

    case DevQueryResultAdd:
        wprintf(L"Object '%ws' has been added to the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultUpdate:
        wprintf(L"Object '%ws' was updated.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;

    case DevQueryResultRemove:
        wprintf(L"Object '%ws' has been removed from the result set.\n",
                pActionData->Data.DeviceObject.pszObjectId);
        break;
    }
}

void
Example1(PCZZWSTR InterfacePaths)
{
    DEVPROPCOMPKEY RequestedProperties[] =
    {
        { DEVPKEY_DeviceInterface_Enabled, DEVPROP_STORE_SYSTEM, NULL },
        { DEVPKEY_DeviceInterface_FriendlyName, DEVPROP_STORE_SYSTEM, NULL }
    };

    HDEVQUERY hDevQuery = NULL;
    HRESULT hr = DevCreateObjectQueryFromIds(DevObjectTypeDeviceInterface,
                                             InterfacePaths,
                                             DevQueryFlagUpdateResults,
                                             RTL_NUMBER_OF(RequestedProperties),
                                             RequestedProperties,
                                             0,
                                             NULL,
                                             Example1Callback,
                                             NULL,
                                             &hDevQuery);

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

    // do other work while the query monitors system state in the background

  exit:

    if (hDevQuery != NULL)
    {
        DevCloseObjectQuery(hDevQuery);
    }

    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

Voir aussi

DevCreateObjectQuery