FONCTION OREnumValue
Énumère les valeurs de la clé de Registre ouverte spécifiée dans une ruche de Registre hors connexion. La fonction récupère des informations pour une valeur sous la clé spécifiée chaque fois que la fonction est appelée.
Syntaxe
DWORD OREnumValue(
_In_ ORHKEY Handle,
_In_ DWORD dwIndex,
_Out_ PWSTR lpValueName,
_Inout_ PDWORD lpcValueName,
_Out_opt_ PDWORD lpType,
_Out_opt_ PBYTE lpData,
_Inout_opt_ PDWORD lpcbData
);
Paramètres
-
Gérer [in]
-
Handle d’une clé de Registre ouverte dans une ruche de Registre hors connexion.
-
dwIndex [in]
-
Index de la valeur à récupérer. Ce paramètre doit être égal à zéro pour le premier appel à la fonction, puis incrémenté pour les appels suivants.
Étant donné que les valeurs ne sont pas triées, toute nouvelle valeur aura un index arbitraire. Cela signifie que la fonction peut retourner des valeurs dans n’importe quel ordre.
-
lpValueName [out]
-
Pointeur vers une mémoire tampon qui reçoit le nom de la valeur sous la forme d’une chaîne terminée par null. Cette mémoire tampon doit être suffisamment grande pour inclure le caractère null de fin.
Pour plus d’informations, consultez Limites de taille des éléments du Registre.
-
lpcValueName [in, out]
-
Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée vers le paramètre lpValueName , en caractères. Lorsque la fonction retourne, la variable reçoit le nombre de caractères stockés dans la mémoire tampon, sans inclure le caractère null de fin.
-
lpType [out, facultatif]
-
Pointeur vers une variable qui reçoit un code indiquant le type de données stockées dans la valeur spécifiée. Pour obtenir la liste des codes de type possibles, consultez Types de valeurs de registre. Le paramètre lpType peut avoir la valeur NULL si le code de type n’est pas requis.
-
lpData [out, facultatif]
-
Pointeur vers une mémoire tampon qui reçoit les données de l’entrée de valeur. Ce paramètre peut avoir la valeur NULL si les données ne sont pas requises.
Si lpData a la valeur NULL et lpcbData n’est pas NULL, la fonction stocke la taille des données, en octets, dans la variable pointée par lpcbData. Cela permet à une application de déterminer la meilleure façon d’allouer une mémoire tampon pour les données.
-
lpcbData [in, out, optional]
-
Pointeur vers une variable qui spécifie la taille de la mémoire tampon pointée vers le paramètre lpData , en octets. Lorsque la fonction retourne, la variable reçoit le nombre d’octets stockés dans la mémoire tampon.
Ce paramètre peut avoir la valeur NULL uniquement si lpData a la valeur NULL.
Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, cette taille inclut les caractères null de fin. Pour plus d'informations, consultez la section Notes.
Si la mémoire tampon spécifiée par lpData n’est pas assez grande pour contenir les données, la fonction retourne ERROR_MORE_DATA et stocke la taille de mémoire tampon requise dans la variable pointée par lpcbData. Dans ce cas, le contenu de lpData n’est pas défini.
Valeur retournée
Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.
Si la fonction échoue, la valeur de retour est un code d’erreur différent de zéro défini dans Winerror.h. Vous pouvez utiliser la fonction FormatMessage avec l’indicateur FORMAT_MESSAGE_FROM_SYSTEM pour obtenir une description générique de l’erreur.
Si la mémoire tampon lpData est trop petite pour recevoir la valeur, la fonction retourne ERROR_MORE_DATA.
Notes
Pour énumérer des valeurs, une application doit initialement appeler la fonction OREnumValue avec le paramètre dwIndex défini sur zéro. L’application doit ensuite incrémenter dwIndex et appeler la fonction OREnumValue jusqu’à ce qu’il n’y ait plus de valeurs (jusqu’à ce que la fonction retourne ERROR_NO_MORE_ITEMS).
L’application peut également définir dwIndex sur l’index de la dernière valeur lors du premier appel à la fonction et décrémenter l’index jusqu’à ce que la valeur avec l’index 0 soit énumérée. Pour récupérer l’index de la dernière valeur, utilisez la fonction ORQueryInfoKey .
Lors de l’utilisation d’OREnumValue, une application ne doit pas appeler des fonctions de Registre hors connexion susceptibles de modifier la clé interrogée.
Si les données ont le type REG_SZ, REG_MULTI_SZ ou REG_EXPAND_SZ, la chaîne n’a peut-être pas été stockée avec les caractères null appropriés. Par conséquent, même si la fonction retourne ERROR_SUCCESS, l’application doit s’assurer que la chaîne est correctement arrêtée avant de l’utiliser ; sinon, il peut remplacer une mémoire tampon. (Notez que REG_MULTI_SZ chaînes doivent avoir deux caractères de fin null.)
Pour déterminer la taille maximale des mémoires tampons de nom et de données, utilisez la fonction ORQueryInfoKey .
Spécifications
| Condition requise | Valeur |
|---|---|
| Composant redistribuable |
Bibliothèque du Registre hors connexion Windows version 1.0 ou ultérieure |
| En-tête |
|
| DLL |
|
Voir aussi