Méthode IWbemServices ::CreateInstanceEnum (wbemcli.h)

La méthode IWbemServices ::CreateInstanceEnum crée un énumérateur qui retourne les instances d’une classe spécifiée en fonction des critères de sélection spécifiés par l’utilisateur. Cette méthode prend en charge les requêtes WQL simples ; les requêtes plus complexes peuvent être traitées à l’aide de la méthode IWbemServices ::ExecQuery .

Syntaxe

HRESULT CreateInstanceEnum(
  [in]  const BSTR           strFilter,
  [in]  long                 lFlags,
  [in]  IWbemContext         *pCtx,
  [out] IEnumWbemClassObject **ppEnum
);

Paramètres

[in] strFilter

BSTR valide contenant le nom de la classe pour laquelle les instances sont souhaitées. Ce paramètre ne peut pas être NULL.

[in] lFlags

Les indicateurs suivants affectent le comportement de cette méthode. La valeur suggérée pour ce paramètre est WBEM_FLAG_RETURN_IMMEDIATELY et WBEM_FLAG_FORWARD_ONLY pour de meilleures performances.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Si cet indicateur est défini, WMI récupère les qualificateurs modifiés stockés dans l’espace de noms localisé des paramètres régionaux de la connexion actuelle. S’il n’est pas défini, seuls les qualificateurs stockés dans l’espace de noms immédiat sont récupérés.

WBEM_FLAG_DEEP

Cet indicateur force l’énumération à inclure ceci et toutes les sous-classes dans la hiérarchie.

WBEM_FLAG_SHALLOW

Cet indicateur force l’énumération à inclure uniquement les instances pures de cette classe, à l’exclusion de toutes les instances de sous-classes qui fournissent des propriétés introuvables dans cette classe.

WBEM_FLAG_RETURN_IMMEDIATELY

Cet indicateur fait qu’il s’agit d’un appel semi-synchronisé. Pour plus d’informations, consultez Appel d’une méthode.

WBEM_FLAG_FORWARD_ONLY

Cet indicateur entraîne le retour d’un énumérateur avant uniquement. Les énumérateurs avant uniquement sont généralement beaucoup plus rapides et utilisent moins de mémoire que les énumérateurs conventionnels, mais n’autorisent pas les appels à cloner ou réinitialiser.

WBEM_FLAG_BIDIRECTIONAL

Cet indicateur oblige Windows Management à conserver les pointeurs vers les objets de l’énumération jusqu’à ce que le client libère l’énumérateur. Étant donné que les pointeurs d’objet ne sont pas libérés immédiatement, cette méthode peut échouer avec un hResult de WBEM_E_OUT_OF_MEMORY si le client tente d’énumérer un grand nombre d’objets. Cet indicateur est implicite par défaut si vous définissez le paramètre lFlags sur 0 (zéro).

WBEM_FLAG_DIRECT_READ

Cet indicateur entraîne un accès direct au fournisseur pour la classe spécifiée sans tenir compte de sa ou de ses sous-classes parentes.

[in] pCtx

Généralement NULL. Sinon, il s’agit d’un pointeur vers un objet IWbemContext qui peut être utilisé par le fournisseur qui fournit les instances demandées. Les valeurs de l’objet de contexte doivent être spécifiées dans la documentation du fournisseur en question. Pour plus d’informations sur ce paramètre, consultez Effectuer des appels à WMI.

[out] ppEnum

Reçoit le pointeur vers l’énumérateur, qui a un nombre de références positif. L’appelant doit appeler IUnknown ::Release sur le pointeur une fois qu’il n’est plus nécessaire.

Valeur retournée

Cette méthode retourne une valeur HRESULT qui indique le statut de l'appel de méthode. La liste suivante répertorie la valeur contenue dans un HRESULT.

En cas d’échec, vous pouvez obtenir toutes les informations disponibles à partir de la fonction COM GetErrorInfo.

Des codes d’erreur spécifiques à COM peuvent également être retournés si des problèmes réseau vous font perdre la connexion à distance à Windows Management.

Remarques

Il ne s’agit pas d’une erreur pour que l’énumérateur retourné n’ait aucun élément.

Configuration requise

Voir aussi

IWbemServices

IWbemServices::CreateInstanceEnumAsync

Récupération d’un code d’erreur