WdfRegistryQueryMultiString, fonction (wdfregistry.h)

Article
02/07/2025

[S’applique à KMDF et UMDF]

La méthode WdfRegistryQueryMultiString récupère les chaînes actuellement affectées à une valeur de registre multi-chaîne spécifiée, crée un objet de chaîne de framework pour chaque chaîne et ajoute chaque objet de chaîne à une collection d’objets spécifiée.

Syntaxe

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

Paramètres

[in] Key

Handle vers un objet de clé de Registre qui représente une clé de Registre ouverte.

[in] ValueName

Pointeur vers une structure UNICODE_STRING qui contient un nom de valeur.

[in, optional] StringsAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES qui contient des attributs d’objet pour chaque nouvel objet de chaîne. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[in] Collection

Handle vers un objet de collection d’infrastructure fourni par le pilote.

Valeur de retour

WdfRegistryQueryMultiString retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Retourner le code	Description
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryMultiString n’a pas été appelé à IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer un objet de chaîne.
STATUS_ACCESS_DENIED	Le pilote n’a pas ouvert la clé de Registre avec KEY_QUERY_VALUE, KEY_READ ou un accès KEY_ALL_ACCESS.
STATUS_OBJECT_TYPE_MISMATCH	Le type de données de la valeur de Registre spécifiée par le paramètre ValueName spécifié n’a pas été REG_MULTI_SZ.
STATUS_OBJECT_NAME_NOT_FOUND	La valeur du Registre n’a pas été disponible.
STATUS_RESOURCE_DATA_NOT_FOUND	La valeur de Registre existe sous la clé spécifiée, mais est vide.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfRegistryQueryMultiString peut retourner, consultez Framework Object Creation Errors.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

Avant que votre pilote appelle WdfRegistryQueryMultiString, il doit appeler WdfCollectionCreate pour créer un objet de collection.

Si l’appelant ne fournit pas de paramètre StringsAttributes, les objets WDFSTRING créés par l’infrastructure sont par défaut parentés du WDFDRIVER.

Après WdfRegistryQueryMultiString, le pilote peut appeler WdfCollectionGetCount pour obtenir le nombre de chaînes récupérées et WdfCollectionGetItem pour obtenir des objets de chaîne de la collection.

Si la collection contient des objets avant que le pilote appelle la méthode WdfRegistryQueryMultiString, la méthode ne supprime pas ces objets ou ne modifie pas leurs valeurs d’index. Les nouveaux objets sont ajoutés à la fin de la collection.

Pour obtenir une chaîne à partir d’un objet de chaîne, le pilote peut appeler WdfStringGetUnicodeString.

Pour plus d’informations sur les objets de clé de Registre, consultez Utilisation du Registre dans Framework-Based Drivers.

Exemples

L’exemple de code suivant crée un objet de collection, initialise une structure WDF_OBJECT_ATTRIBUTES afin que l’objet de collection soit le parent de tous les objets de chaîne créés par l’infrastructure pour la collection et récupère les chaînes d’une valeur de Registre à plusieurs chaînes. Enfin, l’exemple obtient le nombre d’objets de chaîne que l’infrastructure a ajoutés à la collection.

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfregistry.h (include Wdf.h)
bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)