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 dans des espaces de noms en fonction des GUID de leur fournisseur. Certaines plateformes matérielles peuvent ne pas prendre en charge les GUID du fournisseur. Sur ces plateformes, toutes les variables sont regroupées dans un espace de noms commun et le paramètre VendorGuid est ignoré.
[out, optional] Value
Pointeur vers une mémoire tampon allouée à 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 pointé par ce paramètre contient la taille, en octets, de la mémoire tampon value fournie par l’appelant. 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 est le nombre d’octets de données écrites dans la mémoire tampon Value . 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 la section Notes.
Valeur retournée
ExGetFirmwareEnvironmentVariable retourne STATUS_SUCCESS si elle réussit. Les valeurs de retour possibles incluent les codes d’erreur status suivants.
| Code de retour | 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 Value 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 qui sont passées entre l’environnement de microprogramme de démarrage implémenté dans la plateforme matérielle et les chargeurs de système d’exploitation et autres logiciels qui s’exécutent dans l’environnement de microprogramme.
L’ensemble des 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 les 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 de 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 à la fois le BIOS hérité et UEFI. Pour identifier ces conditions, utilisez d’abord uuidgen ou un outil similaire pour générer statiquement un GUID unique aléatoire. 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 à la fois le BIOS hérité et l’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, telle que 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 dans l’emplacement désigné par Attributes. 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 de 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 .
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible à partir de Windows 8. |
| Plateforme cible | Universal |
| 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