Fonction WdfRegistryQueryMultiString (wdfregistry.h)
[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 d’infrastructure pour chaque chaîne et ajoute chaque objet string à 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 d’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 de 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 d’un objet de collection d’infrastructure fourni par le pilote.
Valeur retournée
WdfRegistryQueryMultiString retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :
Code de retour | Description |
---|---|
|
WdfRegistryQueryMultiString n’a pas été appelé à IRQL = PASSIVE_LEVEL. |
|
Un paramètre non valide a été spécifié. |
|
Impossible d’allouer un objet string. |
|
Le pilote n’a pas ouvert la clé de Registre avec un accès KEY_QUERY_VALUE, KEY_READ ou KEY_ALL_ACCESS. |
|
Le type de données de la valeur de Registre spécifiée par le paramètre ValueName n’a pas été REG_MULTI_SZ. |
|
La valeur du Registre n’était pas disponible. |
|
La valeur du 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 Erreurs de création d’objet Framework.
Cette méthode peut également retourner d’autres valeurs NTSTATUS.
Un bogue case activée 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 , tous les objets WDFSTRING créés par l’infrastructure sont parentés par défaut à WDFDRIVER.
Une fois que WdfRegistryQueryMultiString est retourné, 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 à partir 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 ni ne modifie leurs valeurs d’index. Les nouveaux objets sont ajoutés à la fin de la collection.
Pour obtenir une chaîne à partir d’un objet string, le pilote peut appeler WdfStringGetUnicodeString.
Pour plus d’informations sur les objets de clé de Registre, consultez Utilisation du Registre dans les pilotes Framework-Based.
Exemples
L’exemple de code suivant crée un objet de collection, initialise une structure de 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 multi-chaînes. Enfin, l’exemple obtient le nombre d’objets de chaîne ajoutés par l’infrastructure à 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);
Configuration requise
Condition requise | Valeur |
---|---|
Plateforme cible | Universal |
Version KMDF minimale | 1.0 |
Version UMDF minimale | 2.0 |
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) |