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 contenente 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 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 a 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 buffer Valore fornito dal chiamante. 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 è il numero di byte di dati scritti nel buffer Value . Se la routine restituisce STATUS_BUFFER_TOO_SMALL, *ValueLength è la dimensione del buffer necessaria.
[out, optional] Attributes
Puntatore a un percorso 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 ha bisogno degli attributi. Per altre informazioni, vedere la sezione Osservazioni.
Valore restituito
ExGetFirmwareEnvironmentVariable restituisce STATUS_SUCCESS se ha esito positivo. I valori restituiti possibili includono i codici di stato degli errori 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. |
Commenti
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 eseguiti 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 del firmware estendibile unificata 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 hanno sempre esito negativo su una piattaforma basata su BIOS legacy; non riescono 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 staticamente. Chiamare quindi questa routine per cercare un nome di variabile specifico, specificando tale GUID come parametro VendorGuid .
In una piattaforma basata su BIOS legacy o su una piattaforma che supporta bios legacy e 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 del 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 puntata da 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 l'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 .
Requisiti
| 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 |
Vedi anche
ExSetFirmwareEnvironmentVariable