Fonction SetFirmwareEnvironmentVariableExA (winbase.h)
Définit la valeur de la variable d’environnement de microprogramme spécifiée en tant qu’attributs qui indiquent comment cette variable est stockée et gérée.
Syntaxe
BOOL SetFirmwareEnvironmentVariableExA(
[in] LPCSTR lpName,
[in] LPCSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize,
[in] DWORD dwAttributes
);
Paramètres
[in] lpName
Nom de la variable d’environnement du microprogramme. Le pointeur ne doit pas avoir la valeur NULL.
[in] lpGuid
GUID qui représente l’espace de noms de la variable d’environnement du microprogramme. Le GUID doit être une chaîne au format « {xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx} ». Si le système ne prend pas en charge les espaces de noms guid, ce paramètre est ignoré. Le pointeur ne doit pas avoir la valeur NULL.
[in] pValue
Pointeur vers la nouvelle valeur de la variable d’environnement du microprogramme.
[in] nSize
Taille de la mémoire tampon pValue , en octets. À moins que l’attribut VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS ou VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS variable soit défini via dwAttributes, la définition de cette valeur sur zéro entraîne la suppression de cette variable.
[in] dwAttributes
Masque de bits pour définir les attributs de variable UEFI associés à la variable. Voir également UEFI Spec 2.3.1, Section 7.2.
| Valeur | Signification |
|---|---|
|
La variable d’environnement du microprogramme est stockée dans une mémoire non volatile (par exemple, NVRAM). |
|
La variable d’environnement du microprogramme est accessible pendant le service de démarrage. |
|
La variable d’environnement du microprogramme est accessible au moment de l’exécution.
Note Les variables avec cet ensemble d’attributs doivent également avoir VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS défini.
|
|
Indique les erreurs matérielles rencontrées lors de l’exécution. |
|
Indique une exigence d’authentification qui doit être remplie avant d’écrire dans cette variable d’environnement de microprogramme. Pour plus d’informations, consultez la spécification UEFI 2.3.1. |
|
Indique les exigences d’authentification et d’horodatage qui doivent être remplies avant d’écrire dans cette variable d’environnement de microprogramme. Lorsque cet attribut est défini, la mémoire tampon, représentée par pValue, commence par un instance d’un descripteur complet (et sérialisé) EFI_VARIABLE_AUTHENTICATION_2. Pour plus d’informations, consultez la spécification UEFI 2.3.1. |
|
Ajoutez une variable d’environnement existante avec la valeur pValue. Si le microprogramme ne prend pas en charge l’opération, SetFirmwareEnvironmentVariableEx retourne ERROR_INVALID_FUNCTION. |
Valeur retournée
Si la fonction réussit, la valeur de retour est une valeur différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. Les codes d’erreur possibles incluent ERROR_INVALID_FUNCTION.
Remarques
À compter de Windows 10 version 1803, les applications Windows universelles peuvent lire et écrire des variables de microprogramme UEFI. Pour plus d’informations, consultez Accéder aux variables de microprogramme UEFI à partir d’une application Windows universelle .
À compter de Windows 10 version 1803, la lecture des variables de microprogramme UEFI est également prise en charge à partir des pilotes UMDF (User-Mode Driver Framework). L’écriture de variables de microprogramme UEFI à partir de pilotes UMDF n’est pas prise en charge.
Pour écrire une variable d’environnement de microprogramme, le compte d’utilisateur sous lequel l’application s’exécute doit avoir le privilège SE_SYSTEM_ENVIRONMENT_NAME . Une application Windows universelle doit être exécutée à partir d’un compte d’administrateur et respecter les exigences décrites dans Accéder aux variables de microprogramme UEFI à partir d’une application Windows universelle.
La méthode correcte pour modifier les attributs d’une variable consiste à supprimer la variable et à la recréer avec des attributs différents.
L’ensemble exact des variables d’environnement du microprogramme est déterminé par le microprogramme de démarrage. L’emplacement de ces variables d’environnement est également spécifié par le microprogramme. Par exemple, sur un système UEFI, NVRAM contient des variables d’environnement de microprogramme qui spécifient les paramètres de démarrage du système. Pour plus d’informations sur les variables spécifiques utilisées, consultez la spécification UEFI. Pour plus d’informations sur UEFI et Windows, consultez UEFI et Windows.
Les variables de microprogramme ne sont pas prises en charge sur un système BIOS hérité. La fonction SetFirmwareEnvironmentVariableEx échoue toujours sur un système BIOS hérité, ou si Windows a été installé à l’aide du BIOS hérité sur un système qui prend en charge à la fois le BIOS hérité et UEFI. Pour identifier ces conditions, appelez la fonction avec un nom d’environnement de microprogramme factice, tel qu’une chaîne vide (« ») pour le paramètre lpName et un GUID factice tel que «{00000000-0000-0000-0000-000000000000} » pour le paramètre lpGuid . Sur un système BIOS hérité ou sur un système qui prend en charge à la fois le BIOS hérité et l’UEFI où Windows a été installé à l’aide du BIOS hérité, la fonction échoue avec ERROR_INVALID_FUNCTION. Sur un système UEFI, la fonction échoue avec une erreur spécifique au microprogramme, telle que ERROR_NOACCESS, pour indiquer que l’espace de noms GUID factice n’existe pas.
Notes
L’en-tête winbase.h définit SetFirmwareEnvironmentVariableEx comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Client minimal pris en charge | Windows 8 [applications de bureau | Applications UWP] |
| Serveur minimal pris en charge | Windows Server 2012 [applications de bureau | Applications UWP] |
| Plateforme cible | Windows |
| En-tête | winbase.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
Accéder aux variables de microprogramme UEFI à partir d’une application Windows universelle
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour