GetFirmwareEnvironmentVariableA, fonction (winbase.h)

  • Article

Récupère la valeur de la variable d’environnement du microprogramme spécifiée.

Syntaxe

DWORD GetFirmwareEnvironmentVariableA(
  [in]  LPCSTR lpName,
  [in]  LPCSTR lpGuid,
  [out] PVOID  pBuffer,
  [in]  DWORD  nSize
);

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-xxxxxxxxxxxxxx} » où « x » représente une valeur hexadécimale.

[out] pBuffer

Pointeur vers une mémoire tampon qui reçoit la valeur de la variable d’environnement du microprogramme spécifiée.

[in] nSize

Taille de la mémoire tampon pBuffer , en octets.

Valeur retournée

Si la fonction réussit, la valeur de retour est le nombre d’octets stockés dans la mémoire tampon pBuffer .

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 (Unified Extensible Firmware Interface). Pour plus d’informations, consultez Accéder aux variables de microprogramme UEFI à partir d’une application Windows universelle .

Pour lire une variable d’environnement de microprogramme, le compte d’utilisateur sous lequel l’application s’exécute doit disposer du 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.

À compter de Windows 10 version 1803, la lecture des variables UEFI (Unified Extensible Firmware Interface) est également prise en charge à partir des pilotes UMDF (User-Mode Driver Framework). L’écriture de variables UEFI à partir de pilotes UMDF n’est pas prise en charge.

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 GetFirmwareEnvironmentVariable é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.

Si vous créez une application de sauvegarde, vous pouvez utiliser cette fonction pour enregistrer tous les paramètres de démarrage du système afin qu’ils puissent être restaurés à l’aide de la fonction SetFirmwareEnvironmentVariable si nécessaire.

GetFirmwareEnvironmentVariable est l’équivalent en mode utilisateur de la routine en mode noyau ExGetFirmwareEnvironmentVariable .

Notes

L’en-tête winbase.h définit GetFirmwareEnvironmentVariable 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 Vista, Windows XP avec SP1 [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2003 [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

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable

Fonctions d’information système