ExGetFirmwareEnvironmentVariable, fonction (wdm.h)
La routine ExGetFirmwareEnvironmentVariable obtient la valeur de la variable d’environnement du microprogramme système spécifiée.
Syntaxe
NTSTATUS ExGetFirmwareEnvironmentVariable(
[in] PUNICODE_STRING VariableName,
[in] LPGUID VendorGuid,
[out, optional] PVOID Value,
[in, out] PULONG ValueLength,
[out, optional] PULONG Attributes
);
Paramètres
[in] VariableName
Pointeur vers une structure UNICODE_STRING qui contient le nom de la variable d’environnement spécifiée.
[in] VendorGuid
Pointeur vers un GUID qui identifie le fournisseur associé à la variable d’environnement spécifiée. Les variables d’environnement sont regroupées en espaces de noms en fonction de leurs GUID de fournisseur. Certaines plateformes matérielles peuvent ne pas prendre en charge les GUID du fournisseur. Sur ces plateformes, toutes les variables sont regroupées en un, un espace de noms commun et le paramètre VendorGuid est ignoré.
[out, optional] Value
Pointeur vers une mémoire tampon allouée par l’appelant dans laquelle la routine écrit la valeur de la variable d’environnement spécifiée.
[in, out] ValueLength
Pointeur vers un emplacement qui contient la taille de la mémoire tampon. Lors de l’entrée, l’emplacement vers lequel pointe ce paramètre contient la taille, en octets, de la mémoire tampon valeur fournie par l’appelant tampon. Avant de quitter, la routine écrit à cet emplacement la taille, en octets, de la valeur de la variable. Si la routine retourne STATUS_SUCCESS, la valeur de sortie *ValueLength correspond au nombre d’octets de données écrites dans la mémoire tampon Valeur. Si la routine retourne STATUS_BUFFER_TOO_SMALL, *ValueLength est la taille de mémoire tampon requise.
[out, optional] Attributes
Pointeur vers un emplacement dans lequel la routine écrit les attributs de la variable d’environnement spécifiée. Ce paramètre est facultatif et peut être défini sur NULL si l’appelant n’a pas besoin des attributs. Pour plus d’informations, consultez Remarques.
Valeur de retour
ExGetFirmwareEnvironmentVariable retourne STATUS_SUCCESS si elle réussit. Les valeurs de retour possibles incluent les codes d’état d’erreur suivants.
| Retourner le code | Description |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Les ressources système disponibles sont insuffisantes pour terminer l’opération demandée. |
| STATUS_BUFFER_TOO_SMALL | La mémoire tampon valeur est trop petite. |
| STATUS_VARIABLE_NOT_FOUND | La variable demandée n’existe pas. |
| STATUS_INVALID_PARAMETER | L’un des paramètres n’est pas valide. |
| STATUS_NOT_IMPLEMENTED | Cette routine n’est pas prise en charge sur cette plateforme. |
| STATUS_UNSUCCESSFUL | Le microprogramme a retourné une erreur non reconnue. |
Remarques
Les variables d’environnement du microprogramme système contiennent des valeurs de données transmises entre l’environnement de microprogramme de démarrage implémenté dans la plateforme matérielle et les chargeurs du système d’exploitation et d’autres logiciels qui s’exécutent dans l’environnement du microprogramme.
L’ensemble de variables d’environnement de microprogramme disponibles dans une plateforme matérielle dépend du microprogramme de démarrage. L’emplacement de ces variables d’environnement est également spécifié par le microprogramme. Par exemple, sur une plateforme 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 des variables spécifiques utilisées, consultez la spécification de l’interface de microprogramme extensible unifiée sur le site web UEFI. Pour plus d’informations sur UEFI et Windows, consultez UEFI et Windows.
Les variables d’environnement du microprogramme ne sont pas prises en charge sur une plateforme BIOS héritée. Les appels à ExGetFirmwareEnvironmentVariable échouent toujours sur une plateforme BIOS héritée ; ils échouent également si Windows a été installé à l’aide du BIOS hérité sur une plateforme qui prend en charge le BIOS hérité et UEFI. Pour identifier ces conditions, utilisez d’abord uuidgen ou un outil similaire pour générer un GUID unique aléatoire de manière statique. Appelez ensuite cette routine pour rechercher un nom de variable spécifique, en fournissant ce GUID comme paramètre VendorGuid.
Sur une plateforme BIOS héritée ou sur une plateforme qui prend en charge le BIOS hérité et UEFI, mais dans laquelle Windows a été installé à l’aide du BIOS hérité, la fonction échoue avec STATUS_NOT_IMPLEMENTED. Sur une plateforme UEFI, la fonction échoue avec une erreur spécifique au microprogramme, par exemple STATUS_VARIABLE_NOT_FOUND, pour indiquer que l’espace de noms GUID factice n’existe pas.
Si l’appelant spécifie un paramètre attributs non NULL, la routine écrit les attributs de la variable d’environnement du microprogramme système spécifiée à l’emplacement vers lequel pointe Attributs. La version 2.3.1 de la spécification UEFI définit les attributs suivants pour les variables d’environnement du microprogramme.
| Nom de la variable | Valeur |
|---|---|
| EFI_VARIABLE_NON_VOLATILE | 0x00000001 |
| EFI_VARIABLE_BOOTSERVICE_ACCESS | 0x00000002 |
| EFI_VARIABLE_RUNTIME_ACCESS | 0x00000004 |
| EFI_VARIABLE_HARDWARE_ERROR_RECORD | 0x00000008 |
| EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS | 0x00000010 |
| EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS | 0x00000020 |
| EFI_VARIABLE_APPEND_WRITE | 0x00000040 |
Ces valeurs d’attribut sont définies en tant que bits d’indicateur. La valeur écrite dans la variable ULONG pointée par Attributes est égale à zéro ou au niveau du bit OR d’un ou plusieurs attributs dans le tableau précédent. Pour plus d’informations, consultez la spécification UEFI sur le site web UEFI.
Si vous créez un magasin de données de sauvegarde, vous pouvez utiliser cette fonction pour enregistrer tous les paramètres de démarrage de la plateforme afin qu’ils puissent être restaurés en appelant la routine ExSetFirmwareEnvironmentVariable si nécessaire.
ExGetFirmwareEnvironmentVariable est l’équivalent en mode noyau de la fonction Win32 GetFirmwareEnvironmentVariable.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 8. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
Voir aussi
ExSetFirmwareEnvironmentVariable