Funzione ExGetFirmwareEnvironmentVariable (wdm.h)
La routine ExGetFirmwareEnvironmentVariable ottiene il valore della variabile di ambiente del firmware di sistema specificata.
Sintassi
NTSTATUS ExGetFirmwareEnvironmentVariable(
[in] PUNICODE_STRING VariableName,
[in] LPGUID VendorGuid,
[out, optional] PVOID Value,
[in, out] PULONG ValueLength,
[out, optional] PULONG Attributes
);
Parametri
[in] VariableName
Puntatore a una struttura UNICODE_STRING che contiene il nome della variabile di ambiente specificata.
[in] VendorGuid
Puntatore a un GUID che identifica il fornitore associato alla variabile di ambiente specificata. Le variabili di ambiente vengono raggruppate in spazi dei nomi in base ai GUID del fornitore. Alcune piattaforme hardware potrebbero non supportare i GUID del fornitore. In queste piattaforme tutte le variabili vengono raggruppate in uno spazio dei nomi comune e il parametro vendorGuid viene ignorato.
[out, optional] Value
Puntatore a un buffer allocato dal chiamante in cui la routine scrive il valore della variabile di ambiente specificata.
[in, out] ValueLength
Puntatore a una posizione contenente le dimensioni del buffer. Nella voce, la posizione a cui punta questo parametro contiene le dimensioni, in byte, del chiamante fornito buffer value. Prima di uscire, la routine scrive in questa posizione le dimensioni, in byte, del valore della variabile. Se la routine restituisce STATUS_SUCCESS, il valore di output *ValueLength corrisponde al numero di byte di dati scritti nel buffer value. Se la routine restituisce STATUS_BUFFER_TOO_SMALL, *ValueLength è la dimensione del buffer richiesta.
[out, optional] Attributes
Puntatore a una posizione in cui la routine scrive gli attributi della variabile di ambiente specificata. Questo parametro è facoltativo e può essere impostato su NULL se il chiamante non necessita degli attributi. Per altre informazioni, vedere Osservazioni.
Valore restituito
ExGetFirmwareEnvironmentVariable restituisce STATUS_SUCCESS se ha esito positivo. I valori restituiti possibili includono i codici di stato di errore seguenti.
| Codice restituito | Descrizione |
|---|---|
| STATUS_INSUFFICIENT_RESOURCES | Le risorse di sistema disponibili non sono sufficienti per completare l'operazione richiesta. |
| STATUS_BUFFER_TOO_SMALL | Il buffer valore è troppo piccolo. |
| STATUS_VARIABLE_NOT_FOUND | La variabile richiesta non esiste. |
| STATUS_INVALID_PARAMETER | Uno dei parametri non è valido. |
| STATUS_NOT_IMPLEMENTED | Questa routine non è supportata in questa piattaforma. |
| STATUS_UNSUCCESSFUL | Il firmware ha restituito un errore non riconosciuto. |
Osservazioni
Le variabili di ambiente del firmware di sistema contengono valori di dati passati tra l'ambiente del firmware di avvio implementato nella piattaforma hardware e i caricatori del sistema operativo e altri software in esecuzione nell'ambiente firmware.
Il set di variabili di ambiente del firmware disponibili in una piattaforma hardware dipende dal firmware di avvio. La posizione di queste variabili di ambiente viene specificata anche dal firmware. Ad esempio, in una piattaforma basata su UEFI, NVRAM contiene variabili di ambiente del firmware che specificano le impostazioni di avvio del sistema. Per informazioni sulle variabili specifiche usate, vedere la specifica dell'interfaccia unificata del firmware estendibile nel sito Web UEFI. Per altre informazioni su UEFI e Windows, vedere UEFI e Windows.
Le variabili di ambiente del firmware non sono supportate in una piattaforma basata su BIOS legacy. Le chiamate a ExGetFirmwareEnvironmentVariable sempre non riescono in una piattaforma legacy basata su BIOS; hanno esito negativo anche se Windows è stato installato usando il BIOS legacy in una piattaforma che supporta sia BIOS legacy che UEFI. Per identificare queste condizioni, usare prima uuidgen o uno strumento simile per generare un GUID univoco casuale in modo statico. Chiamare quindi questa routine per cercare un nome di variabile specifico, specificando tale GUID come parametro VendorGuid.
In una piattaforma legacy basata su BIOS o in una piattaforma che supporta sia BIOS legacy che UEFI, ma in cui Windows è stato installato usando il BIOS legacy, la funzione avrà esito negativo con STATUS_NOT_IMPLEMENTED. In una piattaforma basata su UEFI, la funzione avrà esito negativo con un errore specifico per il firmware, ad esempio STATUS_VARIABLE_NOT_FOUND, per indicare che lo spazio dei nomi GUID fittizio non esiste.
Se il chiamante specifica un parametro attributi non NULL, la routine scrive gli attributi della variabile di ambiente del firmware di sistema specificata nella posizione a cui punta Attributi. La versione 2.3.1 della specifica UEFI definisce gli attributi seguenti per le variabili di ambiente del firmware.
| Nome variabile | Valore |
|---|---|
| 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 |
Questi valori di attributo sono definiti come bit di flag. Il valore scritto nella variabile ULONG a cui punta Attributi è zero o or bit per bit di uno o più attributi nella tabella precedente. Per altre informazioni, vedere la specifica UEFI nel sito Web UEFI.
Se si crea un archivio dati di backup, è possibile usare questa funzione per salvare tutte le impostazioni di avvio per la piattaforma in modo che possano essere ripristinate chiamando la routine ExSetFirmwareEnvironmentVariable, se necessario.
ExGetFirmwareEnvironmentVariable è l'equivalente in modalità kernel della funzione GetFirmwareEnvironmentVariable win32 GetFirmwareEnvironmentVariable.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Disponibile a partire da Windows 8. |
| piattaforma di destinazione | Universale |
| intestazione | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| libreria | NtosKrnl.lib |
| dll | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
Vedere anche
ExSetFirmwareEnvironmentVariable